@fabricorg/platform 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fabric
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+# @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.
+
+## Portability Scope
+
+**`@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.
+
+**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.
+
+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.)
+
+## Subpath Exports
+
+| 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) |
+
+## Action Lifecycle
+
+Every domain mutation flows through a single platform pipeline:
+
+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.
+
+`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.
+
+## Module Contract
+
+Verticals declare modules as `FabricModule<TDb>`:
+
+```ts
+import type { FabricModule } from "@fabricorg/platform/modules";
+import type { Prisma } from "@repo/database";
+
+export const lendingModule: FabricModule<Prisma.TransactionClient> = {
+  namespace: "lending",
+  version: "1.0.0",
+  objectTypes: ["Vehicle", "Party", "Location", "Document"],
+  actions: [...],
+  policies: [...],
+  stateMachines: [...],
+  displayRenderers: [...],
+};
+```
+
+Apps compose modules explicitly at startup:
+
+```ts
+import { registerFabricModules } from "@fabricorg/platform/modules";
+import { lendingModule } from "@repo/lending";
+import { messagingModule } from "@repo/messaging";
+
+registerFabricModules([messagingModule, lendingModule]);
+```
+
+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.
+
+## Saga Actions
+
+Multi-step orchestrations declare `kind: "saga"` on the `ActionDefinition` and ship a `SagaImplementation` alongside:
+
+```ts
+import type { SagaImplementation } from "@fabricorg/platform/actions";
+
+export const ingestSaga: SagaImplementation = async (ctx, runChild) => {
+  const child = await runChild({
+    suffix: "step-1",
+    actionId: "lending.receive_lead_payload",
+    parameters: { ... },
+  });
+  // ... orchestrate further child actions ...
+  return {
+    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.
+
+## Versioning
+
+`0.x` while contracts evolve. `1.0` only after at least two materially different verticals validate the API.

package/dist/actions/index.d.ts

@@ -0,0 +1,114 @@
+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;
+}
+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/actions/index.js

@@ -0,0 +1,59 @@
+// actions/index.ts
+var ACTOR_TYPES = [
+  "natural_person",
+  "agent",
+  "system",
+  "service_account",
+  "external_system",
+  "integration"
+];
+function isActorType(value) {
+  return ACTOR_TYPES.includes(value);
+}
+function assertActorType(value) {
+  if (!isActorType(value)) {
+    throw new Error(`Invalid actorType: ${value}`);
+  }
+}
+var registry = /* @__PURE__ */ new Map();
+function assertActionId(actionId) {
+  if (!/^[a-z][a-z0-9-]*\.[a-z][a-z0-9_]*$/.test(actionId)) {
+    throw new Error(`Invalid action ID: ${actionId}`);
+  }
+}
+function registerAction(definition) {
+  assertActionId(definition.actionId);
+  if (registry.has(definition.actionId)) {
+    throw new Error(`Action "${definition.actionId}" is already registered`);
+  }
+  if (definition.mutatesDomain && definition.emitsEvents.length === 0) {
+    throw new Error(
+      `Action "${definition.actionId}" mutates domain but emits no events. Every mutating action must emit at least one AssetEvent.`
+    );
+  }
+  registry.set(definition.actionId, definition);
+}
+function resolveAction(actionId) {
+  return registry.get(actionId);
+}
+function isRegisteredActionId(actionId) {
+  return registry.has(actionId);
+}
+function resolveRegisteredAction(actionId) {
+  if (!isRegisteredActionId(actionId)) {
+    return void 0;
+  }
+  return resolveAction(actionId);
+}
+function getRegisteredActionIds() {
+  return Array.from(registry.keys());
+}
+function registerActionIfMissing(definition) {
+  if (!registry.has(definition.actionId)) {
+    registerAction(definition);
+  }
+}
+
+export { ACTOR_TYPES, assertActionId, assertActorType, getRegisteredActionIds, isActorType, isRegisteredActionId, registerAction, registerActionIfMissing, resolveAction, resolveRegisteredAction };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/actions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../actions/index.ts"],"names":[],"mappings":";AAwBO,IAAM,WAAA,GAAoC;AAAA,EAChD,gBAAA;AAAA,EACA,OAAA;AAAA,EACA,QAAA;AAAA,EACA,iBAAA;AAAA,EACA,iBAAA;AAAA,EACA;AACD;AAEO,SAAS,YAAY,KAAA,EAAmC;AAC9D,EAAA,OAAQ,WAAA,CAAkC,SAAS,KAAK,CAAA;AACzD;AAEO,SAAS,gBAAgB,KAAA,EAA2C;AAC1E,EAAA,IAAI,CAAC,WAAA,CAAY,KAAK,CAAA,EAAG;AACxB,IAAA,MAAM,IAAI,KAAA,CAAM,CAAA,mBAAA,EAAsB,KAAK,CAAA,CAAE,CAAA;AAAA,EAC9C;AACD;AAoHA,IAAM,QAAA,uBAAe,GAAA,EAAgC;AAE9C,SAAS,eAAe,QAAA,EAAgD;AAC9E,EAAA,IAAI,CAAC,oCAAA,CAAqC,IAAA,CAAK,QAAQ,CAAA,EAAG;AACzD,IAAA,MAAM,IAAI,KAAA,CAAM,CAAA,mBAAA,EAAsB,QAAQ,CAAA,CAAE,CAAA;AAAA,EACjD;AACD;AAEO,SAAS,eAAe,UAAA,EAAoC;AAClE,EAAA,cAAA,CAAe,WAAW,QAAQ,CAAA;AAElC,EAAA,IAAI,QAAA,CAAS,GAAA,CAAI,UAAA,CAAW,QAAQ,CAAA,EAAG;AACtC,IAAA,MAAM,IAAI,KAAA,CAAM,CAAA,QAAA,EAAW,UAAA,CAAW,QAAQ,CAAA,uBAAA,CAAyB,CAAA;AAAA,EACxE;AAEA,EAAA,IAAI,UAAA,CAAW,aAAA,IAAiB,UAAA,CAAW,WAAA,CAAY,WAAW,CAAA,EAAG;AACpE,IAAA,MAAM,IAAI,KAAA;AAAA,MACT,CAAA,QAAA,EAAW,WAAW,QAAQ,CAAA,8FAAA;AAAA,KAE/B;AAAA,EACD;AAEA,EAAA,QAAA,CAAS,GAAA,CAAI,UAAA,CAAW,QAAA,EAAU,UAAU,CAAA;AAC7C;AAEO,SAAS,cAAc,QAAA,EAAkD;AAC/E,EAAA,OAAO,QAAA,CAAS,IAAI,QAAQ,CAAA;AAC7B;AAEO,SAAS,qBAAqB,QAAA,EAAwC;AAC5E,EAAA,OAAO,QAAA,CAAS,IAAI,QAAoB,CAAA;AACzC;AAEO,SAAS,wBAAwB,QAAA,EAAgD;AACvF,EAAA,IAAI,CAAC,oBAAA,CAAqB,QAAQ,CAAA,EAAG;AACpC,IAAA,OAAO,MAAA;AAAA,EACR;AAEA,EAAA,OAAO,cAAc,QAAQ,CAAA;AAC9B;AAEO,SAAS,sBAAA,GAAqC;AACpD,EAAA,OAAO,KAAA,CAAM,IAAA,CAAK,QAAA,CAAS,IAAA,EAAM,CAAA;AAClC;AAEO,SAAS,wBAAwB,UAAA,EAAoC;AAC3E,EAAA,IAAI,CAAC,QAAA,CAAS,GAAA,CAAI,UAAA,CAAW,QAAQ,CAAA,EAAG;AACvC,IAAA,cAAA,CAAe,UAAU,CAAA;AAAA,EAC1B;AACD","file":"index.js","sourcesContent":["export type ActionId = `${string}.${string}`;\n\nexport interface SchemaParseIssue {\n\tpath: PropertyKey[];\n\tmessage: string;\n}\n\nexport type SchemaParseResult<T = unknown> =\n\t| { success: true; data: T }\n\t| { success: false; error: { issues: SchemaParseIssue[] } };\n\nexport interface SchemaValidator<T = unknown> {\n\tparse(input: unknown): T;\n\tsafeParse(input: unknown): SchemaParseResult<T>;\n}\n\nexport type ActorType =\n\t| \"natural_person\"\n\t| \"agent\"\n\t| \"system\"\n\t| \"service_account\"\n\t| \"external_system\"\n\t| \"integration\";\n\nexport const ACTOR_TYPES: readonly ActorType[] = [\n\t\"natural_person\",\n\t\"agent\",\n\t\"system\",\n\t\"service_account\",\n\t\"external_system\",\n\t\"integration\",\n] as const;\n\nexport function isActorType(value: string): value is ActorType {\n\treturn (ACTOR_TYPES as readonly string[]).includes(value);\n}\n\nexport function assertActorType(value: string): asserts value is ActorType {\n\tif (!isActorType(value)) {\n\t\tthrow new Error(`Invalid actorType: ${value}`);\n\t}\n}\n\nexport type ActionStatus =\n\t| \"pending\"\n\t| \"running\"\n\t| \"completed\"\n\t| \"failed\"\n\t| \"blocked_by_policy\"\n\t| \"waiting_for_approval\"\n\t| \"validation_failed\";\n\nexport interface FabricRuntimeServices {\n\treadonly [serviceName: string]: unknown;\n}\n\nexport interface ActionContext<TDb = unknown> {\n\tactionInvocationId: string;\n\ttenantId: string;\n\tspaceId: string;\n\tactorId: string;\n\tactorType: ActorType;\n\tcorrelationId: string;\n\tcausationId?: string;\n\tdb: TDb;\n\tservices?: FabricRuntimeServices;\n}\n\nexport interface ActionResult {\n\tsuccess: boolean;\n\tdata?: Record<string, unknown>;\n\terror?: string;\n}\n\nexport type ActionHandler<TDb = unknown> = (\n\tctx: ActionContext<TDb>,\n\tparams: unknown,\n) => Promise<ActionResult>;\n\nexport interface AdapterStepRetryPolicy {\n\tidempotent: boolean;\n\tmaxAttempts?: number;\n\tinitialDelayMs?: number;\n\tbackoffMultiplier?: number;\n\tmaxDelayMs?: number;\n}\n\nexport interface AdapterStep {\n\tadapterType: string;\n\toperation: string;\n\tretryPolicy?: AdapterStepRetryPolicy;\n\tgetInput: (\n\t\tparams: unknown,\n\t\thandlerResult: Record<string, unknown>,\n\t) => Record<string, unknown> | undefined;\n}\n\nexport interface ActionStateMachineBinding {\n\tentityType: string;\n\ttargetState: string | ((params: unknown) => string);\n\tgetEntityId: (params: unknown) => string | undefined;\n}\n\nexport interface ActionDefinition<TDb = unknown> {\n\tactionId: ActionId;\n\tnamespace: string;\n\tversion: number;\n\tschema: SchemaValidator;\n\thandler: ActionHandler<TDb>;\n\trequiredRoles?: string[];\n\trequiredPermissions?: string[];\n\tpolicies?: `${string}.v${number}`[];\n\temitsEvents: string[];\n\tidempotent: boolean;\n\tmutatesDomain: boolean;\n\tstateMachine?: ActionStateMachineBinding;\n\tadapterSteps?: AdapterStep[];\n\t/**\n\t * If \"saga\", the action is a multi-step orchestration. The worker dispatches\n\t * to a registered saga implementation instead of running `handler` directly.\n\t */\n\tkind?: \"atomic\" | \"saga\";\n}\n\nexport interface SagaContext {\n\tactionInvocationId: string;\n\ttenantId: string;\n\tspaceId: string;\n\tparameters: unknown;\n}\n\nexport interface SagaChildActionInput {\n\tsuffix: string;\n\tactionId: string;\n\tparameters: Record<string, unknown>;\n}\n\nexport type SagaRunChild = (input: SagaChildActionInput) => Promise<Record<string, unknown>>;\n\nexport interface SagaCompletionEvent {\n\teventType: string;\n\tsubjectType: string;\n\tsubjectId: string;\n\tpayload: unknown;\n\teventSchemaVersion?: number;\n}\n\nexport interface SagaCompletion {\n\tresultData: Record<string, unknown>;\n\tevent?: SagaCompletionEvent;\n}\n\nexport type SagaImplementation = (\n\tctx: SagaContext,\n\trunChild: SagaRunChild,\n) => Promise<SagaCompletion>;\n\nconst registry = new Map<ActionId, ActionDefinition>();\n\nexport function assertActionId(actionId: string): asserts actionId is ActionId {\n\tif (!/^[a-z][a-z0-9-]*\\.[a-z][a-z0-9_]*$/.test(actionId)) {\n\t\tthrow new Error(`Invalid action ID: ${actionId}`);\n\t}\n}\n\nexport function registerAction(definition: ActionDefinition): void {\n\tassertActionId(definition.actionId);\n\n\tif (registry.has(definition.actionId)) {\n\t\tthrow new Error(`Action \"${definition.actionId}\" is already registered`);\n\t}\n\n\tif (definition.mutatesDomain && definition.emitsEvents.length === 0) {\n\t\tthrow new Error(\n\t\t\t`Action \"${definition.actionId}\" mutates domain but emits no events. ` +\n\t\t\t\t`Every mutating action must emit at least one AssetEvent.`,\n\t\t);\n\t}\n\n\tregistry.set(definition.actionId, definition);\n}\n\nexport function resolveAction(actionId: ActionId): ActionDefinition | undefined {\n\treturn registry.get(actionId);\n}\n\nexport function isRegisteredActionId(actionId: string): actionId is ActionId {\n\treturn registry.has(actionId as ActionId);\n}\n\nexport function resolveRegisteredAction(actionId: string): ActionDefinition | undefined {\n\tif (!isRegisteredActionId(actionId)) {\n\t\treturn undefined;\n\t}\n\n\treturn resolveAction(actionId);\n}\n\nexport function getRegisteredActionIds(): ActionId[] {\n\treturn Array.from(registry.keys());\n}\n\nexport function registerActionIfMissing(definition: ActionDefinition): void {\n\tif (!registry.has(definition.actionId)) {\n\t\tregisterAction(definition);\n\t}\n}\n"]}

package/dist/adapters/index.d.ts

@@ -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/adapters/index.js

@@ -0,0 +1,101 @@
+// adapters/index.ts
+function adapterKey(adapterType, operation) {
+  return `${adapterType}:${operation}`;
+}
+var MissingAdapterRegistrationError = class extends Error {
+  constructor(adapterType, operation) {
+    super(`No adapter registered for adapterType "${adapterType}" and operation "${operation}"`);
+    this.name = "MissingAdapterRegistrationError";
+  }
+};
+var AdapterRegistry = class {
+  adapters = /* @__PURE__ */ new Map();
+  register(adapter) {
+    const key = adapterKey(adapter.adapterType, adapter.operation);
+    if (this.adapters.has(key)) {
+      throw new Error(
+        `Adapter already registered for adapterType "${adapter.adapterType}" and operation "${adapter.operation}"`
+      );
+    }
+    this.adapters.set(key, adapter);
+  }
+  resolve(adapterType, operation) {
+    return this.adapters.get(adapterKey(adapterType, operation));
+  }
+  require(adapterType, operation) {
+    const adapter = this.resolve(adapterType, operation);
+    if (!adapter) {
+      throw new MissingAdapterRegistrationError(adapterType, operation);
+    }
+    return adapter;
+  }
+};
+var DEFAULT_RETRY_POLICY = {
+  maxAttempts: 3,
+  initialDelayMs: 100,
+  backoffMultiplier: 2,
+  maxDelayMs: 1e3
+};
+var NO_RETRY_POLICY = {
+  idempotent: false,
+  maxAttempts: 1,
+  initialDelayMs: 0,
+  backoffMultiplier: 1,
+  maxDelayMs: 0
+};
+function resolveAdapterRetryPolicy(policy, defaultIdempotent) {
+  const idempotent = policy?.idempotent ?? defaultIdempotent;
+  if (!idempotent) {
+    return NO_RETRY_POLICY;
+  }
+  return {
+    idempotent: true,
+    maxAttempts: Math.max(1, Math.min(policy?.maxAttempts ?? DEFAULT_RETRY_POLICY.maxAttempts, 5)),
+    initialDelayMs: Math.max(0, policy?.initialDelayMs ?? DEFAULT_RETRY_POLICY.initialDelayMs),
+    backoffMultiplier: Math.max(
+      1,
+      policy?.backoffMultiplier ?? DEFAULT_RETRY_POLICY.backoffMultiplier
+    ),
+    maxDelayMs: Math.max(0, policy?.maxDelayMs ?? DEFAULT_RETRY_POLICY.maxDelayMs)
+  };
+}
+function getRetryDelayMs(attempt, policy) {
+  const exponentialDelay = policy.initialDelayMs * policy.backoffMultiplier ** Math.max(0, attempt - 1);
+  return Math.min(exponentialDelay, policy.maxDelayMs);
+}
+async function executeWithAdapterRetry(options) {
+  const policy = resolveAdapterRetryPolicy(options.policy, options.defaultIdempotent);
+  const sleep = options.sleep ?? ((delayMs) => new Promise((resolve) => setTimeout(resolve, delayMs)));
+  let lastError;
+  for (let attempt = 1; attempt <= policy.maxAttempts; attempt++) {
+    try {
+      const result = await options.execute(attempt, policy.maxAttempts);
+      if (options.isSuccessful(result)) {
+        await options.onAttempt?.({ attempt, result, willRetry: false });
+        return result;
+      }
+      lastError = options.getError(result) ?? "Adapter returned unsuccessful result";
+      const willRetry = policy.idempotent && attempt < policy.maxAttempts;
+      const nextDelayMs = willRetry ? getRetryDelayMs(attempt, policy) : void 0;
+      await options.onAttempt?.({ attempt, result, error: lastError, willRetry, nextDelayMs });
+      if (!willRetry) {
+        return result;
+      }
+      await sleep(nextDelayMs ?? 0);
+    } catch (error) {
+      lastError = error instanceof Error ? error.message : String(error);
+      const willRetry = policy.idempotent && attempt < policy.maxAttempts;
+      const nextDelayMs = willRetry ? getRetryDelayMs(attempt, policy) : void 0;
+      await options.onAttempt?.({ attempt, error: lastError, willRetry, nextDelayMs });
+      if (!willRetry) {
+        throw error;
+      }
+      await sleep(nextDelayMs ?? 0);
+    }
+  }
+  throw new Error(lastError ?? "Adapter retry exhausted");
+}
+
+export { AdapterRegistry, MissingAdapterRegistrationError, executeWithAdapterRetry, getRetryDelayMs, resolveAdapterRetryPolicy };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/adapters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../adapters/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["export interface AdapterExecutionContext {\n\ttenantId: string;\n\tspaceId: string;\n\tactionInvocationId: string;\n\tadapterInvocationId: string;\n\tcorrelationId: string;\n\tcausationId?: string;\n\tattempt: number;\n\tmaxAttempts: number;\n}\n\nexport interface AdapterExecutionResult {\n\tsuccess: boolean;\n\tcorrelationId?: string;\n\terror?: string;\n}\n\nexport type AdapterExecutor = (\n\tinput: Record<string, unknown>,\n\tcontext: AdapterExecutionContext,\n) => Promise<AdapterExecutionResult>;\n\nexport interface AdapterRetryPolicy {\n\t/** External calls must explicitly opt into retry by being idempotent. */\n\tidempotent: boolean;\n\t/** Total attempts including the first call. Non-idempotent policies are forced to 1. */\n\tmaxAttempts?: number;\n\t/** First backoff delay in milliseconds. */\n\tinitialDelayMs?: number;\n\t/** Exponential multiplier applied after each failed attempt. */\n\tbackoffMultiplier?: number;\n\t/** Upper bound for any single retry delay in milliseconds. */\n\tmaxDelayMs?: number;\n}\n\nexport interface ResolvedAdapterRetryPolicy {\n\tidempotent: boolean;\n\tmaxAttempts: number;\n\tinitialDelayMs: number;\n\tbackoffMultiplier: number;\n\tmaxDelayMs: number;\n}\n\nexport interface AdapterCircuitBreakerConfig {\n\tmode: \"monitor\" | \"enforce\";\n\tfailureThreshold: number;\n\twindowMs: number;\n\tcooldownMs: number;\n\tminimumSamples?: number;\n}\n\nexport interface AdapterImplementation {\n\tadapterType: string;\n\toperation: string;\n\tvendor: string;\n\t/** Whether this adapter operation can be safely retried by default. */\n\tidempotent: boolean;\n\tretryPolicy?: AdapterRetryPolicy;\n\t/** Defaults to monitor-only; enforce mode must be explicitly configured. */\n\tcircuitBreaker?: AdapterCircuitBreakerConfig;\n\texecute: AdapterExecutor;\n}\n\nexport interface AdapterAttempt<T> {\n\tattempt: number;\n\tresult?: T;\n\terror?: string;\n\twillRetry: boolean;\n\tnextDelayMs?: number;\n}\n\nexport interface ExecuteWithRetryOptions<T> {\n\tpolicy?: AdapterRetryPolicy;\n\tdefaultIdempotent: boolean;\n\texecute: (attempt: number, maxAttempts: number) => Promise<T>;\n\tisSuccessful: (result: T) => boolean;\n\tgetError: (result: T) => string | undefined;\n\tsleep?: (delayMs: number) => Promise<void>;\n\tonAttempt?: (attempt: AdapterAttempt<T>) => Promise<void> | void;\n}\n\nfunction adapterKey(adapterType: string, operation: string): string {\n\treturn `${adapterType}:${operation}`;\n}\n\nexport class MissingAdapterRegistrationError extends Error {\n\tconstructor(adapterType: string, operation: string) {\n\t\tsuper(`No adapter registered for adapterType \"${adapterType}\" and operation \"${operation}\"`);\n\t\tthis.name = \"MissingAdapterRegistrationError\";\n\t}\n}\n\nexport class AdapterRegistry {\n\tprivate readonly adapters = new Map<string, AdapterImplementation>();\n\n\tregister(adapter: AdapterImplementation): void {\n\t\tconst key = adapterKey(adapter.adapterType, adapter.operation);\n\t\tif (this.adapters.has(key)) {\n\t\t\tthrow new Error(\n\t\t\t\t`Adapter already registered for adapterType \"${adapter.adapterType}\" and operation \"${adapter.operation}\"`,\n\t\t\t);\n\t\t}\n\n\t\tthis.adapters.set(key, adapter);\n\t}\n\n\tresolve(adapterType: string, operation: string): AdapterImplementation | undefined {\n\t\treturn this.adapters.get(adapterKey(adapterType, operation));\n\t}\n\n\trequire(adapterType: string, operation: string): AdapterImplementation {\n\t\tconst adapter = this.resolve(adapterType, operation);\n\t\tif (!adapter) {\n\t\t\tthrow new MissingAdapterRegistrationError(adapterType, operation);\n\t\t}\n\n\t\treturn adapter;\n\t}\n}\n\nconst DEFAULT_RETRY_POLICY: ResolvedAdapterRetryPolicy = {\n\tidempotent: true,\n\tmaxAttempts: 3,\n\tinitialDelayMs: 100,\n\tbackoffMultiplier: 2,\n\tmaxDelayMs: 1_000,\n};\n\nconst NO_RETRY_POLICY: ResolvedAdapterRetryPolicy = {\n\tidempotent: false,\n\tmaxAttempts: 1,\n\tinitialDelayMs: 0,\n\tbackoffMultiplier: 1,\n\tmaxDelayMs: 0,\n};\n\nexport function resolveAdapterRetryPolicy(\n\tpolicy: AdapterRetryPolicy | undefined,\n\tdefaultIdempotent: boolean,\n): ResolvedAdapterRetryPolicy {\n\tconst idempotent = policy?.idempotent ?? defaultIdempotent;\n\n\tif (!idempotent) {\n\t\treturn NO_RETRY_POLICY;\n\t}\n\n\treturn {\n\t\tidempotent: true,\n\t\tmaxAttempts: Math.max(1, Math.min(policy?.maxAttempts ?? DEFAULT_RETRY_POLICY.maxAttempts, 5)),\n\t\tinitialDelayMs: Math.max(0, policy?.initialDelayMs ?? DEFAULT_RETRY_POLICY.initialDelayMs),\n\t\tbackoffMultiplier: Math.max(\n\t\t\t1,\n\t\t\tpolicy?.backoffMultiplier ?? DEFAULT_RETRY_POLICY.backoffMultiplier,\n\t\t),\n\t\tmaxDelayMs: Math.max(0, policy?.maxDelayMs ?? DEFAULT_RETRY_POLICY.maxDelayMs),\n\t};\n}\n\nexport function getRetryDelayMs(attempt: number, policy: ResolvedAdapterRetryPolicy): number {\n\tconst exponentialDelay =\n\t\tpolicy.initialDelayMs * policy.backoffMultiplier ** Math.max(0, attempt - 1);\n\n\treturn Math.min(exponentialDelay, policy.maxDelayMs);\n}\n\nexport async function executeWithAdapterRetry<T>(options: ExecuteWithRetryOptions<T>): Promise<T> {\n\tconst policy = resolveAdapterRetryPolicy(options.policy, options.defaultIdempotent);\n\tconst sleep =\n\t\toptions.sleep ?? ((delayMs) => new Promise((resolve) => setTimeout(resolve, delayMs)));\n\tlet lastError: string | undefined;\n\n\tfor (let attempt = 1; attempt <= policy.maxAttempts; attempt++) {\n\t\ttry {\n\t\t\tconst result = await options.execute(attempt, policy.maxAttempts);\n\t\t\tif (options.isSuccessful(result)) {\n\t\t\t\tawait options.onAttempt?.({ attempt, result, willRetry: false });\n\t\t\t\treturn result;\n\t\t\t}\n\n\t\t\tlastError = options.getError(result) ?? \"Adapter returned unsuccessful result\";\n\t\t\tconst willRetry = policy.idempotent && attempt < policy.maxAttempts;\n\t\t\tconst nextDelayMs = willRetry ? getRetryDelayMs(attempt, policy) : undefined;\n\t\t\tawait options.onAttempt?.({ attempt, result, error: lastError, willRetry, nextDelayMs });\n\n\t\t\tif (!willRetry) {\n\t\t\t\treturn result;\n\t\t\t}\n\n\t\t\tawait sleep(nextDelayMs ?? 0);\n\t\t} catch (error) {\n\t\t\tlastError = error instanceof Error ? error.message : String(error);\n\t\t\tconst willRetry = policy.idempotent && attempt < policy.maxAttempts;\n\t\t\tconst nextDelayMs = willRetry ? getRetryDelayMs(attempt, policy) : undefined;\n\t\t\tawait options.onAttempt?.({ attempt, error: lastError, willRetry, nextDelayMs });\n\n\t\t\tif (!willRetry) {\n\t\t\t\tthrow error;\n\t\t\t}\n\n\t\t\tawait sleep(nextDelayMs ?? 0);\n\t\t}\n\t}\n\n\tthrow new Error(lastError ?? \"Adapter retry exhausted\");\n}\n"]}

package/dist/displays/index.d.ts

@@ -0,0 +1,34 @@
+interface DisplayDescriptor {
+    title: string;
+    subtitle?: string;
+    stateLabel?: string;
+    primaryFacts?: Array<{
+        label: string;
+        value: string;
+    }>;
+}
+interface CachedDisplayDescriptor extends DisplayDescriptor {
+    _cachedDisplay?: {
+        source: "event_payload" | "projection_snapshot";
+        cursor?: string | null;
+        checksum?: string;
+        generatedAt?: string;
+    };
+}
+type DisplayDatabaseClient = any;
+interface DisplayContext<TDb = DisplayDatabaseClient> {
+    tenantId: string;
+    spaceId: string;
+    db: TDb;
+}
+type DisplayRenderer = (payload: unknown, ctx?: DisplayContext) => DisplayDescriptor | Promise<DisplayDescriptor>;
+interface DisplayRendererRegistration {
+    eventType: string;
+    renderer: DisplayRenderer;
+}
+declare function registerDisplayRenderer(eventType: string, renderer: DisplayRenderer): void;
+declare function resolveDisplayRenderer(eventType: string): DisplayRenderer | undefined;
+declare function denormalizeDisplaySnapshot(payload: unknown): CachedDisplayDescriptor | undefined;
+declare function renderEventDisplay(eventType: string, payload: unknown, ctx?: DisplayContext): Promise<CachedDisplayDescriptor>;
+
+export { type CachedDisplayDescriptor, type DisplayContext, type DisplayDatabaseClient, type DisplayDescriptor, type DisplayRenderer, type DisplayRendererRegistration, denormalizeDisplaySnapshot, registerDisplayRenderer, renderEventDisplay, resolveDisplayRenderer };

package/dist/displays/index.js

@@ -0,0 +1,89 @@
+import assert from '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.ok(renderer, "resolveDisplayRenderer should return the registered renderer");
+  const result = await renderEventDisplay(testEventType, { name: "Alice" });
+  assert.strictEqual(result.title, "Test: Alice");
+  assert.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.deepStrictEqual(snapshotResult, snapshot);
+  const fallback = await renderEventDisplay("__UnknownEvent__", {});
+  assert.strictEqual(fallback.title, "__UnknownEvent__");
+  assert.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.strictEqual(asyncResult.title, "Async: t-1");
+  console.log("\u2705 display engine inline tests passed");
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+  _runInlineTests().catch((err) => {
+    console.error("\u274C display engine inline tests failed", err);
+    process.exit(1);
+  });
+}
+
+export { denormalizeDisplaySnapshot, registerDisplayRenderer, renderEventDisplay, resolveDisplayRenderer };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map