From 63d53e45d4fe8b856ba788265476e36441f5727c Mon Sep 17 00:00:00 2001 From: Yordis Prieto Date: Sun, 25 Oct 2026 10:51:05 -0400 Subject: [PATCH] chore(docs): keep architectural declarations distinct from behavior Signed-off-by: Yordis Prieto --- docs/README.md | 2 + .../architecture-resource-roadmap.md | 10 + .../architecture-resource-coverage.md | 2 +- .../system-relationship-acceptance.md | 142 ++++++++++++ .../system-relationship-contracts.md | 203 ++++++++++++++++++ 5 files changed, 358 insertions(+), 1 deletion(-) create mode 100644 docs/reference/system-relationship-acceptance.md create mode 100644 docs/reference/system-relationship-contracts.md diff --git a/docs/README.md b/docs/README.md index c1396e15..3ba3e577 100644 --- a/docs/README.md +++ b/docs/README.md @@ -41,6 +41,8 @@ Resource contracts and acceptance: - [Architecture resource coverage](reference/architecture-resource-coverage.md) - [Domain-scoped listing](reference/domain-scoped-listing.md) +- [System relationship contract proposal](reference/system-relationship-contracts.md) +- [System relationship acceptance requirements](reference/system-relationship-acceptance.md) - [Channel and DataStore contracts](reference/channel-and-datastore-contracts.md) - [Channel and DataStore acceptance fixture](reference/channel-and-datastore-acceptance.md) - [Specification and API contracts](reference/specification-and-api-contracts.md) diff --git a/docs/explanation/architecture-resource-roadmap.md b/docs/explanation/architecture-resource-roadmap.md index a33b8dba..101e6b33 100644 --- a/docs/explanation/architecture-resource-roadmap.md +++ b/docs/explanation/architecture-resource-roadmap.md @@ -124,6 +124,16 @@ selectors require explicit rebinding. The typed boundary and read-only review surface. Remote connectors and additional format compilers remain separate milestones. +## Proposed system relationship layer + +The [system relationship proposal](../reference/system-relationship-contracts.md) +builds on existing Component and ExternalSystem boundaries. Its +[acceptance requirements](../reference/system-relationship-acceptance.md) +keep authored declarations distinct from checked behavioral paths and runtime +evidence. This is a specification milestone, not native implementation or +completed acceptance. Richer grouping and actor-interaction boundaries remain +explicit in the proposal. + ## Atlas Linter comes after the architecture resources The [remaining contract boundaries](../reference/architecture-resource-coverage.md#remaining-contract-boundaries) diff --git a/docs/reference/architecture-resource-coverage.md b/docs/reference/architecture-resource-coverage.md index 0e190bb1..4b8e92b1 100644 --- a/docs/reference/architecture-resource-coverage.md +++ b/docs/reference/architecture-resource-coverage.md @@ -31,7 +31,7 @@ version strings do not replace these selectors. See | Area | Existing representation | Remaining boundary | | --- | --- | --- | | Strategic membership | Domain project, Subdomain domain and context realizations are native references. [Domain-scoped listing](domain-scoped-listing.md) preserves exact strategic versions and considers every realization; ordinary entity scope remains namespace-derived. | Arbitrary domain nesting and shared authored system/service membership have no dedicated fields. Listing does not establish authored membership, change project-validation scope or add a Domain version selector to Studio. | -| System and service relationships | Component members can select other Components and ExternalSystems, with ordinary reference discovery. | Dedicated grouping levels, labeled directed system relationships and system-level actor interactions require a contract decision. Containment is Component-owned; ExternalSystem has no members field, so external-system-owned membership also remains a contract decision. | +| System and service relationships | Component members can select other Components and ExternalSystems, with ordinary reference discovery. | The [system relationship proposal](system-relationship-contracts.md) and [acceptance requirements](system-relationship-acceptance.md) specify a bounded declaration layer; they do not establish implemented support. Dedicated grouping levels and system-level actor interactions remain separate boundaries. Containment is Component-owned; ExternalSystem has no members field, so external-system-owned membership also remains outside current support. | | Communication | API roles/providers/usages, Processor calls and Channel bindings to actual observations are supported. | General authored send/receive and conditional-trigger declarations before behavioral mapping have no native relationship contract. Retained source declarations do not establish executable paths. | | Metadata and agents | Registered annotations include links, code repository/path/symbol/ref provenance, tags and lifecycle status. | Lifecycle effective dates and agent model/tool declarations need dedicated contracts. Arbitrary metadata references are not recursively indexed. See [annotations](../../proto/trogonatlas/annotation/v1alpha1/annotations.proto). | | Business data | Schema fields, nested shapes, schema type references and identity-derivation annotations are available. | Business identifier roles, foreign entity/property selections, relationship labels and general aggregate intent are not supplied by type reuse. See [field schema](../../proto/trogonatlas/eventmodel/v1alpha1/fields.proto). | diff --git a/docs/reference/system-relationship-acceptance.md b/docs/reference/system-relationship-acceptance.md new file mode 100644 index 00000000..e39d833d --- /dev/null +++ b/docs/reference/system-relationship-acceptance.md @@ -0,0 +1,142 @@ +# System relationship acceptance requirements + +Status: proposed executable acceptance requirements for the +[contract](system-relationship-contracts.md), not implemented and not run. +Logical fixture notation below is not current manifest syntax or an available +RPC payload. No backend, CLI/MCP, Studio or runtime acceptance is claimed. + +## Fixture and evidence + +Materialize each case in a fresh registered namespace, using exact native +version `1` unless a case names another version. Logical namespace `commerce` +stands for the recorded fixture namespace. Capture actual returned owner UIDs, +ConnectionIds and etags; symbolic occurrence names below are not submitted IDs. +Retain requests, responses, backend revision, caller/authorized namespaces, +branch, checked scope, completeness and storage changes for assertions. + +Create targets first, then source owners, then responsibility/Decision/Document +subjects using returned selectors. A known same-incarnation target can be used +in a guarded final-overlay batch. Do not predict the UID of a newly created owner. +Each fixture also satisfies unrelated existing entity admission rules. + +| Exact entity | Fixture declaration | +| --- | --- | +| Component `commerce/checkout@1` | Actual deployable checkout unit. Members include an exact Processor, a UI, a Specification and Component `commerce/worker@1`. These remain raw references. | +| Component `commerce/worker@1` | Actual deployable worker unit; shares the Processor member intentionally. No exclusive hosting inference. | +| ExternalSystem `commerce/provider@1` | Third-party integration boundary, with no members. | +| Component `commerce/checkout@2` | A separate breaking-change version for exact-version assertions. | +| `checkout@1` relationships | `out_a` and `out_b` both target ExternalSystem `provider@1`, label “submits orders”, with equal doc. `local` targets Component `worker@1`. | +| `provider@1` relationships | `back` targets Component `checkout@1`, label “notifies”; `peer` targets a separately created ExternalSystem `commerce/auditor@1`. | +| `worker@1` relationships | `next` targets Component `checkout@2`. | +| Team/Person and Decision/Document | Valid existing entities select `out_a` through full ConnectionRef. Also include an independent entity-level subject for `checkout@1` to detect accidental expansion. | + +The graph covers all allowed endpoint kind combinations and opposite arrows +without generating an inverse declaration automatically. No broker, network +call, runtime service, source registration or actor entity is needed. + +## Required public outcomes + +Implement executable backend/service tests through public authoring and query +surfaces. Name their actual requests in retained evidence; do not substitute +core-only tests for persistence, authorization or transport results. + +| Case | Assertions | +| --- | --- | +| Create/read | Each relationship persists its typed target, label/doc presence, order and assigned ID. Owner UID is server-owned. `out_a` and `out_b` have distinct IDs despite equal content. | +| Direction | Outgoing checkout references contain `out_a`, `out_b`, `local`; provider references contain `back`, `peer`. Incoming provider references retain both checkout occurrences. A relation from provider to checkout does not reverse or satisfy a checkout declaration. | +| Reference provenance | Each hit has exact `from`, `from_uid`, `connection_id`, typed `to` and current diagnostic field path. Reordering changes paths where needed, preserving IDs. No member reference acquires a ConnectionId. | +| Exact versions | Incoming lookup of `checkout@1` finds `back`; lookup of `checkout@2` finds `next`. No latest, superseding-version or version-family match. | +| Subject lookup | Responsibility, Decision and Document direct/reverse queries for `out_a` return only exact matching declarations. `out_b`, owner entity, endpoint entity and member selections never inherit those matches. | +| Subject context | Resolver checks complete persisted inventory and occurrence role. A Component/ExternalSystem owner alone does not authorize a member/index/ancestry connection subject. Target hydration is separate from identifying a retained occurrence. | +| Impact | Returned paths retain relationship provenance; declared cycles terminate under existing traversal bounds. Owner-level impact need not enumerate every parallel path. It reports graph reachability without a runtime-dependency claim. | +| Native export/reapply | In the same store, preserve UID/local IDs, typed refs, exact versions, labels/doc presence, ordering and unchanged etags on no-op. Truncation cannot be passed as a complete reapply artifact. | +| Native surfaces | Guarded authoring, validation/preview and inspection through CLI and MCP preserve full selectors, errors and incomplete state. Record native backend transport evidence independently of any mocked client tests. | +| Revision floor | Old writer revisions are refused before they can drop relationships. Current writers preserve fields on unrelated edits. | + +## Admission and lifecycle matrix + +Each rejected mutation must leave owner content, etag, UID, IDs and branch state +unchanged. Test observable stored effects after rejection, not just an error code. + +| Input or operation | Expected result | +| --- | --- | +| Missing/multiple target alternatives; unsupported kind; malformed or nonpositive exact Id | Atomic rejection. No generic EntityRef or source-handle fallback. | +| Self-target exact kind/key/version | Reject; different versions are distinct targets. Cycles between different endpoints remain valid descriptive declarations. | +| Missing/blank/over-limit label; present blank/over-limit doc | Reject under CatalogTitle/CatalogText rules. Valid Unicode at encoded-byte limit succeeds; limit plus one fails. | +| Repeated equal target/label/doc | Accept distinct IDs, including parallel occurrences within one owner; never deduplicate by content. | +| New-owner supplied ID | Accept valid non-nil lowercase hyphenated UUID; reject malformed/duplicate IDs, including duplicates across roles. | +| Existing-owner unknown supplied ID; target change retaining ID; identity stripping in edited content | Reject; never match by index, label or target. | +| Reorder or label/doc edit | Preserve IDs and subject resolution. Label wording is descriptive, not a role/target change. | +| Add occurrence | Omit ID; backend returns fresh ID. Preview ID is unreserved and must not be reused as an active ID on apply. | +| Remove/re-add same content in separate guarded writes | Removed selector becomes unresolved; new occurrence receives fresh ID; sibling subjects still resolve. | +| Exact-content id-less manifest reapply | No-op exception preserves stored IDs/UID/etag. An edited id-less manifest rejects. | +| Owner delete/recreate | New UID prevents old ConnectionRef resolution even if a local ID is supplied again. Plain endpoint refs retain existing exact-key recreation semantics. | +| Clone/new version | New owner UID and exact owner key; incoming selectors stay on original. Local IDs may survive only in their new owner scope. | +| Missing/unreadable target on new or edited owner | Reject without hidden detail; inspect retained dangling owners independently. | +| Force-delete target | Preserve readable source declaration/ID and authored selector; target hydration is unavailable. Unrelated owner writes remain possible, but editing the dangling source requires repair. | +| Remove selected local relation | Existing incoming subjects become unresolved without retargeting to `out_b`. Safe deletion of the containing owner remains protected. | +| Retarget provider key under guards | Retargeted relationships receive fresh IDs; unaffected siblings retain IDs. Incoming ConnectionRefs to changed relationships remain unresolved until explicitly replaced. | +| Safe delete | Existing relationship and typed subject referrers block deletion. Hidden referrers block generically without hidden hydration. Final batch deletes consider all requested removals/remaining referrers. | +| Stale etag/preview/guard | Refuse or revalidate under guarded publication; no stale admission can publish an invalid endpoint or partial batch. Use deterministic write gates, not timing sleeps. | + +Branch tests must independently cover retained-ID edits, baseline-only removal, +branch-only addition, ordinary landing/rebase refusal to revive removed IDs, +explicit keep/take resolution renewing only restored IDs, whole-owner baseline +deletion with explicit branch restoration, and independent same-key creation +with distinct UIDs. Assert persisted identities and old selector outcomes after +each operation against the recorded branch base. + +## Authorization, bounds and failures + +Use separate owner and target namespaces with Reader, Writer and hidden-target +callers. Include hidden referrers outside the visible listing scope. Verify +absence of hidden labels, paths, titles, counts and existence in error payloads, +query totals, hydration and delete reports. + +| Case | Expected result | +| --- | --- | +| Reader mutation; hidden direct read | PERMISSION_DENIED; NOT_FOUND respectively. Catalog responsibility grants no additional permission. | +| Unreadable selected subject | Query fails without existence disclosure. A readable source can show its already authored target selector, with no hidden hydration. | +| Missing versus hidden target hydration | Same generic unavailable result for the restricted caller. Authorized stale UID/removed-ID diagnostics remain specific where safe. | +| Source write with target reference access | Succeeds without granting target write access. Authoring the opposite arrow still requires write access on its source owner. | +| Relationship ceiling | 1,024 valid relationships fit if other limits permit; 1,025 reject atomically. | +| Entity ceiling | Entire encoded entity at 1 MiB is admissible if other limits permit; above rejects. Lower existing ceilings remain effective. | +| Discovery rows | Component/ExternalSystem share the existing 5,000-row resource ceiling with other covered resource kinds. Cross-kind work cannot reset the budget. Exact authorized hydration still works beyond a display cap. | +| Occurrence/output ceilings | Shared 10,000 examined occurrences and 4,096 emitted records per request; exercise boundary and overflow with equal-endpoint repetitions and nested subject lookups. Internal scan pages and batch members cannot restart counters within a request. A new independent request receives fresh counters but its continuation token cannot bypass required complete-scan checks. | +| Discovery overflow | RESOURCE_EXHAUSTED, never an apparently complete empty list. Existing bounded impact/export/report incompleteness remains explicit and cannot establish absence. | +| Guard/report independence | Hidden or display-clipped referrers still protect deletion through the complete guard. Incomplete/failed guard refuses deletion. Preserve `referrers_incomplete` reporting contract without using a report as the safety decision. | +| Injected decode/backend/auth-service/timeout failure | Operational failure propagates; no successful absence result, model-error disguise or partial publication. | +| Source integration isolation | Reject source mapping/adoption of new occurrences, ownership of this field and whole-owner writes with current/proposed architectural relationships. Reject every Source create containing relationships, including a title-only mapping; assert no native entity or mapping-base publication. Existing-owner supported unrelated field-specific writes preserve local declarations. RELATIONSHIPS enum presence alone is insufficient admission. | + +## Grouping and human behavior boundaries + +These are negative acceptance assertions for the selected scope, not acceptance +of a future interaction feature. + +- Component membership still accepts supported exact entity references and + preserves shared members. No abstract group kind, transitive membership, + exclusivity, membership occurrence or behavioral validation rule is introduced. +- ExternalSystem still has no authored members. A “contains” relationship is + only wording, never containment, and no Component proxy is synthesized. +- Persona remains human, with descriptive `role`; no directory Person, principal, + agent or automation identity is inferred from it. +- Inspect existing CommandSlice persona/UI/command edge refs and UiSlice + persona/UI/source-ReadModel refs using exact current types. Repeated equal + source ReadModelEdge occurrences remain individually selected; storyboard + recurrence retains order. No `InteractionSlice` or `UI.persona` path is emitted. +- A label such as “sends” produces no Processor, AutomationSlice, event producer, + API provider exposure, Channel binding, message access or checked behavioral path. +- Empty declarations prove only absence of authored declarations in the checked + view. Accepted declarations and resolved model references prove no runtime call. + +## Completion evidence boundary + +Implementation completion requires maintained executable fixtures for the +selected native contract, public transport assertions and retained outputs for +these cases. Record test names/commands and their actual results at that time. +This document itself is a specification and reports no passing tests. + +Studio inspection/browser evidence, when supplied, must identify the native +backend, fixture and exact selectors. Mocked transport does not establish native +persistence. Runtime observations require separate deployment/instrumentation +evidence; no runtime proof is needed or supplied by this declaration contract. diff --git a/docs/reference/system-relationship-contracts.md b/docs/reference/system-relationship-contracts.md new file mode 100644 index 00000000..e65c3f24 --- /dev/null +++ b/docs/reference/system-relationship-contracts.md @@ -0,0 +1,203 @@ +# System and service relationship contracts + +Status: proposed native contract, not implemented. This reference specifies +backend requirements; it supplies no schema changes, executable acceptance +results or runtime evidence. [Acceptance requirements](system-relationship-acceptance.md) +remain unrun. Existing capabilities below are grounded in current source. + +## Scope and existing representations + +| Current representation | Evidence and boundary | +| --- | --- | +| Component | [Infrastructure schema](../../proto/trogonatlas/eventmodel/v1alpha1/infrastructure.proto): a living deployable implementation unit, with technology and curated `members: repeated EntityRef`. Membership documents implementation intent and does not change behavioral validation. | +| Exact members | [Identity schema](../../proto/trogonatlas/eventmodel/v1alpha1/identity.proto) and [reference extraction/retargeting](../../rsworkspace/crates/trogon-atlas-core/src/refs.rs): members can select any known entity kind, including Component and ExternalSystem. A diagnostic `members[i]` path has no persisted occurrence ID. | +| ExternalSystem | Infrastructure schema: a living third-party boundary; no members field. Its existing inbound/outbound integration links include ReadModel ExternalSource and Processor calls in [moments](../../proto/trogonatlas/eventmodel/v1alpha1/moments.proto). | +| Human behavior | [Slices](../../proto/trogonatlas/eventmodel/v1alpha1/slices.proto): `CommandSlice.persona` field 4, `ui` field 5 and `command` field 6; `UiSlice.persona` field 4, `source_read_models` field 5 and `ui` field 6. UI itself has transitions and slot composition, no persona field. | +| Persona | Moments schema: always human; `role` is a descriptive string. It is neither a directory Person nor an authenticated principal. Automation uses Processor/AutomationSlice. | +| Existing API/data paths | [Specification](specification-and-api-contracts.md), [Channel and DataStore](channel-and-datastore-contracts.md) and [DataProduct](data-product-contracts.md) declarations have their own exact selectors and evidence boundaries. | + +Use Component only where the deployable implementation meaning holds. A service +that is a deployable unit can use Component; a third-party boundary can use +ExternalSystem. Existing Component membership may curate hosted model elements +and other implementation boundaries, with shared exact members remaining shared. +It does not establish exclusive ownership, runtime hosting, arbitrary abstract +system containment, a business hierarchy or transitive membership. A reference +to an ExternalSystem does not mean the Component deploys that third party. +This proposal does not change membership shape, admissible kinds, ordering, +duplicate handling or existing validation. It adds no membership ConnectionRef. + +| Boundary | Disposition | +| --- | --- | +| Labeled directed declarations between implementation/external boundaries | Selected below, using existing owners and typed references. | +| Abstract systems above deployables, independent system/service levels, authored strategic nesting | Deferred. Existing source establishes implementation and strategic meanings but no defensible shared taxonomy for these additional levels. No System, Service or Actor entity kind is introduced. | +| External-system-owned membership | Deferred. ExternalSystem has no members field. A relationship labeled “contains” does not introduce membership; a Component proxy must not be invented for an external abstract group. | +| System-level human interactions | Deferred. Existing slice occurrences can ground human behavior, but raw membership cannot identify which hosting assertion supports an interaction. A new aggregation/interaction selector and its lifecycle need a separate contract. | +| General send/receive, conditional triggers and agent/tool communication | Deferred. A label may retain architectural intent but does not declare message flow, processor execution or event production. Existing typed API/observation paths retain their own meanings. | + +## Proposed wire shape + +The following names and tags are proposed implementation input, not current +protobuf fields. Extend existing Component with `relationships` at field 8 and +ExternalSystem with `relationships` at field 7. Both are repeated +`ArchitecturalRelationship` values. Existing fields retain their meanings. + +| Proposed message/field | Type and value contract | +| --- | --- | +| `ArchitecturalRelationship.connection_id = 1` | Existing `ConnectionId`; required in persisted state, omitted for assignment as described below. | +| `ArchitecturalRelationship.target = 2` | Required `ArchitecturalEndpoint`. | +| `ArchitecturalRelationship.label = 3` | Required existing `CatalogTitle`, with nonblank UTF-8 `value`, at most 256 encoded bytes under its existing validation. Human-readable wording, no controlled runtime semantics. | +| `ArchitecturalRelationship.doc = 4` | Optional existing `CatalogText`, nonblank if present, at most 16 KiB encoded under its existing validation. Absence means no elaboration. | +| `ArchitecturalEndpoint.component = 1` | Oneof selection, existing `ComponentRef` wrapping exact native Id. Currently declared in [reliability.proto](../../proto/trogonatlas/eventmodel/v1alpha1/reliability.proto); reuse or relocate that definition, do not duplicate it. | +| `ArchitecturalEndpoint.external_system = 2` | Alternative in the same oneof, existing `ExternalSystemRef`. | + +The containing exact Component or ExternalSystem is both the declaration owner +and implicit source endpoint. Direction is always source to target. There is no +separate owner ref, source field, bidirectional flag, inverse list or relation +entity kind. Either owner kind can target either endpoint kind. An inbound +claim is authored on its source, requiring write access there. Cross-namespace +reference permission alone cannot authorize it. A reverse arrow requires its +own declaration on the other source. + +Endpoints require namespace, slug and positive numeric breaking-change version; +missing, unknown or multiple alternatives reject, as do latest/family/source +handles and self-targets with identical kind/key/version. Distinct versions +are distinct endpoints; descriptive cycles between distinct endpoints are legal. +There is no transitive dependency, deployment, execution or authorization rule. + +Repeated equal target/label/doc values are permitted as separate occurrences. +Their ConnectionIds distinguish them; endpoint pairs and labels never deduplicate +or identify occurrences. Preserve list order for native export and display, +without interpreting it as causal order. An empty collection means no authored +outbound declarations in that checked owner, not no operational dependencies. +No per-relationship status, protocol, message, provider, behavior or metadata bag +is introduced. Decision/Document subjects can carry rationale and provenance. + +## Identity, versions and branches + +Reuse [connection identity](connection-identity.md), the +[connection inventory/resolver](../../rsworkspace/crates/trogon-atlas-core/src/connections.rs) +and [persistence lifecycle helpers](../../rsworkspace/crates/trogon-atlas-core/src/connection_persistence.rs). +Adding protobuf fields alone does not integrate their semantic fingerprints, +resolved targets or graph discovery; these are explicit implementation obligations. + +The fingerprint is relationship role plus full typed target. Source identity is +the containing exact owner/incarnation. Label, doc and order are descriptive and +excluded from the fingerprint; changing wording preserves identity. A target +kind/key/version change requires a fresh ID. All persisted connection occurrences +share one uniqueness domain within the containing owner incarnation. + +| Operation | Required behavior | +| --- | --- | +| Create | Fresh server-owned UID. Omitted IDs receive UUIDv7 values; valid supplied IDs are allowed on a new owner only. Reject duplicate IDs across the entire owner and malformed/noncanonical/nil UUIDs. | +| Edit/add/reorder | Preserve unchanged IDs. Additions to existing owners omit IDs; reject unknown supplied IDs, stripping retained IDs in changed content and target changes retaining an ID. | +| Preview/retry | Preview IDs are not reserved and cannot be supplied as active IDs on apply. Preserve original request digest/idempotency semantics through assignment. | +| Remove/re-add | Removed IDs stop resolving. Re-add with fresh IDs; indistinguishable same-target replacement requires separate guarded remove/add writes. No endpoint/index matching or deletion ledger is introduced. | +| Exact-content id-less reapply | Existing whole-content no-op exception preserves stored UID/IDs. It does not permit edited content to strip identities. | +| Copy/new version | New owner incarnation; local IDs may be retained in their new scope. Incoming selectors remain on the original owner. Targets remain exact unless explicitly changed. | +| Branch edit/land/rebase | Preserve incarnation and active IDs; compare recorded base, baseline and branch. Ordinary landing refuses revival of an ID deleted on the opposing same-incarnation owner. | +| Explicit conflict resolution | Keep the selected incarnation; renew only restored IDs removed by the opposing same-incarnation owner. Whole-owner deletion uses existing explicit keep-side restoration behavior. Independent same-key creations with different UIDs require conflict resolution. | +| Delete/recreate | Old ConnectionRefs fail against the replacement UID. Plain endpoint refs follow the exact mutable key, including same-key recreation. | + +A ConnectionRef is existing `owner: EntityRef`, `owner_uid` and `id`. +Resolution checks exact owner kind/key/version, UID, complete stored identity +inventory and the selected relationship. A readable stored declaration may +remain identifiable when its target has become unavailable; target resolution +is reported separately. No selector freezes mutable label/doc, endpoint content +or behavior. Historical findings require checked content and revision/etag, +branch and authorization context in addition to IDs. + +## Subjects, references and native operations + +Extend the closed responsibility and CatalogSubject connection inventories to +allow **only** `relationships[]` on Component and ExternalSystem. Reuse existing +ConnectionRef arms in [ResponsibilitySubject](../../proto/trogonatlas/eventmodel/v1alpha1/responsibility.proto) +and [CatalogSubject](../../proto/trogonatlas/eventmodel/v1alpha1/decision_document.proto). +There is no new selector union arm. Current +[responsibility admission](../../rsworkspace/crates/trogon-atlas-core/src/responsibility.rs) +excludes these owner kinds; implementation must extend validation, resolution, +authorized endpoint context and direct/reverse query discovery together. A raw +Component member, ancestry ref or arbitrary path remains an unsupported connection +subject even if its owner kind is admitted. + +Team/Person can assign responsibility to that exact declaration. Decision and +Document can select it as a subject. Existing entity subjects for Component and +ExternalSystem remain unchanged. Assignment or rationale on the owner does not +spread to declarations, endpoints or members; assignment on a declaration does +not spread to an equal-endpoint sibling. Selecting a stored declaration asserts +neither valid endpoint hydration nor executed behavior. Target availability is +reported independently, with ordinary edited-owner reference admission retained. + +| Surface | Required extension | +| --- | --- | +| Native authoring | Exact reads, guarded put/batch, validation, diff, branch operations, preview, native manifest/export and snapshot recovery preserve the proposed fields and returned identities. Advertise a new writer contract revision and mutation floor before admitting fields older writers could drop; no revision number is allocated here. | +| Outgoing/incoming references | Add explicit extraction for `relationships[i].target.component` or `.external_system`, and return existing [Reference](../../proto/trogonatlas/api/eventmodel/v1alpha1/graph.proto) fields `from`, `from_uid`, `connection_id`, `from_field`, `to`. Preserve parallel occurrences and multiplicity. A path is diagnostic only. | +| Subject discovery | ListSubjectAssignments, ListSubjectDecisions and ListSubjectDocuments match full ConnectionRef, preserving owner UID, occurrence ID and unchanged selector. Existing namespace visibility/budgets apply. New shapes must be explicitly included in scan/index provenance enrichment, not assumed indexed from protobuf reflection. | +| Impact | Include declared target references with full occurrence provenance on returned paths. Existing owner-level reachability/one-path-per-owner behavior is not exhaustive parallel-path enumeration or a runtime dependency classifier. | +| Retarget | Exact guarded entity-key retarget updates supported plain targets and renews affected relationship IDs. Existing ConnectionRefs selecting old declarations do not follow them; replacing these selectors requires explicit new selections. | +| Safe/force deletion | Complete incoming-reference guard sees relation targets and typed subject owners. Safe delete protects them even with hidden referrers. Force delete leaves incoming declarations/selectors unresolved without cascading or replacing them. Local occurrence removal follows existing local-removal semantics and can leave subjects unresolved. | + +GetEntity and existing reference/subject queries suffice for direct inspection; +no relationship traversal RPC or new derived hierarchy is selected. Fetch the +readable source at its checked etag to obtain labels; Reference does not carry +a fabricated relationship payload. An etag change requires a refreshed read, +not merging old provenance with current wording. + +Source integration is a separate boundary. Its existing +[SourceSelection and field enum](../../proto/trogonatlas/api/eventmodel/v1alpha1/source_integration.proto) +include ConnectionRef and RELATIONSHIPS for supported current uses; this does +not authorize these new occurrences automatically. This first release is native +only: source selection/adoption of architectural occurrences and source ownership +of their `relationships` field are unsupported and reject atomically. Source +whole-owner writes involving a nonempty current or proposed architectural +relationship collection must also reject, preventing silent deletion. +Source creates containing architectural relationships must reject regardless of +ownership policy, including title-only ownership: the +[create path](../../rsworkspace/crates/trogon-atlas-server/src/source_integration.rs) +copies the incoming entity, so field-specific ownership alone is not a filter +on initial content. Existing-owner supported field-specific writes to unrelated +fields preserve the local collection. +Remote connectors, format compilers, source selector rebinding and portable +migration of incarnation-bound subjects remain deferred. Native export/reapply +in the same store is not proof of portable migration. + +## Admission, visibility and bounds + +All following rules are proposed requirements for this slice. Backend authority, +existing namespace access, write guards, metadata and entity size/RPC limits +remain applicable. No catalog label or assignment grants security authority. + +| Boundary | Requirement | +| --- | --- | +| Changed owner | Validate complete resulting owner and exact targets in the authorized merged branch/final batch overlay, including tombstones. Target must exist and be readable/referenceable. Unchanged dangling owners remain inspectable and do not veto unrelated mutations. | +| Batch/branch concurrency | Validate and publish under existing guarded commit/writer coordination. Recheck relevant view/preconditions at publication; stale preview/read must fail or be revalidated against the guarded final graph. No partial owner, batch or landing publication. | +| Resource ceilings | At most 1,024 relationships per owner; entire protobuf entity at most 1 MiB. Lower existing limits win. Cap rejection never truncates a collection. | +| Discovery work | Extend the existing shared 5,000 visible resource-row ceiling to include Component and ExternalSystem, counted once per exact owner/view. Share 10,000 examined identified occurrences across nested subject work and 4,096 emitted records per request; repeated equal endpoints consume work. Internal scan pages and batch members do not reset a request's budgets. Independent requests have independent counters; a continuation token cannot bypass the complete-scan ceiling required by that request. | +| Exact hydration | Bypass display/discovery projection caps for exact authorized owner lookup, retaining entity/RPC limits. Validate the complete persisted identity inventory before occurrence selection. | +| Operational failure | Discovery/admission budget exhaustion is RESOURCE_EXHAUSTED. Backend, decode, timeout and authorization-service failures retain operational semantics; they cannot become a verified empty result or model absence finding. | +| Visibility | Source write plus authorized reference access to target required. Hidden direct reads preserve NOT_FOUND; Reader mutations return PERMISSION_DENIED. A query for an unreadable subject fails without disclosing existence. Readable authored selectors remain visible, without hidden target hydration. | +| Query hydration | For callers lacking target visibility, missing and hidden targets share generic unavailable status. Never reveal hidden titles, namespace inventory, referrer paths, counts or existence. Authorized stale UID/removed-ID diagnostics can be specific where safe. | +| Deletion safety | Use independent complete incoming-reference guard across namespaces and final requested deletions, with bounded concurrency/timeout. Reporting caps cannot authorize deletion. Operational/incomplete guard refuses deletion. Preserve existing `referrers_incomplete` reporting behavior and generic hidden-dependency protection. | + +Typed discovery overflow fails with RESOURCE_EXHAUSTED. Existing bounded +impact/export/report surfaces may return explicitly incomplete output under +their existing contracts; clients must preserve incompleteness. A clipped export +is not a complete reapply artifact. A successful native write is evidence of +accepted declarations only. Authored grouping, architectural declaration, +checked behavioral paths and observed runtime behavior remain distinct layers. + +## Deferred human interaction contract + +A future system-level Persona view must ground issuance in the exact +CommandSlice persona/UI/command edges, and display in exact UiSlice persona/UI +and selected source ReadModelEdge occurrences. These paths are present in +[slice reference extraction](../../rsworkspace/crates/trogon-atlas-core/src/refs.rs) +and [connection context fingerprints](../../rsworkspace/crates/trogon-atlas-core/src/connections.rs). +Repeated equal ReadModel edges must remain distinct; repeated storyboard moments +must retain authored order and recurrence without invented moment IDs. + +Component membership alone cannot choose an interaction occurrence or prove +hosting, a human's permissions or runtime execution. This proposal adds no +Persona-to-system link, interaction message, inferred actor or behavioral query. +The absent aggregation/hosting occurrence contract is the reason for deferral; +existing exact slice inspection remains available. UI navigation and Screen +slot composition do not supply a substitute Persona relation.