92 lines
6.2 KiB
Markdown
92 lines
6.2 KiB
Markdown
# Reusable library candidate review — 2026-09-10
|
|
|
|
Codex-9e8r6t `/root`. This is a preimplementation falsification brief for the
|
|
independent Codex-956atf library proposal, not a ratified semantic contract.
|
|
The updated user objective explicitly requires reusable model libraries. Existing
|
|
source includes and same-project sequence reuse do not close that requirement.
|
|
|
|
## Evidence and engineering need
|
|
|
|
Current `SourceBundle` compiles includes into one Project and one global alias
|
|
table. `Project` has no library revision, instantiation correspondence or update
|
|
baseline. Core reference visitors distinguish typed reference fields from text;
|
|
their existing behavior must survive any extension.
|
|
|
|
Capella separates shared library references from reusable model patterns. Its
|
|
library can support several projects and other libraries, with reading and
|
|
editing modes. This serves shared data definitions as well as reusable catalogs.
|
|
[Official library concepts](https://github.com/eclipse-capella/capella/blob/master/doc/plugins/org.polarsys.capella.re.doc/html/09.%20Libraries/9.1.%20Introduction.mediawiki).
|
|
|
|
Its pattern update workflow previews differences and allows individual merges.
|
|
The valuable behavior is a reviewed change with identifiable effects, including
|
|
new members and renamed existing members.
|
|
[Official REC/RPL update workflow](https://github.com/eclipse-capella/capella/blob/master/doc/plugins/org.polarsys.capella.re.doc/html/08.%20Replicable%20Element%20(REC-RPL)/8.3.%20Update%20REC-RPL.mediawiki).
|
|
|
|
The documented restrictions include missing referenced libraries and replacing
|
|
a library version while its project is open. These motivate testing a portable,
|
|
pinned snapshot and explicit update transaction in Studio; that is a proposed
|
|
improvement, not a claim about newer Capella versions.
|
|
[Official restrictions](https://github.com/eclipse-capella/capella/blob/master/doc/plugins/org.polarsys.capella.re.doc/html/09.%20Libraries/9.4.%20Usage%20Restrictions.mediawiki).
|
|
|
|
SysML's namespace/import semantics distinguish member identity and visibility.
|
|
This is useful evidence for separating a readable qualified name from an object
|
|
identity; adopting those ideas would not establish SysML conformance.
|
|
[SysML 2.0, section 7.5](https://www.omg.org/spec/SysML/2.0/Language/PDF).
|
|
|
|
## Alternatives that must remain distinct
|
|
|
|
| Candidate | Useful capability | Failure to probe |
|
|
| --- | --- | --- |
|
|
| Copy source/includes | Simple portable templates and normal local editing | No recorded correspondence or maintained update; repeat aliases/UUIDs collide. |
|
|
| Live external references | One authoritative shared definition | Missing remote files, moving versions and offline reproducibility; local customization needs separate semantics. |
|
|
| Generic definition/usage metamodel | Rich specialization and instance semantics | Large foundational rewrite; ordinary OA/SA records and source updater become dependent on unresolved new semantics. |
|
|
| Pinned typed package plus explicit use/copy mappings | Offline reproduction, ordinary local records, reviewed updates | Duplicate representations, historical identity confusion and misleading generic merge can invalidate the apparent simplicity. |
|
|
|
|
The last candidate warrants an experiment, but has not yet won independent
|
|
review. Shared immutable definitions and editable pattern instances are separate
|
|
user needs; one cannot silently substitute for the other.
|
|
|
|
## Falsification cases and acceptance boundaries
|
|
|
|
- Reuse the same package twice in one project and once in another. Preserve
|
|
origin identities, give editable instances distinct local identities, and keep
|
|
all internal/external bindings explicit. Repeated names must not select by the
|
|
first alias or UUID. A new package revision must not change an open project.
|
|
- Extract a process with repeated occurrences, ports, scenario bindings,
|
|
diagrams, artifacts and an OA/SA trace. Define ownership closure separately
|
|
from external dependencies; neither omit needed references nor capture the
|
|
whole surrounding system. Show external connections requiring user binding.
|
|
- A library revision must be reproducible offline. Its identity, schema and
|
|
content pin must survive text/API/export/reopen. A locator is not a content
|
|
identity. Loading or evaluating a supplied package must not fetch or execute.
|
|
- Reidentify a local instance member. Its foreign origin and historical baseline
|
|
UUIDs must remain unchanged; local mapping targets and ordinary live references
|
|
must follow it. Deleting a foreign member must produce a reviewable update,
|
|
not a dangling reference or a name-based match to another object.
|
|
- Compare old package, new package and local instance explicitly. Probe upstream
|
|
rename versus local description edit, conflicting rename, deleted locally
|
|
customized member, reordered occurrences, changed constructor and a new
|
|
mandatory binding. A whole-record equality merge must not discard unrelated
|
|
local edits. If a conflict is intentionally coarse, the UI must expose that
|
|
exact scope before acceptance.
|
|
- Keep local geometry, artifact evidence and engineering mappings when taking an
|
|
unrelated upstream semantic change. Conversely, do not describe excluded
|
|
layout/trace content as synchronized. Detachment must preserve the current
|
|
usable model and remove only the explicit maintenance relationship.
|
|
- Validate the complete model and writeback before committing a package update.
|
|
Source-budget failure, stale revision, invalid binding and cancellation must
|
|
retain the original Project, complete SourceBundle, raw draft and history.
|
|
Accepted update is one Undo/Redo boundary with exact UUID/source restoration.
|
|
- Large catalogs need bounded contextual browsing: package/version → exported
|
|
task or definition → required bindings → impact. A single flattened list of
|
|
every imported identity would violate the current user guidance.
|
|
|
|
## Next decision
|
|
|
|
Receive the independent package proposal, compare its concrete record/source
|
|
contract against these cases, then run a small pure-core experiment before any
|
|
broad schema migration. Quantity and calculation definitions must be eligible
|
|
for the chosen reuse contract without interpreting descriptive expression text
|
|
or assuming that all UUID-shaped strings are live references. Native creation
|
|
and scenario acceptance continue independently during this design investigation.
|