@fabricorg/platform 0.2.0 → 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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabricorg/platform",
-	"version": "0.2.0",
+	"version": "0.2.1",
 	"description": "Generic, vertical-agnostic runtime for ontology-based business applications. Provides actions, modules, events, policies, state machines, adapters, displays, projections, privacy, and evidence contracts. Zero runtime dependencies; portable across any database client and any vertical (lending, insurance, healthcare, legal, etc.).",
 	"keywords": [
 		"fabric",