# 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.