@fabricorg/platform 0.1.2 → 0.2.1

package/README.md

@@ -1,104 +1,148 @@
 # @fabricorg/platform
 
-Generic runtime for ontology-based business applications. Provides the action lifecycle, policy dispatch, state machine validation, adapter retry/circuit-breaker, event append, and ID generation that any vertical (lending, legal, healthcare, insurance, etc.) can build on.
+A portable runtime for ontology-based, agent-native business applications. Zero dependencies. Bring your own database client.
 
-## Portability Scope
+```bash
+npm install @fabricorg/platform
+```
 
-**`@fabricorg/platform` is portable.** It has zero runtime dependencies, no database client, no ORM, and no vertical vocabulary. Every contract is parameterized by `TDb` so consumers bind their own persistence client.
+## Hello, action
 
-**Vertical packages (e.g. `@repo/lending`) are NOT portable.** They bind `TDb` to a concrete client (e.g. `Prisma.TransactionClient`), reference vertical entity types, and assume a specific database schema. To run a vertical against a different ORM, fork the vertical — not the platform.
+```ts
+import { z } from "zod";
+import type { ActionDefinition, ActionContext } from "@fabricorg/platform/actions";
+
+const greet: ActionDefinition<unknown> = {
+  id: "demo.greet",
+  schema: z.object({ name: z.string() }),
+  handler: async (ctx: ActionContext<unknown>, params: { name: string }) => {
+    return { greeting: `Hello, ${params.name}!` };
+  },
+};
+```
 
-The platform is enforced clean by `boundary.test.ts`, which forbids:
-- `@repo/database`, `@repo/ontology`, `@repo/adapters` imports
-- the literal `Prisma`, the field name `prisma:`, and the type default `TDb = any`
-- any vertical vocabulary (`lending.`, `borrower`, `lender`, `LeadApplication`, `Offer`, `Vehicle`, `Party`, `Obligation`, `auto-refi`, etc.)
-- any "register default" hook (`registerDefaultPolicies`, etc.)
+That's the smallest unit. From here, you compose actions into a `FabricModule<TDb>`, register the module at startup, and call `invokeAction("demo.greet", ...)` from any of three call paths (authenticated user, signed token, or system/agent). Every call passes through the same pipeline: **policy → state machine → handler → adapters → events → projections.**
 
-## Subpath Exports
+For a complete walkthrough see https://platform.fabric.pro/docs/getting-started/quickstart.
 
-| Path | Contents |
-|---|---|
-| `@fabricorg/platform` | re-exports everything below |
-| `@fabricorg/platform/actions` | `ActionDefinition<TDb>`, `ActionContext<TDb>`, `ActorType`, `assertActorType`, `SagaImplementation`, `SchemaValidator` |
-| `@fabricorg/platform/adapters` | `AdapterRegistry`, `AdapterImplementation`, retry/circuit-breaker primitives |
-| `@fabricorg/platform/events` | `AssetEventEnvelope`, `EventTypeRegistry` |
-| `@fabricorg/platform/ids` | `createFabricId`, `FABRIC_ID_PREFIXES`, `parseFabricId` |
-| `@fabricorg/platform/modules` | `FabricModule<TDb>`, `ModuleRegistry`, `createModuleRegistry`, `registerFabricModules` |
-| `@fabricorg/platform/policies` | `PolicyEvaluator<TDb>`, `PolicyContext<TDb>`, code/data/hybrid evaluation engine |
-| `@fabricorg/platform/state-machines` | `StateMachineDefinition`, `validateTransition`, engine |
-| `@fabricorg/platform/projections` | replay/snapshot framework |
-| `@fabricorg/platform/displays` | `DisplayRendererRegistration`, display engine |
-| `@fabricorg/platform/privacy` | redaction, anonymization-pipeline, data-classification contracts |
-| `@fabricorg/platform/evidence` | compliance evidence packet envelope |
-| `@fabricorg/platform/objects` | shared object-type contracts |
-| `@fabricorg/platform/testing` | test fixtures (in-memory adapter registry, fake ActionContext, deterministic IDs) |
+## Why use this
 
-## Action Lifecycle
+You're building a governed business application — not a CRUD app. You need:
 
-Every domain mutation flows through a single platform pipeline:
+- A single, auditable entry point for every mutation
+- Policies that gate every change before it happens
+- Events as evidence (not retrofitted logs)
+- Agents and humans treated identically by policy
+- A vertical-specific ontology layered on a portable runtime
 
-1. `evaluatePolicies` — dispatch each policy ID via `evaluatePolicyDefinitions` (code/data/hybrid). Aggregate `block` halts the invocation.
-2. **If `actionDef.kind === "saga"`** — dispatch to a registered saga implementation that orchestrates child actions and returns a `SagaCompletion`.
-3. **Otherwise** — build an `ActionContext<TDb>`, run `actionDef.handler(ctx, params)` inside a single transaction. The handler parses its own input via its declared schema (single source of truth — handlers honor their schema contract). State-machine binding validates transitions before the handler runs. ZodError thrown by handler parsing is translated to `validation_failed` invocation status.
-4. `executeAdapters` — for each `actionDef.adapterSteps`, look up the implementation in the `AdapterRegistry` and run via `executeWithAdapterRetry` (idempotency-aware retry, exponential backoff, circuit breaker, dead-letter queue on terminal failure).
-5. `completeActionInvocation` — mark completed/failed and emit telemetry.
+That's what this package gives you. Nothing more.
 
-`validateActionParameters` exists as a standalone activity for preview/dry-run paths but is **not** part of the execute pipeline — parameter validation happens once, in the handler, via its own schema.
+## What's in the box
 
-## Module Contract
+| Subpath | What you get |
+|---|---|
+| `@fabricorg/platform` | Re-exports everything below |
+| `@fabricorg/platform/actions` | `ActionDefinition`, `ActionContext`, `SagaImplementation` |
+| `@fabricorg/platform/policies` | `PolicyEvaluator`, `PolicyContext`, code/data/hybrid evaluation |
+| `@fabricorg/platform/state-machines` | `StateMachineDefinition`, `validateTransition` |
+| `@fabricorg/platform/events` | `AssetEventEnvelope`, `EventTypeRegistry` |
+| `@fabricorg/platform/projections` | Replay/snapshot framework |
+| `@fabricorg/platform/adapters` | `AdapterRegistry`, retry + circuit-breaker |
+| `@fabricorg/platform/modules` | `FabricModule<TDb>`, `registerFabricModules` |
+| `@fabricorg/platform/ids` | `createFabricId`, `FABRIC_ID_PREFIXES` |
+| `@fabricorg/platform/displays` | `DisplayRendererRegistration` |
+| `@fabricorg/platform/privacy` | Redaction + data classification |
+| `@fabricorg/platform/evidence` | Compliance evidence packets |
+| `@fabricorg/platform/objects` | Shared object-type contracts |
+| `@fabricorg/platform/testing` | In-memory adapter registry, fake `ActionContext`, deterministic IDs |
 
-Verticals declare modules as `FabricModule<TDb>`:
+## Composing a vertical
+
+Verticals declare a `FabricModule<TDb>` that registers their actions, policies, state machines, events, and adapters with the platform:
 
 ```ts
 import type { FabricModule } from "@fabricorg/platform/modules";
-import type { Prisma } from "@repo/database";
+import { registerFabricModules } from "@fabricorg/platform/modules";
 
-export const lendingModule: FabricModule<Prisma.TransactionClient> = {
-  namespace: "lending",
+const myModule: FabricModule<MyDbClient> = {
+  namespace: "demo",
   version: "1.0.0",
-  objectTypes: ["Vehicle", "Party", "Location", "Document"],
-  actions: [...],
-  policies: [...],
-  stateMachines: [...],
-  displayRenderers: [...],
+  objectTypes: ["Widget"],
+  actions: [greet, /* ... */],
+  policies: [/* ... */],
+  stateMachines: [/* ... */],
+  displayRenderers: [],
 };
+
+// At app startup:
+registerFabricModules([myModule]);
 ```
 
-Apps compose modules explicitly at startup:
+The platform never auto-loads a module. The host app composes them explicitly — no implicit defaults, no globals, no surprises.
 
-```ts
-import { registerFabricModules } from "@fabricorg/platform/modules";
-import { lendingModule } from "@repo/lending";
-import { messagingModule } from "@repo/messaging";
+## The action lifecycle
 
-registerFabricModules([messagingModule, lendingModule]);
-```
+Every `invokeAction(id, params)` call goes through:
+
+1. **`evaluatePolicies`** — every policy registered for the action runs (code/data/hybrid). A single `block` halts the invocation.
+2. **State-machine validation** — if the action's target entity is bound to a state machine, the requested transition is validated before the handler runs.
+3. **Handler** — `actionDef.handler(ctx, params)` runs inside a single `TDb` transaction. Handler parses its own input via its `schema` (single source of truth).
+4. **Adapters** — for each `actionDef.adapterSteps`, the registered implementation runs via `executeWithAdapterRetry` (idempotent retry, exponential backoff, circuit breaker).
+5. **Events** — domain events are appended; projections derive read models on next replay.
+6. **Completion** — invocation status is marked, telemetry emitted.
 
-There are no implicit/default modules. The platform never auto-loads a vertical. Each vertical owns its full domain ontology — there is no "shared core ontology" package; cross-industry governance object types (`AssetEvent`, `ActionInvocation`, `PolicyEvaluation`, `ApprovalRequest`, `ConsentRecord`, `AgentRun`) are pre-registered by the platform itself.
+`validateActionParameters` is also exposed for preview/dry-run paths but is **not** part of the execute pipeline.
 
-## Saga Actions
+## Saga actions
 
-Multi-step orchestrations declare `kind: "saga"` on the `ActionDefinition` and ship a `SagaImplementation` alongside:
+Multi-step orchestrations declare `kind: "saga"` on the `ActionDefinition` and ship a `SagaImplementation`:
 
 ```ts
 import type { SagaImplementation } from "@fabricorg/platform/actions";
 
 export const ingestSaga: SagaImplementation = async (ctx, runChild) => {
-  const child = await runChild({
+  const step1 = await runChild({
     suffix: "step-1",
-    actionId: "lending.receive_lead_payload",
-    parameters: { ... },
+    actionId: "demo.receive_payload",
+    parameters: { /* ... */ },
   });
-  // ... orchestrate further child actions ...
+  // orchestrate further child actions...
   return {
-    resultData: { ... },
-    event: { eventType: "...", subjectType: "...", subjectId: "...", payload: ... },
+    resultData: { /* ... */ },
+    event: { eventType: "...", subjectType: "...", subjectId: "...", payload: {} },
   };
 };
 ```
 
-The host app's saga registry maps action IDs to implementations. The worker dispatches generically — no platform code or worker code references vertical action IDs.
+Your worker maps action IDs to implementations. The platform dispatches generically — no platform code references vertical action IDs.
+
+## Portability boundary
+
+The `boundary.test.ts` in this package fails CI if any of these leak in:
+
+- `@repo/database`, `@repo/ontology`, `@repo/adapters` imports
+- the literal `Prisma`, the field name `prisma:`, or the type default `TDb = any`
+- vertical vocabulary (`lending.`, `borrower`, `lender`, `Vehicle`, `Party`, `Obligation`, `auto-refi`, etc.)
+- "register default" hooks (`registerDefaultPolicies`, etc.)
+
+This is what keeps the platform portable across verticals and consumers.
+
+## Compatibility
+
+- **Runtime:** Node 20+
+- **Module formats:** ESM and CommonJS (dual format from v0.2.0+)
+- **TypeScript:** 5.0+, `moduleResolution: node` or `node16`/`nodenext`
 
 ## Versioning
 
 `0.x` while contracts evolve. `1.0` only after at least two materially different verticals validate the API.
+
+See [`CHANGELOG.md`](./CHANGELOG.md) for release history.
+
+## Documentation
+
+Full reference docs at https://platform.fabric.pro
+
+## License
+
+MIT

package/dist/actions/index.cjs

@@ -0,0 +1,48 @@
+'use strict';
+
+var chunkKQEBNUZI_cjs = require('../chunk-KQEBNUZI.cjs');
+
+
+
+Object.defineProperty(exports, "ACTOR_TYPES", {
+  enumerable: true,
+  get: function () { return chunkKQEBNUZI_cjs.ACTOR_TYPES; }
+});
+Object.defineProperty(exports, "assertActionId", {
+  enumerable: true,
+  get: function () { return chunkKQEBNUZI_cjs.assertActionId; }
+});
+Object.defineProperty(exports, "assertActorType", {
+  enumerable: true,
+  get: function () { return chunkKQEBNUZI_cjs.assertActorType; }
+});
+Object.defineProperty(exports, "getRegisteredActionIds", {
+  enumerable: true,
+  get: function () { return chunkKQEBNUZI_cjs.getRegisteredActionIds; }
+});
+Object.defineProperty(exports, "isActorType", {
+  enumerable: true,
+  get: function () { return chunkKQEBNUZI_cjs.isActorType; }
+});
+Object.defineProperty(exports, "isRegisteredActionId", {
+  enumerable: true,
+  get: function () { return chunkKQEBNUZI_cjs.isRegisteredActionId; }
+});
+Object.defineProperty(exports, "registerAction", {
+  enumerable: true,
+  get: function () { return chunkKQEBNUZI_cjs.registerAction; }
+});
+Object.defineProperty(exports, "registerActionIfMissing", {
+  enumerable: true,
+  get: function () { return chunkKQEBNUZI_cjs.registerActionIfMissing; }
+});
+Object.defineProperty(exports, "resolveAction", {
+  enumerable: true,
+  get: function () { return chunkKQEBNUZI_cjs.resolveAction; }
+});
+Object.defineProperty(exports, "resolveRegisteredAction", {
+  enumerable: true,
+  get: function () { return chunkKQEBNUZI_cjs.resolveRegisteredAction; }
+});
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/actions/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.cjs"}

package/dist/actions/index.d.cts

@@ -0,0 +1,116 @@
+type ActionId = `${string}.${string}`;
+interface SchemaParseIssue {
+    path: PropertyKey[];
+    message: string;
+}
+type SchemaParseResult<T = unknown> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: {
+        issues: SchemaParseIssue[];
+    };
+};
+interface SchemaValidator<T = unknown> {
+    parse(input: unknown): T;
+    safeParse(input: unknown): SchemaParseResult<T>;
+}
+type ActorType = "natural_person" | "agent" | "system" | "service_account" | "external_system" | "integration";
+declare const ACTOR_TYPES: readonly ActorType[];
+declare function isActorType(value: string): value is ActorType;
+declare function assertActorType(value: string): asserts value is ActorType;
+type ActionStatus = "pending" | "running" | "completed" | "failed" | "blocked_by_policy" | "waiting_for_approval" | "validation_failed";
+interface FabricRuntimeServices {
+    readonly [serviceName: string]: unknown;
+}
+interface ActionContext<TDb = unknown> {
+    actionInvocationId: string;
+    tenantId: string;
+    spaceId: string;
+    actorId: string;
+    actorType: ActorType;
+    correlationId: string;
+    causationId?: string;
+    db: TDb;
+    services?: FabricRuntimeServices;
+}
+interface ActionResult {
+    success: boolean;
+    data?: Record<string, unknown>;
+    error?: string;
+}
+type ActionHandler<TDb = unknown> = (ctx: ActionContext<TDb>, params: unknown) => Promise<ActionResult>;
+interface AdapterStepRetryPolicy {
+    idempotent: boolean;
+    maxAttempts?: number;
+    initialDelayMs?: number;
+    backoffMultiplier?: number;
+    maxDelayMs?: number;
+}
+interface AdapterStep {
+    adapterType: string;
+    operation: string;
+    retryPolicy?: AdapterStepRetryPolicy;
+    getInput: (params: unknown, handlerResult: Record<string, unknown>) => Record<string, unknown> | undefined;
+}
+interface ActionStateMachineBinding {
+    entityType: string;
+    targetState: string | ((params: unknown) => string);
+    getEntityId: (params: unknown) => string | undefined;
+}
+interface ActionDefinition<TDb = unknown> {
+    actionId: ActionId;
+    namespace: string;
+    version: number;
+    schema: SchemaValidator;
+    handler?: ActionHandler<TDb>;
+    requiredRoles?: string[];
+    requiredPermissions?: string[];
+    policies?: `${string}.v${number}`[];
+    emitsEvents: string[];
+    idempotent: boolean;
+    mutatesDomain: boolean;
+    stateMachine?: ActionStateMachineBinding;
+    adapterSteps?: AdapterStep[];
+    /**
+     * If "saga", the action is a multi-step orchestration. The worker dispatches
+     * to a registered saga implementation instead of running `handler` directly.
+     */
+    kind?: "atomic" | "saga";
+}
+interface SagaContext {
+    actionInvocationId: string;
+    tenantId: string;
+    spaceId: string;
+    parameters: unknown;
+    sleep?: (delayMs: number) => Promise<void>;
+    query?: <T = unknown>(model: string, operation: string, args: unknown) => Promise<T>;
+}
+interface SagaChildActionInput {
+    suffix: string;
+    actionId: string;
+    parameters: Record<string, unknown>;
+}
+type SagaRunChild = (input: SagaChildActionInput) => Promise<Record<string, unknown>>;
+interface SagaCompletionEvent {
+    eventType: string;
+    subjectType: string;
+    subjectId: string;
+    payload: unknown;
+    eventSchemaVersion?: number;
+}
+interface SagaCompletion {
+    resultData: Record<string, unknown>;
+    event?: SagaCompletionEvent;
+}
+type SagaImplementation = (ctx: SagaContext, runChild: SagaRunChild) => Promise<SagaCompletion>;
+declare function assertActionId(actionId: string): asserts actionId is ActionId;
+declare function registerAction(definition: ActionDefinition): void;
+declare function resolveAction(actionId: ActionId): ActionDefinition | undefined;
+declare function isRegisteredActionId(actionId: string): actionId is ActionId;
+declare function resolveRegisteredAction(actionId: string): ActionDefinition | undefined;
+declare function getRegisteredActionIds(): ActionId[];
+declare function registerActionIfMissing(definition: ActionDefinition): void;
+
+export { ACTOR_TYPES, type ActionContext, type ActionDefinition, type ActionHandler, type ActionId, type ActionResult, type ActionStateMachineBinding, type ActionStatus, type ActorType, type AdapterStep, type AdapterStepRetryPolicy, type FabricRuntimeServices, type SagaChildActionInput, type SagaCompletion, type SagaCompletionEvent, type SagaContext, type SagaImplementation, type SagaRunChild, type SchemaParseIssue, type SchemaParseResult, type SchemaValidator, assertActionId, assertActorType, getRegisteredActionIds, isActorType, isRegisteredActionId, registerAction, registerActionIfMissing, resolveAction, resolveRegisteredAction };

package/dist/adapters/index.cjs

@@ -0,0 +1,28 @@
+'use strict';
+
+var chunkNPVIFZQV_cjs = require('../chunk-NPVIFZQV.cjs');
+
+
+
+Object.defineProperty(exports, "AdapterRegistry", {
+  enumerable: true,
+  get: function () { return chunkNPVIFZQV_cjs.AdapterRegistry; }
+});
+Object.defineProperty(exports, "MissingAdapterRegistrationError", {
+  enumerable: true,
+  get: function () { return chunkNPVIFZQV_cjs.MissingAdapterRegistrationError; }
+});
+Object.defineProperty(exports, "executeWithAdapterRetry", {
+  enumerable: true,
+  get: function () { return chunkNPVIFZQV_cjs.executeWithAdapterRetry; }
+});
+Object.defineProperty(exports, "getRetryDelayMs", {
+  enumerable: true,
+  get: function () { return chunkNPVIFZQV_cjs.getRetryDelayMs; }
+});
+Object.defineProperty(exports, "resolveAdapterRetryPolicy", {
+  enumerable: true,
+  get: function () { return chunkNPVIFZQV_cjs.resolveAdapterRetryPolicy; }
+});
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/adapters/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.cjs"}

package/dist/adapters/index.d.cts

@@ -0,0 +1,83 @@
+interface AdapterExecutionContext {
+    tenantId: string;
+    spaceId: string;
+    actionInvocationId: string;
+    adapterInvocationId: string;
+    correlationId: string;
+    causationId?: string;
+    attempt: number;
+    maxAttempts: number;
+}
+interface AdapterExecutionResult {
+    success: boolean;
+    correlationId?: string;
+    error?: string;
+}
+type AdapterExecutor = (input: Record<string, unknown>, context: AdapterExecutionContext) => Promise<AdapterExecutionResult>;
+interface AdapterRetryPolicy {
+    /** External calls must explicitly opt into retry by being idempotent. */
+    idempotent: boolean;
+    /** Total attempts including the first call. Non-idempotent policies are forced to 1. */
+    maxAttempts?: number;
+    /** First backoff delay in milliseconds. */
+    initialDelayMs?: number;
+    /** Exponential multiplier applied after each failed attempt. */
+    backoffMultiplier?: number;
+    /** Upper bound for any single retry delay in milliseconds. */
+    maxDelayMs?: number;
+}
+interface ResolvedAdapterRetryPolicy {
+    idempotent: boolean;
+    maxAttempts: number;
+    initialDelayMs: number;
+    backoffMultiplier: number;
+    maxDelayMs: number;
+}
+interface AdapterCircuitBreakerConfig {
+    mode: "monitor" | "enforce";
+    failureThreshold: number;
+    windowMs: number;
+    cooldownMs: number;
+    minimumSamples?: number;
+}
+interface AdapterImplementation {
+    adapterType: string;
+    operation: string;
+    vendor: string;
+    /** Whether this adapter operation can be safely retried by default. */
+    idempotent: boolean;
+    retryPolicy?: AdapterRetryPolicy;
+    /** Defaults to monitor-only; enforce mode must be explicitly configured. */
+    circuitBreaker?: AdapterCircuitBreakerConfig;
+    execute: AdapterExecutor;
+}
+interface AdapterAttempt<T> {
+    attempt: number;
+    result?: T;
+    error?: string;
+    willRetry: boolean;
+    nextDelayMs?: number;
+}
+interface ExecuteWithRetryOptions<T> {
+    policy?: AdapterRetryPolicy;
+    defaultIdempotent: boolean;
+    execute: (attempt: number, maxAttempts: number) => Promise<T>;
+    isSuccessful: (result: T) => boolean;
+    getError: (result: T) => string | undefined;
+    sleep?: (delayMs: number) => Promise<void>;
+    onAttempt?: (attempt: AdapterAttempt<T>) => Promise<void> | void;
+}
+declare class MissingAdapterRegistrationError extends Error {
+    constructor(adapterType: string, operation: string);
+}
+declare class AdapterRegistry {
+    private readonly adapters;
+    register(adapter: AdapterImplementation): void;
+    resolve(adapterType: string, operation: string): AdapterImplementation | undefined;
+    require(adapterType: string, operation: string): AdapterImplementation;
+}
+declare function resolveAdapterRetryPolicy(policy: AdapterRetryPolicy | undefined, defaultIdempotent: boolean): ResolvedAdapterRetryPolicy;
+declare function getRetryDelayMs(attempt: number, policy: ResolvedAdapterRetryPolicy): number;
+declare function executeWithAdapterRetry<T>(options: ExecuteWithRetryOptions<T>): Promise<T>;
+
+export { type AdapterAttempt, type AdapterCircuitBreakerConfig, type AdapterExecutionContext, type AdapterExecutionResult, type AdapterExecutor, type AdapterImplementation, AdapterRegistry, type AdapterRetryPolicy, type ExecuteWithRetryOptions, MissingAdapterRegistrationError, type ResolvedAdapterRetryPolicy, executeWithAdapterRetry, getRetryDelayMs, resolveAdapterRetryPolicy };

package/dist/chunk-7KJHGAZY.cjs

@@ -0,0 +1,99 @@
+'use strict';
+
+var assert = require('assert');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var assert__default = /*#__PURE__*/_interopDefault(assert);
+
+// displays/index.ts
+var registry = /* @__PURE__ */ new Map();
+function registerDisplayRenderer(eventType, renderer) {
+  registry.set(eventType, renderer);
+}
+function resolveDisplayRenderer(eventType) {
+  return registry.get(eventType);
+}
+function denormalizeDisplaySnapshot(payload) {
+  if (payload !== null && typeof payload === "object" && "_displaySnapshot" in payload && payload._displaySnapshot !== null && typeof payload._displaySnapshot === "object" && "title" in payload._displaySnapshot) {
+    return payload._displaySnapshot;
+  }
+  if (payload !== null && typeof payload === "object" && "_projectionSnapshot" in payload && payload._projectionSnapshot !== null && typeof payload._projectionSnapshot === "object" && "display" in payload._projectionSnapshot && payload._projectionSnapshot.display !== null && typeof payload._projectionSnapshot.display === "object" && "title" in payload._projectionSnapshot.display) {
+    const snapshot = payload._projectionSnapshot;
+    return {
+      ...snapshot.display,
+      _cachedDisplay: {
+        source: "projection_snapshot",
+        cursor: snapshot.eventCursor,
+        checksum: snapshot.checksum,
+        generatedAt: snapshot.updatedAt
+      }
+    };
+  }
+  return void 0;
+}
+async function renderEventDisplay(eventType, payload, ctx) {
+  const snapshot = denormalizeDisplaySnapshot(payload);
+  if (snapshot) {
+    return snapshot;
+  }
+  const renderer = resolveDisplayRenderer(eventType);
+  if (!renderer) {
+    return {
+      title: eventType,
+      subtitle: "No display renderer registered for this event type."
+    };
+  }
+  return await renderer(payload, ctx);
+}
+async function _runInlineTests() {
+  const testEventType = "__TestEvent__";
+  registerDisplayRenderer(testEventType, (payload) => ({
+    title: `Test: ${payload.name}`,
+    subtitle: "registered renderer"
+  }));
+  const renderer = resolveDisplayRenderer(testEventType);
+  assert__default.default.ok(renderer, "resolveDisplayRenderer should return the registered renderer");
+  const result = await renderEventDisplay(testEventType, { name: "Alice" });
+  assert__default.default.strictEqual(result.title, "Test: Alice");
+  assert__default.default.strictEqual(result.subtitle, "registered renderer");
+  const snapshot = {
+    title: "Snapshot Title",
+    subtitle: "snapshot subtitle",
+    stateLabel: "archived",
+    primaryFacts: [{ label: "ID", value: "123" }]
+  };
+  const snapshotResult = await renderEventDisplay(testEventType, {
+    _displaySnapshot: snapshot
+  });
+  assert__default.default.deepStrictEqual(snapshotResult, snapshot);
+  const fallback = await renderEventDisplay("__UnknownEvent__", {});
+  assert__default.default.strictEqual(fallback.title, "__UnknownEvent__");
+  assert__default.default.strictEqual(fallback.subtitle, "No display renderer registered for this event type.");
+  registerDisplayRenderer("__AsyncEvent__", async (_payload, ctx) => {
+    return {
+      title: `Async: ${ctx?.tenantId ?? "no-ctx"}`
+    };
+  });
+  const asyncResult = await renderEventDisplay(
+    "__AsyncEvent__",
+    {},
+    { tenantId: "t-1", spaceId: "s-1", db: {} }
+  );
+  assert__default.default.strictEqual(asyncResult.title, "Async: t-1");
+  console.log("\u2705 display engine inline tests passed");
+}
+if ((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('chunk-7KJHGAZY.cjs', document.baseURI).href)) === `file://${process.argv[1]}`) {
+  _runInlineTests().catch((err) => {
+    console.error("\u274C display engine inline tests failed", err);
+    process.exit(1);
+  });
+}
+
+exports.denormalizeDisplaySnapshot = denormalizeDisplaySnapshot;
+exports.registerDisplayRenderer = registerDisplayRenderer;
+exports.renderEventDisplay = renderEventDisplay;
+exports.resolveDisplayRenderer = resolveDisplayRenderer;
+//# sourceMappingURL=chunk-7KJHGAZY.cjs.map
+//# sourceMappingURL=chunk-7KJHGAZY.cjs.map

package/dist/chunk-7KJHGAZY.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../displays/index.ts"],"names":["assert"],"mappings":"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","file":"chunk-7KJHGAZY.cjs","sourcesContent":["import assert from \"node:assert\";\n\nexport interface DisplayDescriptor {\n\ttitle: string;\n\tsubtitle?: string;\n\tstateLabel?: string;\n\tprimaryFacts?: Array<{ label: string; value: string }>;\n}\n\nexport interface CachedDisplayDescriptor extends DisplayDescriptor {\n\t_cachedDisplay?: {\n\t\tsource: \"event_payload\" | \"projection_snapshot\";\n\t\tcursor?: string | null;\n\t\tchecksum?: string;\n\t\tgeneratedAt?: string;\n\t};\n}\n\nexport type DisplayDatabaseClient = any;\n\nexport interface DisplayContext<TDb = DisplayDatabaseClient> {\n\ttenantId: string;\n\tspaceId: string;\n\tdb: TDb;\n}\n\nexport type DisplayRenderer = (\n\tpayload: unknown,\n\tctx?: DisplayContext,\n) => DisplayDescriptor | Promise<DisplayDescriptor>;\n\nexport interface DisplayRendererRegistration {\n\teventType: string;\n\trenderer: DisplayRenderer;\n}\n\nconst registry = new Map<string, DisplayRenderer>();\n\nexport function registerDisplayRenderer(eventType: string, renderer: DisplayRenderer): void {\n\tregistry.set(eventType, renderer);\n}\n\nexport function resolveDisplayRenderer(eventType: string): DisplayRenderer | undefined {\n\treturn registry.get(eventType);\n}\n\nexport function denormalizeDisplaySnapshot(payload: unknown): CachedDisplayDescriptor | undefined {\n\tif (\n\t\tpayload !== null &&\n\t\ttypeof payload === \"object\" &&\n\t\t\"_displaySnapshot\" in payload &&\n\t\tpayload._displaySnapshot !== null &&\n\t\ttypeof payload._displaySnapshot === \"object\" &&\n\t\t\"title\" in payload._displaySnapshot\n\t) {\n\t\treturn payload._displaySnapshot as CachedDisplayDescriptor;\n\t}\n\n\tif (\n\t\tpayload !== null &&\n\t\ttypeof payload === \"object\" &&\n\t\t\"_projectionSnapshot\" in payload &&\n\t\tpayload._projectionSnapshot !== null &&\n\t\ttypeof payload._projectionSnapshot === \"object\" &&\n\t\t\"display\" in payload._projectionSnapshot &&\n\t\tpayload._projectionSnapshot.display !== null &&\n\t\ttypeof payload._projectionSnapshot.display === \"object\" &&\n\t\t\"title\" in payload._projectionSnapshot.display\n\t) {\n\t\tconst snapshot = payload._projectionSnapshot as {\n\t\t\tdisplay: DisplayDescriptor;\n\t\t\teventCursor?: string | null;\n\t\t\tchecksum?: string;\n\t\t\tupdatedAt?: string;\n\t\t};\n\t\treturn {\n\t\t\t...snapshot.display,\n\t\t\t_cachedDisplay: {\n\t\t\t\tsource: \"projection_snapshot\",\n\t\t\t\tcursor: snapshot.eventCursor,\n\t\t\t\tchecksum: snapshot.checksum,\n\t\t\t\tgeneratedAt: snapshot.updatedAt,\n\t\t\t},\n\t\t};\n\t}\n\treturn undefined;\n}\n\nexport async function renderEventDisplay(\n\teventType: string,\n\tpayload: unknown,\n\tctx?: DisplayContext,\n): Promise<CachedDisplayDescriptor> {\n\tconst snapshot = denormalizeDisplaySnapshot(payload);\n\tif (snapshot) {\n\t\treturn snapshot;\n\t}\n\n\tconst renderer = resolveDisplayRenderer(eventType);\n\tif (!renderer) {\n\t\treturn {\n\t\t\ttitle: eventType,\n\t\t\tsubtitle: \"No display renderer registered for this event type.\",\n\t\t};\n\t}\n\n\treturn await renderer(payload, ctx);\n}\n\n// Inline test: verify registry round-trip, snapshot denormalization, and fallback.\nasync function _runInlineTests(): Promise<void> {\n\tconst testEventType = \"__TestEvent__\";\n\n\t// 1. Registry round-trip\n\tregisterDisplayRenderer(testEventType, (payload) => ({\n\t\ttitle: `Test: ${(payload as { name: string }).name}`,\n\t\tsubtitle: \"registered renderer\",\n\t}));\n\n\tconst renderer = resolveDisplayRenderer(testEventType);\n\tassert.ok(renderer, \"resolveDisplayRenderer should return the registered renderer\");\n\n\tconst result = await renderEventDisplay(testEventType, { name: \"Alice\" });\n\tassert.strictEqual(result.title, \"Test: Alice\");\n\tassert.strictEqual(result.subtitle, \"registered renderer\");\n\n\t// 2. Snapshot denormalization takes precedence over renderer\n\tconst snapshot: DisplayDescriptor = {\n\t\ttitle: \"Snapshot Title\",\n\t\tsubtitle: \"snapshot subtitle\",\n\t\tstateLabel: \"archived\",\n\t\tprimaryFacts: [{ label: \"ID\", value: \"123\" }],\n\t};\n\tconst snapshotResult = await renderEventDisplay(testEventType, {\n\t\t_displaySnapshot: snapshot,\n\t});\n\tassert.deepStrictEqual(snapshotResult, snapshot);\n\n\t// 3. Fallback for unregistered event type\n\tconst fallback = await renderEventDisplay(\"__UnknownEvent__\", {});\n\tassert.strictEqual(fallback.title, \"__UnknownEvent__\");\n\tassert.strictEqual(fallback.subtitle, \"No display renderer registered for this event type.\");\n\n\t// 4. Async renderer with context\n\tregisterDisplayRenderer(\"__AsyncEvent__\", async (_payload, ctx) => {\n\t\treturn {\n\t\t\ttitle: `Async: ${ctx?.tenantId ?? \"no-ctx\"}`,\n\t\t};\n\t});\n\tconst asyncResult = await renderEventDisplay(\n\t\t\"__AsyncEvent__\",\n\t\t{},\n\t\t{ tenantId: \"t-1\", spaceId: \"s-1\", db: {} },\n\t);\n\tassert.strictEqual(asyncResult.title, \"Async: t-1\");\n\n\tconsole.log(\"✅ display engine inline tests passed\");\n}\n\nif (import.meta.url === `file://${process.argv[1]}`) {\n\t_runInlineTests().catch((err) => {\n\t\tconsole.error(\"❌ display engine inline tests failed\", err);\n\t\tprocess.exit(1);\n\t});\n}\n"]}