@empressaio/atom-contract 1.7.0

package/dist/registration.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Atom registration contract.
+ *
+ * An {@link AtomRegistration} declares the four-layer contract that every
+ * Hauska atom must satisfy: identity, context interface, composition
+ * declaration, and history anchoring. The registration is **server-safe**:
+ * it carries no React types so the registry can be used from the AI context
+ * pipeline as well as the FE renderer.
+ *
+ * Render bindings (the React `<AtomShell>`, per-mode components, focus
+ * store wiring) live in a separate package that depends on this one — not
+ * the other way around. See README §"What this package does NOT ship".
+ */
+import type { AtomComposition } from "./composition.js";
+import type { ContextSummary } from "./context.js";
+import type { Scope } from "./scope.js";
+/**
+ * The five render modes declared by the contract. This package ships these
+ * as a type-only contract; the React binding for each mode lands in a
+ * sibling package.
+ */
+export type AtomMode = "inline" | "compact" | "card" | "expanded" | "focus";
+/**
+ * Atom access tier per ADR-017. Drives catalog visibility and surface-level
+ * gating at the MCP / API boundary.
+ *
+ * - `public-free`     — visible in the unauthenticated public catalog.
+ * - `public-paid`     — visible in the catalog; entitlement-gated at fetch.
+ * - `platform-internal` — visible to platform staff only; never enumerated
+ *   to public clients. Used for partnership-pending data that has been
+ *   ingested but is not yet sanctioned for public surfacing.
+ * - `tenant-private`  — visible only to the owning tenant.
+ * - `tenant-shared`   — shared between explicit tenants (cross-tenant
+ *   benchmarking opt-in per ADR-017; encumbrance corpora, HOA packs).
+ *
+ * An atom that omits the field is treated as `"public-free"` by surfaces
+ * that gate on visibility. The contract itself performs no enforcement;
+ * downstream filters (MCP `list_*`, catalog APIs) honor the tag.
+ *
+ * The field may appear on:
+ *   - {@link AtomRegistration.accessPolicy} — atom-type default; useful
+ *     when an entire atom type is platform-internal (e.g. an audit atom).
+ *   - {@link ContextSummary.accessPolicy} — per-instance value; lets a
+ *     mostly-public atom mark individual instances internal (the
+ *     partnership-pending jurisdiction case). When both are present the
+ *     instance value wins.
+ */
+export type AccessPolicy = "public-free" | "public-paid" | "platform-internal" | "tenant-private" | "tenant-shared";
+/**
+ * Stable reference to a single atom instance. The {@link displayLabel} is
+ * populated by {@link parseInlineReferences} from the third token of
+ * `{{atom|type|id|label}}`; downstream code should treat the label as
+ * presentation-only and never use it for identity.
+ */
+export interface AtomReference {
+    kind: "atom";
+    entityType: string;
+    entityId: string;
+    mode?: AtomMode;
+    /**
+     * Inline-prose display label. Single source of truth for the chip text.
+     */
+    displayLabel?: string;
+}
+/**
+ * Headless atom props passed to render bindings (lives in a sibling
+ * package). Declared here so the registration's render-mode contract is
+ * complete, but free of React imports.
+ */
+export interface AtomProps {
+    entityId: string;
+    mode: AtomMode;
+    data?: Record<string, unknown>;
+    onAction?: (message: string) => void;
+    onModeChange?: (mode: AtomMode) => void;
+    onDrillIn?: (atom: AtomReference) => void;
+}
+/**
+ * Optional chip action surfaced by the render layer when an atom appears
+ * in inline prose. Generated from the underlying data, never persisted.
+ */
+export interface ChipAction {
+    id: string;
+    label: string;
+    /** Free-form prompt fragment the chat will send when the chip is clicked. */
+    message: string;
+}
+/**
+ * Type-level helper that constrains `defaultMode` to a member of
+ * `supportedModes`. Used as the `defaultMode` field type so registrations
+ * with a mismatched default fail to typecheck.
+ */
+export type DefaultModeOf<TSupported extends ReadonlyArray<AtomMode>> = TSupported[number];
+/**
+ * Type-level guard rejecting widened (non-literal) string types. When
+ * `T = string` (i.e. callers passed a non-literal), `string extends T` is
+ * `true` and this resolves to `never`, which makes the surrounding field
+ * un-assignable. When `T = "task"` (a literal), it resolves to `T`.
+ *
+ * Used to enforce: every registration must have a literal `entityType` so
+ * the registry can narrow the resolved type.
+ */
+export type LiteralString<T extends string> = string extends T ? never : T;
+/**
+ * The four-layer atom contract. Generic in `TType` (a literal string) so
+ * the resolver can narrow the entity type at the call site. Preserves a
+ * compile-time union of registered types.
+ *
+ * @typeParam TType - Literal string type identifying the atom (e.g. `"task"`).
+ * @typeParam TSupported - Tuple of supported render modes; constrains
+ *   `defaultMode` at compile time.
+ */
+export interface AtomRegistration<TType extends string = string, TSupported extends ReadonlyArray<AtomMode> = ReadonlyArray<AtomMode>> {
+    /**
+     * Stable atom identity. The literal-only constraint is enforced at the
+     * {@link AtomRegistry.register} entry point (via {@link LiteralString})
+     * rather than on the type itself, so heterogeneous storage shapes
+     * (`AnyAtomRegistration`) and stub builders can carry plain `TType`
+     * without fighting the type system.
+     */
+    entityType: TType;
+    /**
+     * Required, queryable. Atoms are grouped by domain for prompt-builder
+     * derivation (`registry.describeForPrompt()`) and for `listByDomain()`.
+     */
+    domain: string;
+    /** Modes the future render binding will implement. */
+    supportedModes: TSupported;
+    /**
+     * Default mode used when the caller does not specify one. The type
+     * constraint forces this to be a member of `supportedModes` —
+     * registrations with a mismatched default fail to typecheck.
+     */
+    defaultMode: DefaultModeOf<TSupported>;
+    /**
+     * Optional chip-action generator invoked by the render layer when the
+     * atom appears as an inline chip.
+     */
+    chipActions?: (data: Record<string, unknown>) => ChipAction[];
+    /**
+     * The four-layer context resolver. Receives the entity id and a
+     * {@link Scope} object; returns a typed payload (never a bare string).
+     * Atoms that don't differentiate by scope can ignore the second arg.
+     */
+    contextSummary: (entityId: string, scope: Scope) => Promise<ContextSummary<TType>>;
+    /**
+     * Declarative composition graph. Pass an empty array (`[]`) to declare
+     * "no children" — the field is **required** so a registration cannot
+     * silently omit the composition layer of the four-layer contract.
+     * The registry validates referenced child types at `validate()` and on
+     * first lookup.
+     */
+    composition: ReadonlyArray<AtomComposition>;
+    /**
+     * Atom-type default access tier per ADR-017. Surfaces that gate on
+     * visibility (MCP `list_*`, public catalog APIs) treat an omitted field
+     * as `"public-free"`. Per-instance overrides flow through
+     * {@link ContextSummary.accessPolicy}; when both are present the
+     * instance value wins.
+     *
+     * @see {@link AccessPolicy} for the value semantics.
+     */
+    accessPolicy?: AccessPolicy;
+    /**
+     * Optional, machine-readable list of event-type strings this atom is
+     * allowed to emit (and that downstream consumers — audit logs, history
+     * filters, contract tests, catalog surfaces — can rely on to be the
+     * canonical vocabulary for the atom).
+     *
+     * The registry does **not** enforce that producers call
+     * {@link EventAnchoringService.appendEvent} with one of these strings;
+     * the framework treats the field as documentation that the registry
+     * exposes through {@link AtomPromptDescription.eventTypes} so tooling
+     * can introspect it without sniffing source files. Atoms that don't
+     * emit events may omit the field — the catalog surface treats a
+     * missing field as "no declared events" (empty array).
+     *
+     * Convention: dotted names namespaced by `entityType` (e.g.
+     * `"sheet.created"`, `"snapshot.referenced-in-submission"`). Producers
+     * should reference the same constant the registration carries so a
+     * rename surfaces as a typecheck failure.
+     */
+    eventTypes?: ReadonlyArray<string>;
+}
+/**
+ * Convenience alias for a registration whose render-mode tuple is
+ * forgotten — useful for storage in heterogeneous collections (the
+ * registry's `Map`). Loses the `defaultMode ⊂ supportedModes` constraint
+ * so should not be used as a parameter type for `register(...)`.
+ */
+export type AnyAtomRegistration = AtomRegistration<string, ReadonlyArray<AtomMode>>;
+//# sourceMappingURL=registration.d.ts.map

package/dist/registration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registration.d.ts","sourceRoot":"","sources":["../src/registration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAChB,QAAQ,GACR,SAAS,GACT,MAAM,GACN,UAAU,GACV,OAAO,CAAC;AAEZ;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,YAAY,GACpB,aAAa,GACb,aAAa,GACb,mBAAmB,GACnB,gBAAgB,GAChB,eAAe,CAAC;AAEpB;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,CAAC;IACxC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,IAAI,CAAC;CAC3C;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,CAAC,UAAU,SAAS,aAAa,CAAC,QAAQ,CAAC,IAClE,UAAU,CAAC,MAAM,CAAC,CAAC;AAErB;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,MAAM,IAAI,MAAM,SAAS,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;AAE3E;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB,CAC/B,KAAK,SAAS,MAAM,GAAG,MAAM,EAC7B,UAAU,SAAS,aAAa,CAAC,QAAQ,CAAC,GAAG,aAAa,CAAC,QAAQ,CAAC;IAEpE;;;;;;OAMG;IACH,UAAU,EAAE,KAAK,CAAC;IAElB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf,sDAAsD;IACtD,cAAc,EAAE,UAAU,CAAC;IAE3B;;;;OAIG;IACH,WAAW,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAEvC;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,UAAU,EAAE,CAAC;IAE9D;;;;OAIG;IACH,cAAc,EAAE,CACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,KAAK,KACT,OAAO,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC;IAEpC;;;;;;OAMG;IACH,WAAW,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IAE5C;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAE5B;;;;;;;;;;;;;;;;;;OAkBG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACpC;AAED;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,CAChD,MAAM,EACN,aAAa,CAAC,QAAQ,CAAC,CACxB,CAAC"}

package/dist/registration.js

@@ -0,0 +1,15 @@
+/**
+ * Atom registration contract.
+ *
+ * An {@link AtomRegistration} declares the four-layer contract that every
+ * Hauska atom must satisfy: identity, context interface, composition
+ * declaration, and history anchoring. The registration is **server-safe**:
+ * it carries no React types so the registry can be used from the AI context
+ * pipeline as well as the FE renderer.
+ *
+ * Render bindings (the React `<AtomShell>`, per-mode components, focus
+ * store wiring) live in a separate package that depends on this one — not
+ * the other way around. See README §"What this package does NOT ship".
+ */
+export {};
+//# sourceMappingURL=registration.js.map

package/dist/registration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registration.js","sourceRoot":"","sources":["../src/registration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/registry.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Atom registry runtime.
+ *
+ * Stores {@link AtomRegistration} instances in a `Map<string, …>` keyed by
+ * `entityType`. Provides typed lookup, domain-scoped iteration, and a
+ * cross-reference validator that walks every registration's composition
+ * edges. No singleton — callers (tests, app bootstrap) construct their own.
+ *
+ * `resolve(entityType)` returns a discriminated `Result` so consumers
+ * (renderer, AI context builder) decide whether to dev-warn or prod-null
+ * instead of catching exceptions.
+ */
+import type { AccessPolicy, AtomRegistration, AnyAtomRegistration, AtomMode, LiteralString } from "./registration.js";
+/**
+ * Discriminated error variant returned by {@link AtomRegistry.resolve}
+ * when no registration exists for the requested `entityType`.
+ */
+export declare class AtomNotRegisteredError extends Error {
+    readonly entityType: string;
+    readonly kind: "atom-not-registered";
+    constructor(entityType: string);
+}
+/**
+ * Discriminated error variant returned by {@link AtomRegistry.validate}
+ * for each composition edge whose target entity type is not registered.
+ */
+export interface DanglingCompositionRef {
+    parentEntityType: string;
+    childEntityType: string;
+    dataKey: string;
+}
+/** Discriminated success/failure result for {@link AtomRegistry.resolve}. */
+export type ResolveResult<TType extends string = string> = {
+    ok: true;
+    registration: AtomRegistration<TType, ReadonlyArray<AtomMode>>;
+} | {
+    ok: false;
+    error: AtomNotRegisteredError;
+};
+/** Discriminated success/failure result for {@link AtomRegistry.validate}. */
+export type ValidateResult = {
+    ok: true;
+} | {
+    ok: false;
+    errors: ReadonlyArray<DanglingCompositionRef>;
+};
+/**
+ * Per-atom prompt-builder description. The AI prompt builder is expected
+ * to consume an array of these and turn them into a "you can render
+ * <type> using {{atom|type|id|label}}" enumeration without hardcoding
+ * the type list.
+ */
+export interface AtomPromptDescription {
+    entityType: string;
+    domain: string;
+    supportedModes: ReadonlyArray<AtomMode>;
+    defaultMode: AtomMode;
+    composes: ReadonlyArray<string>;
+    /**
+     * Event-type vocabulary the atom self-declares via
+     * {@link AtomRegistration.eventTypes}. Always an array — atoms that
+     * don't declare events surface as `[]` rather than `undefined` so
+     * downstream tooling (catalog UIs, audit-log filters) can map over
+     * the field without nullish guards.
+     */
+    eventTypes: ReadonlyArray<string>;
+    /**
+     * Atom-type default {@link AccessPolicy} from the registration.
+     * Normalized to `"public-free"` when undeclared so consumers can
+     * filter without nullish guards. Per-instance overrides live on
+     * {@link ContextSummary.accessPolicy} and are not visible here.
+     */
+    accessPolicy: AccessPolicy;
+}
+/**
+ * The registry's public surface. Returned by {@link createAtomRegistry}.
+ *
+ * The {@link register} method is generic so the inferred literal type of
+ * the registration narrows the result of {@link resolve} when the same
+ * literal is passed in.
+ */
+export interface AtomRegistry {
+    /**
+     * Register an atom. The `entityType` field is constrained to a literal
+     * string via {@link LiteralString} so the registry can narrow the
+     * resolved type — non-literal (`string`) values are rejected at compile
+     * time. Pass a literal (e.g. `"task"`) or apply `as const`.
+     */
+    register: <TType extends string, TSupported extends ReadonlyArray<AtomMode>>(registration: AtomRegistration<TType, TSupported> & {
+        entityType: LiteralString<TType>;
+    }) => void;
+    /**
+     * Register a pre-built, type-erased registration. Bypasses the literal
+     * `entityType` constraint enforced by {@link register} — intended for
+     * trusted internal callers (test harnesses, dynamic atom loaders) that
+     * have already validated the shape. Application code should always use
+     * {@link register} so it gets the literal narrowing.
+     */
+    registerAny: (registration: AnyAtomRegistration) => void;
+    resolve: <TType extends string>(entityType: TType) => ResolveResult<TType>;
+    list: () => ReadonlyArray<AnyAtomRegistration>;
+    listByDomain: (domain: string) => ReadonlyArray<AnyAtomRegistration>;
+    validate: () => ValidateResult;
+    describeForPrompt: () => ReadonlyArray<AtomPromptDescription>;
+}
+/**
+ * Build a fresh, empty registry. Tests construct their own; the eventual
+ * app bootstrap will construct one and register catalog atoms explicitly.
+ *
+ * Boot-time contract: after every `register()` call has run, the
+ * application bootstrap MUST call {@link AtomRegistry.validate} once and
+ * fail to start if the result is `{ ok: false }`. The registry does not
+ * validate composition references on each `register()` (the parent may
+ * legitimately be registered before the child) and `resolve()` does not
+ * recheck them on lookup either, so dangling cross-references would
+ * otherwise surface only at composition-resolution time. Treating
+ * `validate()` as a hard boot gate keeps the contract enforceable
+ * without paying its cost on every call.
+ *
+ * A composition edge may opt out of presence validation by setting
+ * `forwardRef: true`. Forward-ref edges are skipped by both `validate()`
+ * (so the bootstrap doesn't crash on a not-yet-registered child) and the
+ * lookup-time `resolveComposition` step (so the parent's
+ * `contextSummary` keeps returning a successful result, with zero child
+ * references for that edge, until the child catalog atom registers).
+ */
+export declare function createAtomRegistry(): AtomRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,EACnB,QAAQ,EACR,aAAa,EACd,MAAM,mBAAmB,CAAC;AAE3B;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;aAEnB,UAAU,EAAE,MAAM;IAD9C,QAAQ,CAAC,IAAI,EAAG,qBAAqB,CAAU;gBACnB,UAAU,EAAE,MAAM;CAI/C;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,6EAA6E;AAC7E,MAAM,MAAM,aAAa,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,IACnD;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,YAAY,EAAE,gBAAgB,CAAC,KAAK,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAA;CAAE,GAC5E;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,sBAAsB,CAAA;CAAE,CAAC;AAEjD,8EAA8E;AAC9E,MAAM,MAAM,cAAc,GACtB;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,aAAa,CAAC,sBAAsB,CAAC,CAAA;CAAE,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IACxC,WAAW,EAAE,QAAQ,CAAC;IACtB,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAChC;;;;;;OAMG;IACH,UAAU,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAClC;;;;;OAKG;IACH,YAAY,EAAE,YAAY,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,QAAQ,EAAE,CAAC,KAAK,SAAS,MAAM,EAAE,UAAU,SAAS,aAAa,CAAC,QAAQ,CAAC,EACzE,YAAY,EAAE,gBAAgB,CAAC,KAAK,EAAE,UAAU,CAAC,GAAG;QAClD,UAAU,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC;KAClC,KACE,IAAI,CAAC;IACV;;;;;;OAMG;IACH,WAAW,EAAE,CAAC,YAAY,EAAE,mBAAmB,KAAK,IAAI,CAAC;IACzD,OAAO,EAAE,CAAC,KAAK,SAAS,MAAM,EAAE,UAAU,EAAE,KAAK,KAAK,aAAa,CAAC,KAAK,CAAC,CAAC;IAC3E,IAAI,EAAE,MAAM,aAAa,CAAC,mBAAmB,CAAC,CAAC;IAC/C,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,aAAa,CAAC,mBAAmB,CAAC,CAAC;IACrE,QAAQ,EAAE,MAAM,cAAc,CAAC;IAC/B,iBAAiB,EAAE,MAAM,aAAa,CAAC,qBAAqB,CAAC,CAAC;CAC/D;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,IAAI,YAAY,CAoFjD"}

package/dist/registry.js

@@ -0,0 +1,122 @@
+/**
+ * Atom registry runtime.
+ *
+ * Stores {@link AtomRegistration} instances in a `Map<string, …>` keyed by
+ * `entityType`. Provides typed lookup, domain-scoped iteration, and a
+ * cross-reference validator that walks every registration's composition
+ * edges. No singleton — callers (tests, app bootstrap) construct their own.
+ *
+ * `resolve(entityType)` returns a discriminated `Result` so consumers
+ * (renderer, AI context builder) decide whether to dev-warn or prod-null
+ * instead of catching exceptions.
+ */
+/**
+ * Discriminated error variant returned by {@link AtomRegistry.resolve}
+ * when no registration exists for the requested `entityType`.
+ */
+export class AtomNotRegisteredError extends Error {
+    entityType;
+    kind = "atom-not-registered";
+    constructor(entityType) {
+        super(`No atom registered for entityType "${entityType}"`);
+        this.entityType = entityType;
+        this.name = "AtomNotRegisteredError";
+    }
+}
+/**
+ * Build a fresh, empty registry. Tests construct their own; the eventual
+ * app bootstrap will construct one and register catalog atoms explicitly.
+ *
+ * Boot-time contract: after every `register()` call has run, the
+ * application bootstrap MUST call {@link AtomRegistry.validate} once and
+ * fail to start if the result is `{ ok: false }`. The registry does not
+ * validate composition references on each `register()` (the parent may
+ * legitimately be registered before the child) and `resolve()` does not
+ * recheck them on lookup either, so dangling cross-references would
+ * otherwise surface only at composition-resolution time. Treating
+ * `validate()` as a hard boot gate keeps the contract enforceable
+ * without paying its cost on every call.
+ *
+ * A composition edge may opt out of presence validation by setting
+ * `forwardRef: true`. Forward-ref edges are skipped by both `validate()`
+ * (so the bootstrap doesn't crash on a not-yet-registered child) and the
+ * lookup-time `resolveComposition` step (so the parent's
+ * `contextSummary` keeps returning a successful result, with zero child
+ * references for that edge, until the child catalog atom registers).
+ */
+export function createAtomRegistry() {
+    const store = new Map();
+    function insert(reg) {
+        if (store.has(reg.entityType)) {
+            throw new Error(`Atom "${reg.entityType}" is already registered`);
+        }
+        store.set(reg.entityType, reg);
+    }
+    const registry = {
+        register(registration) {
+            insert(registration);
+        },
+        registerAny(registration) {
+            insert(registration);
+        },
+        resolve(entityType) {
+            const reg = store.get(entityType);
+            if (!reg) {
+                return { ok: false, error: new AtomNotRegisteredError(entityType) };
+            }
+            return {
+                ok: true,
+                registration: reg,
+            };
+        },
+        list() {
+            return Array.from(store.values());
+        },
+        listByDomain(domain) {
+            return Array.from(store.values()).filter((r) => r.domain === domain);
+        },
+        validate() {
+            const errors = [];
+            for (const reg of store.values()) {
+                for (const edge of reg.composition) {
+                    // Forward-ref edges deliberately point at a child atom that
+                    // has not been registered yet (typically a future-sprint
+                    // catalog atom). The parent has opted out of boot-time
+                    // presence validation; the lookup-time `resolveComposition`
+                    // step still rejects the edge if the child is still missing
+                    // when contextSummary runs.
+                    if (edge.forwardRef)
+                        continue;
+                    if (!store.has(edge.childEntityType)) {
+                        errors.push({
+                            parentEntityType: reg.entityType,
+                            childEntityType: edge.childEntityType,
+                            dataKey: edge.dataKey,
+                        });
+                    }
+                }
+            }
+            return errors.length === 0 ? { ok: true } : { ok: false, errors };
+        },
+        describeForPrompt() {
+            return Array.from(store.values()).map((reg) => ({
+                entityType: reg.entityType,
+                domain: reg.domain,
+                supportedModes: reg.supportedModes,
+                defaultMode: reg.defaultMode,
+                composes: reg.composition.map((c) => c.childEntityType),
+                // Normalize undefined → empty array so consumers can map over the
+                // field without a nullish guard. The registration field itself is
+                // optional (undeclared = "no declared events"); the catalog
+                // surfaces always returns an array.
+                eventTypes: reg.eventTypes ?? [],
+                // Normalize undefined → "public-free" per the ADR-017 contract so
+                // downstream visibility filters can branch on the value without a
+                // nullish guard.
+                accessPolicy: reg.accessPolicy ?? "public-free",
+            }));
+        },
+    };
+    return registry;
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"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"}

package/dist/render.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Render-mode resolution.
+ *
+ * Ships the **type-level** render-mode contract only: `AtomMode` enum,
+ * `supportedModes`, `defaultMode`, and a pure resolver that walks the
+ * hardcoded fallback chain `card → compact → expanded → inline → focus`.
+ * There is no React component, no `<AtomShell>`, no focus-store wiring —
+ * those land with the React binding sibling package.
+ */
+import type { AtomMode } from "./registration.js";
+/**
+ * Hardcoded fallback chain. Pulled to module scope so consumers (tests,
+ * docs) can introspect it without re-importing the resolver.
+ */
+export declare const FALLBACK_ORDER: ReadonlyArray<AtomMode>;
+/**
+ * Resolve the mode a render binding should use.
+ *
+ * 1. If `requested` is supported, return it.
+ * 2. Otherwise walk {@link FALLBACK_ORDER} and return the first supported.
+ * 3. As a last resort return `defaultMode` (which the type system
+ *    guarantees is in `supported`).
+ *
+ * @param supported - The atom's `supportedModes`.
+ * @param defaultMode - The atom's `defaultMode`.
+ * @param requested - Mode the caller asked for; `undefined` triggers
+ *   fallback selection.
+ */
+export declare function resolveMode<TSupported extends ReadonlyArray<AtomMode>>(supported: TSupported, defaultMode: TSupported[number], requested?: AtomMode): AtomMode;
+//# sourceMappingURL=render.d.ts.map

package/dist/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,aAAa,CAAC,QAAQ,CAMlD,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,UAAU,SAAS,aAAa,CAAC,QAAQ,CAAC,EACpE,SAAS,EAAE,UAAU,EACrB,WAAW,EAAE,UAAU,CAAC,MAAM,CAAC,EAC/B,SAAS,CAAC,EAAE,QAAQ,GACnB,QAAQ,CAQV"}

package/dist/render.js

@@ -0,0 +1,44 @@
+/**
+ * Render-mode resolution.
+ *
+ * Ships the **type-level** render-mode contract only: `AtomMode` enum,
+ * `supportedModes`, `defaultMode`, and a pure resolver that walks the
+ * hardcoded fallback chain `card → compact → expanded → inline → focus`.
+ * There is no React component, no `<AtomShell>`, no focus-store wiring —
+ * those land with the React binding sibling package.
+ */
+/**
+ * Hardcoded fallback chain. Pulled to module scope so consumers (tests,
+ * docs) can introspect it without re-importing the resolver.
+ */
+export const FALLBACK_ORDER = [
+    "card",
+    "compact",
+    "expanded",
+    "inline",
+    "focus",
+];
+/**
+ * Resolve the mode a render binding should use.
+ *
+ * 1. If `requested` is supported, return it.
+ * 2. Otherwise walk {@link FALLBACK_ORDER} and return the first supported.
+ * 3. As a last resort return `defaultMode` (which the type system
+ *    guarantees is in `supported`).
+ *
+ * @param supported - The atom's `supportedModes`.
+ * @param defaultMode - The atom's `defaultMode`.
+ * @param requested - Mode the caller asked for; `undefined` triggers
+ *   fallback selection.
+ */
+export function resolveMode(supported, defaultMode, requested) {
+    if (requested !== undefined && supported.includes(requested)) {
+        return requested;
+    }
+    for (const mode of FALLBACK_ORDER) {
+        if (supported.includes(mode))
+            return mode;
+    }
+    return defaultMode;
+}
+//# sourceMappingURL=render.js.map

package/dist/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAA4B;IACrD,MAAM;IACN,SAAS;IACT,UAAU;IACV,QAAQ;IACR,OAAO;CACR,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CACzB,SAAqB,EACrB,WAA+B,EAC/B,SAAoB;IAEpB,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QAC7D,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,cAAc,EAAE,CAAC;QAClC,IAAI,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;IAC5C,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/dist/scope.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Scope object passed at the call site of `contextSummary` and other
+ * resolver entry points. Mandatory at the call site so future
+ * audience-aware behavior (AI vs. user vs. internal panels) is opt-in
+ * for atoms but impossible to forget at the call site.
+ */
+/**
+ * Who is asking, with what permissions, as of when. The framework forwards
+ * this verbatim to {@link AtomRegistration.contextSummary}; atoms that do
+ * not differentiate by scope receive the same shape and ignore it.
+ */
+export interface Scope {
+    /**
+     * Audience the response will be shown to. Atoms may filter / redact
+     * based on this value (e.g. omit internal-only metadata for `"ai"`).
+     */
+    audience: "ai" | "user" | "internal";
+    /**
+     * Identity of the requestor when known. Optional because some entry
+     * points (cron warmups, system tasks) have no requestor.
+     */
+    requestor?: {
+        kind: "user" | "agent";
+        id: string;
+    };
+    /**
+     * Time horizon for the response. Defaults to "now" when omitted; atoms
+     * with history may use this to render an as-of view. Stored as a `Date`
+     * for downstream comparison; serialize with `.toISOString()`.
+     */
+    asOf?: Date;
+    /**
+     * Optional permission claim list. The framework does no enforcement —
+     * atoms decide what to do with these. Reserved for future RBAC work.
+     */
+    permissions?: ReadonlyArray<string>;
+}
+/**
+ * Convenience constructor for tests and CLI tools. Returns a scope with
+ * `audience: "internal"` and no requestor, suitable for trusted callers.
+ *
+ * @example
+ *   await registration.contextSummary("id-1", defaultScope());
+ */
+export declare function defaultScope(): Scope;
+//# sourceMappingURL=scope.d.ts.map

package/dist/scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../src/scope.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;GAIG;AACH,MAAM,WAAW,KAAK;IACpB;;;OAGG;IACH,QAAQ,EAAE,IAAI,GAAG,MAAM,GAAG,UAAU,CAAC;IAErC;;;OAGG;IACH,SAAS,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IAEnD;;;;OAIG;IACH,IAAI,CAAC,EAAE,IAAI,CAAC;IAEZ;;;OAGG;IACH,WAAW,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACrC;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,IAAI,KAAK,CAEpC"}

package/dist/scope.js

@@ -0,0 +1,17 @@
+/**
+ * Scope object passed at the call site of `contextSummary` and other
+ * resolver entry points. Mandatory at the call site so future
+ * audience-aware behavior (AI vs. user vs. internal panels) is opt-in
+ * for atoms but impossible to forget at the call site.
+ */
+/**
+ * Convenience constructor for tests and CLI tools. Returns a scope with
+ * `audience: "internal"` and no requestor, suitable for trusted callers.
+ *
+ * @example
+ *   await registration.contextSummary("id-1", defaultScope());
+ */
+export function defaultScope() {
+    return { audience: "internal" };
+}
+//# sourceMappingURL=scope.js.map

package/dist/scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.js","sourceRoot":"","sources":["../src/scope.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAkCH;;;;;;GAMG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;AAClC,CAAC"}