@substrat-run/contracts 0.66.0 → 0.68.0

package/dist/index.d.ts

@@ -34,4 +34,6 @@ export * from './deploy.js';
 export * from './ci.js';
 export * from './money.js';
 export * from './attachments.js';
+export * from './model.js';
+export * from './operations.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC"}

package/dist/index.js

@@ -34,4 +34,6 @@ export * from './deploy.js';
 export * from './ci.js';
 export * from './money.js';
 export * from './attachments.js';
+export * from './model.js';
+export * from './operations.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC"}

package/dist/model.d.ts

@@ -0,0 +1,231 @@
+/**
+ * The entity registry (#697).
+ *
+ * The manifest describes permissions, events, guards, schedules, attachment
+ * targets, entity relations, searchables and UI contributions. It does not
+ * describe **entities**: `migrations` is a pointer (`journalDir` +
+ * `compatibleFrom`), the tables live in raw SQL the manifest never sees, and
+ * entity *type names* appear only as bare `z.string().min(1)` fragments across
+ * four unrelated, individually optional features.
+ *
+ * Nothing checks those four against each other or against the tables. A typo'd
+ * `parentType` in `entityRelations` parses cleanly and produces an edge that
+ * permission never flows along — the tuple evaluator walks a relation that does
+ * not exist, and a grant that should reach a child silently does not.
+ *
+ * This module gives them something to be checked against.
+ *
+ * ## What it is not
+ *
+ * Migrations do not move in here, and nothing about how tables are created
+ * changes. Whether the model becomes the source that migrations are *derived*
+ * from is #680/#685's question; the registry is a prerequisite either way.
+ */
+import { z } from 'zod';
+/**
+ * One entity: the table it lives in, its field schema, and its place in the
+ * permission graph.
+ */
+export interface EntityDef<Names extends string = string> {
+    /** The physical table. Owned by this module — never another's (rule 4). */
+    readonly table: string;
+    /** The row shape. Field names are what `key`, `searchables` and events check against. */
+    readonly fields: z.ZodObject<z.ZodRawShape>;
+    /**
+     * The parent entity types permission may flow along (design doc §4.2 rule 3).
+     * Checked against the declared entities — a typo is a compile error, where it
+     * used to be a silently dead edge.
+     *
+     * **Plural, and an array even for one.** `entityRelations` is an ALLOWLIST,
+     * not an assertion: the kernel accumulates permitted parents into a *set* per
+     * entity type and `ctx.link` checks membership. `reservation` already hangs
+     * off both `resource` and `member`; `protocol` off both `workorder` and
+     * `employee`. Singular `parent` said "the parent", which is not what the
+     * kernel means and cannot express the real cases.
+     */
+    readonly parents?: readonly Names[];
+    /** Natural key, if any. Must name fields that exist. */
+    readonly key?: readonly string[];
+    /** Fields an erasure must be able to reach (§12). Must name fields that exist. */
+    readonly erasable?: readonly string[];
+}
+/** The field names of one entity, read off its own `fields` schema. */
+export type EntityFields<E> = E extends {
+    fields: infer F;
+} ? F extends z.ZodObject<z.ZodRawShape> ? keyof z.infer<F> & string : never : never;
+/**
+ * Declare a module's entities.
+ *
+ * The constraint is self-referential — `parent` is checked against the map's own
+ * keys, and `key`/`erasable` against each entity's own fields — which is what
+ * makes the checks bite per-entity rather than as a union across all of them.
+ * Written the obvious way (an erased supertype) every one of them compiles clean
+ * and enforces nothing; see `test/model.test.ts`, which exists to prove they
+ * still bite.
+ */
+export declare function defineEntities<T extends {
+    readonly [K in keyof T]: EntityDef<keyof T & string> & {
+        key?: readonly EntityFields<T[K]>[];
+        erasable?: readonly EntityFields<T[K]>[];
+    };
+}>(entities: T): T;
+/** The declared entity names. */
+export type EntityName<T> = keyof T & string;
+/**
+ * The serialisable form — the artifact of record.
+ *
+ * Everything downstream (migrations, the manifest, the route table, an ER
+ * diagram, a diff classifier) reads THIS, never the TypeScript. That is what
+ * keeps the authoring notation swappable: a different authoring layer is a new
+ * emitter writing the same JSON, and nothing downstream notices.
+ *
+ * Field schemas are rendered with `z.toJSONSchema`, the same conversion the
+ * OpenAPI builder already uses — so there is no second schema language anywhere
+ * in the pipeline.
+ */
+export interface EmittedEntity {
+    readonly table: string;
+    readonly fields: Record<string, unknown>;
+    /** The permitted parent types, sorted. One shape, always. */
+    readonly parents?: readonly string[];
+    readonly key?: readonly string[];
+    readonly erasable?: readonly string[];
+}
+export interface EmittedModel {
+    readonly entities: Record<string, EmittedEntity>;
+}
+/**
+ * Render the registry to plain JSON. Deterministic: entities and their fields
+ * are emitted in sorted order, so the checked-in artifact diffs cleanly and a
+ * reordered declaration is not a spurious change.
+ */
+export declare function emitModel<T extends Record<string, EntityDef>>(entities: T): EmittedModel;
+/**
+ * `entityRelations` derived from the `parent` declarations, rather than written
+ * a second time by hand.
+ *
+ * Two descriptions of one fact is how they come to disagree — and the disagreement
+ * here is invisible, because a relation naming an entity that does not exist is a
+ * permission edge that silently never resolves.
+ */
+export declare function entityRelationsOf<T extends Record<string, EntityDef>>(entities: T): {
+    entityType: string;
+    parentType: string;
+}[];
+/**
+ * The entity-referencing half of a manifest, narrowed to declared entities.
+ *
+ * Entity-name positions are written `keyof T & string` inline rather than as
+ * `EntityName<T>`. A type ALIAS is printed unresolved in diagnostics — the error
+ * names the alias and inlines the whole entity map — where the inline form lists
+ * the actual names:
+ *
+ *     Type '"bkie"' is not assignable to type '"bike" | "customer"'.
+ */
+type EntityRefs<T extends Record<string, EntityDef>, M> = {
+    readonly attachmentTargets?: readonly {
+        readonly entityType: keyof T & string;
+        readonly readPermission: string;
+        readonly writePermission?: string;
+    }[];
+    /**
+     * `fields` is checked against the NAMED entity's own fields — the only place
+     * in the manifest today where a field name appears at all, and nothing
+     * checked it.
+     */
+    readonly searchables?: M extends {
+        searchables: infer S;
+    } ? {
+        readonly [I in keyof S]: S[I] extends {
+            entityType: infer N;
+        } ? N extends keyof T & string ? {
+            readonly entityType: N;
+            readonly fields: readonly EntityFields<T[N]>[];
+        } : never : never;
+    } : never;
+    readonly entityViews?: readonly {
+        readonly entityType: keyof T & string;
+        readonly view: string;
+    }[];
+    /**
+     * The engine registries this module composes, so relation edges naming their
+     * entities can be checked.
+     */
+    readonly engines?: readonly Record<string, EntityDef>[];
+    /**
+     * Parent edges involving an entity this module does not own.
+     *
+     * A vertical legitimately declares these: an engine is entity-agnostic, so
+     * only the vertical knows that a work order hangs off a bike, or a protocol
+     * off a work order. **Both sides are checked** against the local entities plus
+     * every entity of every registry in `engines`.
+     *
+     * Local-to-local edges do not belong here — they are DERIVED from the
+     * entities' own `parents`, and declaring one twice is how two descriptions of
+     * a fact come to disagree.
+     *
+     * This replaces the `foreignChildOf` / `foreignChildren` pair, which existed
+     * only because foreign names were uncheckable. They are now, so the split has
+     * nothing left to say.
+     */
+    readonly relations?: readonly {
+        readonly entityType: (keyof T & string) | (M extends {
+            engines: readonly (infer R)[];
+        } ? NamesOf<R> : never);
+        readonly parentType: (keyof T & string) | (M extends {
+            engines: readonly (infer R)[];
+        } ? NamesOf<R> : never);
+    }[];
+};
+/** Every entity name in one registry. */
+type NamesOf<R> = R extends Record<string, EntityDef> ? keyof R & string : never;
+/**
+ * Compose the entity-referencing manifest fragments against the registry.
+ *
+ * `entityRelations` is absent by design: it is DERIVED from the entities'
+ * `parent` declarations (`entityRelationsOf`) rather than written a second time.
+ *
+ * Spread the result into the module's manifest:
+ *
+ * ```ts
+ * export const manifest = moduleManifest.parse({
+ *   id: '@acme/vertical',
+ *   …,
+ *   ...manifestEntities(entities, {
+ *     attachmentTargets: [{ entityType: 'contract', readPermission: 'x:read' }],
+ *     searchables: [{ entityType: 'customer', fields: ['name'] }],
+ *   }),
+ * });
+ * ```
+ *
+ * A typo in any `entityType` is now a compile error naming the declared
+ * entities, and a `searchables` field that the entity does not have is too.
+ */
+export declare function manifestEntities<const T extends Record<string, EntityDef>, const M extends EntityRefs<T, M>>(entities: T, refs: M): {
+    attachmentTargets: NonNullable<M['attachmentTargets']> | [];
+    searchables: M['searchables'];
+    entityRelations: {
+        entityType: string;
+        parentType: string;
+    }[];
+    ui: {
+        entityViews: M['entityViews'];
+    };
+};
+/**
+ * The row type of a declared entity — what `ctx.sql.query` returns for it.
+ *
+ * `ctx.sql.query` leaves `T` to the vertical, so every handler writes its own
+ * row interface and the schema ends up described three times: the DDL, the
+ * registry, and a hand-written `interface CustomerRow`. This collapses the
+ * third into the second.
+ *
+ * ```ts
+ * export type CustomerRow = EntityRow<typeof calloutEntities, 'customer'>;
+ * ```
+ */
+export type EntityRow<T extends Record<string, EntityDef>, K extends keyof T> = T[K] extends {
+    fields: infer F;
+} ? F extends z.ZodObject<z.ZodRawShape> ? z.infer<F> : never : never;
+export {};
+//# sourceMappingURL=model.d.ts.map

package/dist/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,MAAM,WAAW,SAAS,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM;IACtD,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yFAAyF;IACzF,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IAC5C;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,KAAK,EAAE,CAAC;IACpC,wDAAwD;IACxD,QAAQ,CAAC,GAAG,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,uEAAuE;AACvE,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GACvD,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,GAClC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,GACzB,KAAK,GACP,KAAK,CAAC;AAEV;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,CAAC,SAAS;IACR,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG;QACrD,GAAG,CAAC,EAAE,SAAS,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACpC,QAAQ,CAAC,EAAE,SAAS,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;KAC1C;CACF,EACD,QAAQ,EAAE,CAAC,GAAG,CAAC,CAEhB;AAED,iCAAiC;AACjC,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,CAAC;AAE7C;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,GAAG,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CAClD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,YAAY,CAkBxF;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EACnE,QAAQ,EAAE,CAAC,GACV;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,EAAE,CAQ9C;AAMD;;;;;;;;;GASG;AACH,KAAK,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,CAAC,IAAI;IACxD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS;QACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC;QACtC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;QAChC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;KACnC,EAAE,CAAC;IACJ;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,SAAS;QAAE,WAAW,EAAE,MAAM,CAAC,CAAA;KAAE,GACrD;QACE,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS;YAAE,UAAU,EAAE,MAAM,CAAC,CAAA;SAAE,GACzD,CAAC,SAAS,MAAM,CAAC,GAAG,MAAM,GACxB;YAAE,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;YAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;SAAE,GAC1E,KAAK,GACP,KAAK;KACV,GACD,KAAK,CAAC;IACV,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACnG;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,CAAC;IACxD;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS;QAI5B,QAAQ,CAAC,UAAU,EAAE,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,SAAS;YAAE,OAAO,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,CAAA;SAAE,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC;QAC7G,QAAQ,CAAC,UAAU,EAAE,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,SAAS;YAAE,OAAO,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,CAAA;SAAE,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC;KAC9G,EAAE,CAAC;CACL,CAAC;AAEF,yCAAyC;AACzC,KAAK,OAAO,CAAC,CAAC,IAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,MAAM,CAAC,GAAG,MAAM,GAAG,KAAK,CAAC;AAGjF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EACzC,KAAK,CAAC,CAAC,SAAS,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,EAEhC,QAAQ,EAAE,CAAC,EACX,IAAI,EAAE,CAAC,GACN;IACD,iBAAiB,EAAE,WAAW,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,GAAG,EAAE,CAAC;IAC5D,WAAW,EAAE,CAAC,CAAC,aAAa,CAAC,CAAC;IAC9B,eAAe,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC9D,EAAE,EAAE;QAAE,WAAW,EAAE,CAAC,CAAC,aAAa,CAAC,CAAA;KAAE,CAAC;CACvC,CAUA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;IAC3F,MAAM,EAAE,MAAM,CAAC,CAAC;CACjB,GACG,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,GAClC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GACV,KAAK,GACP,KAAK,CAAC"}

package/dist/model.js

@@ -0,0 +1,111 @@
+/**
+ * The entity registry (#697).
+ *
+ * The manifest describes permissions, events, guards, schedules, attachment
+ * targets, entity relations, searchables and UI contributions. It does not
+ * describe **entities**: `migrations` is a pointer (`journalDir` +
+ * `compatibleFrom`), the tables live in raw SQL the manifest never sees, and
+ * entity *type names* appear only as bare `z.string().min(1)` fragments across
+ * four unrelated, individually optional features.
+ *
+ * Nothing checks those four against each other or against the tables. A typo'd
+ * `parentType` in `entityRelations` parses cleanly and produces an edge that
+ * permission never flows along — the tuple evaluator walks a relation that does
+ * not exist, and a grant that should reach a child silently does not.
+ *
+ * This module gives them something to be checked against.
+ *
+ * ## What it is not
+ *
+ * Migrations do not move in here, and nothing about how tables are created
+ * changes. Whether the model becomes the source that migrations are *derived*
+ * from is #680/#685's question; the registry is a prerequisite either way.
+ */
+import { z } from 'zod';
+/**
+ * Declare a module's entities.
+ *
+ * The constraint is self-referential — `parent` is checked against the map's own
+ * keys, and `key`/`erasable` against each entity's own fields — which is what
+ * makes the checks bite per-entity rather than as a union across all of them.
+ * Written the obvious way (an erased supertype) every one of them compiles clean
+ * and enforces nothing; see `test/model.test.ts`, which exists to prove they
+ * still bite.
+ */
+export function defineEntities(entities) {
+    return entities;
+}
+/**
+ * Render the registry to plain JSON. Deterministic: entities and their fields
+ * are emitted in sorted order, so the checked-in artifact diffs cleanly and a
+ * reordered declaration is not a spurious change.
+ */
+export function emitModel(entities) {
+    const out = {};
+    for (const name of Object.keys(entities).sort()) {
+        const e = entities[name];
+        if (!e)
+            continue;
+        const { $schema: _drop, ...fields } = z.toJSONSchema(e.fields, { io: 'output', target: 'draft-2020-12' });
+        out[name] = {
+            table: e.table,
+            fields,
+            ...(e.parents?.length ? { parents: [...e.parents].sort() } : {}),
+            ...(e.key ? { key: [...e.key].sort() } : {}),
+            ...(e.erasable ? { erasable: [...e.erasable].sort() } : {}),
+        };
+    }
+    return { entities: out };
+}
+/**
+ * `entityRelations` derived from the `parent` declarations, rather than written
+ * a second time by hand.
+ *
+ * Two descriptions of one fact is how they come to disagree — and the disagreement
+ * here is invisible, because a relation naming an entity that does not exist is a
+ * permission edge that silently never resolves.
+ */
+export function entityRelationsOf(entities) {
+    return Object.keys(entities)
+        .sort()
+        .flatMap((name) => {
+        const parents = entities[name]?.parents;
+        if (!parents?.length)
+            return [];
+        return [...parents].sort().map((parentType) => ({ entityType: name, parentType }));
+    });
+}
+/**
+ * Compose the entity-referencing manifest fragments against the registry.
+ *
+ * `entityRelations` is absent by design: it is DERIVED from the entities'
+ * `parent` declarations (`entityRelationsOf`) rather than written a second time.
+ *
+ * Spread the result into the module's manifest:
+ *
+ * ```ts
+ * export const manifest = moduleManifest.parse({
+ *   id: '@acme/vertical',
+ *   …,
+ *   ...manifestEntities(entities, {
+ *     attachmentTargets: [{ entityType: 'contract', readPermission: 'x:read' }],
+ *     searchables: [{ entityType: 'customer', fields: ['name'] }],
+ *   }),
+ * });
+ * ```
+ *
+ * A typo in any `entityType` is now a compile error naming the declared
+ * entities, and a `searchables` field that the entity does not have is too.
+ */
+export function manifestEntities(entities, refs) {
+    return {
+        attachmentTargets: (refs.attachmentTargets ?? []),
+        searchables: refs.searchables,
+        // Derived edges first, then the ones this module cannot check.
+        // Local edges are derived from the entities' own `parents`; edges involving
+        // a composed engine's entity are declared, and both sides are checked.
+        entityRelations: [...entityRelationsOf(entities), ...(refs.relations ?? [])],
+        ui: { entityViews: refs.entityViews },
+    };
+}
+//# sourceMappingURL=model.js.map

package/dist/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAqCxB;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAO5B,QAAW;IACX,OAAO,QAAQ,CAAC;AAClB,CAAC;AA8BD;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAsC,QAAW;IACxE,MAAM,GAAG,GAAkC,EAAE,CAAC;IAC9C,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QAChD,MAAM,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QACzB,IAAI,CAAC,CAAC;YAAE,SAAS;QACjB,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,MAAM,EAAE,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,eAAe,EAAE,CAGvG,CAAC;QACF,GAAG,CAAC,IAAI,CAAC,GAAG;YACV,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,MAAM;YACN,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAChE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5C,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC5D,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC;AAC3B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAW;IAEX,OAAO,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC;SACzB,IAAI,EAAE;SACN,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;QAChB,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;QACxC,IAAI,CAAC,OAAO,EAAE,MAAM;YAAE,OAAO,EAAE,CAAC;QAChC,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC;IACrF,CAAC,CAAC,CAAC;AACP,CAAC;AAuED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,gBAAgB,CAI9B,QAAW,EACX,IAAO;IAOP,OAAO;QACL,iBAAiB,EAAE,CAAC,IAAI,CAAC,iBAAiB,IAAI,EAAE,CAA6C;QAC7F,WAAW,EAAE,IAAI,CAAC,WAA+B;QACjD,+DAA+D;QAC/D,4EAA4E;QAC5E,uEAAuE;QACvE,eAAe,EAAE,CAAC,GAAG,iBAAiB,CAAC,QAAQ,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;QAC5E,EAAE,EAAE,EAAE,WAAW,EAAE,IAAI,CAAC,WAA+B,EAAE;KAC1D,CAAC;AACJ,CAAC"}

package/dist/operations.d.ts

@@ -0,0 +1,223 @@
+/**
+ * The operation surface of the model (#707).
+ *
+ * #697 declared the entities. This declares what can be *done* to them, and
+ * checks the joins that today are unchecked strings: which permission an
+ * operation requires, which output field an event takes its subject from,
+ * whether a payload carries something an erasure must be able to reach.
+ *
+ * ## A composer, not a second `defineModel`
+ *
+ * `defineOperations` sits beside `defineEntities` rather than swallowing it.
+ * Each half stays independently adoptable — which is what let the entity half
+ * ship and be taken up by two verticals before this existed. A vertical adopts
+ * operations when it is ready, not as the price of adopting entities.
+ *
+ * ## `input`, and the transcription that is not here
+ *
+ * `input` is the Zod object the handler already parses — the same object, not a
+ * description of it. That is the whole reason the model is TypeScript (#680): a
+ * schema language would need the shape written twice, and transcription is what
+ * produced 40 wrong argument names in the one app where this was measured.
+ */
+import { z } from 'zod';
+import type { EntityDef } from './model.js';
+/** `{var}` names in a literal path. */
+type PathParams<S extends string> = S extends `${string}{${infer P}}${infer Rest}` ? P | PathParams<Rest> : never;
+type InputKeys<O> = O extends {
+    input: infer I;
+} ? (I extends z.ZodType ? keyof z.infer<I> & string : never) : never;
+type OutputKeys<O> = O extends {
+    output: infer R;
+} ? (R extends z.ZodType ? keyof z.infer<R> & string : never) : never;
+/** Every `{var}` must name an input field, or the path type collapses. */
+type CheckedPath<O> = O extends {
+    http: {
+        path: infer P;
+    };
+} ? P extends string ? [PathParams<P>] extends [InputKeys<O>] ? P : never : never : string;
+/**
+ * The erasable fields OF THE ENTITY THIS EVENT IS ABOUT.
+ *
+ * Resolving through `emits.entity` rather than matching field names across all
+ * entities is what makes the §12 check exact. A `contactPerson.email` marked
+ * erasable must not stop an event about an `office` carrying its own `email` —
+ * a rule that refuses correct code trains people to route around it, which is
+ * how a PII rule stops being obeyed.
+ */
+type ErasableOf<Entities, O> = O extends {
+    emits: {
+        entity: infer N;
+    };
+} ? N extends keyof Entities ? Entities[N] extends {
+    erasable: readonly (infer F)[];
+} ? F & string : never : never : never;
+/**
+ * The platform's own event invariant, moved from runtime to compile time.
+ * `contracts/events.ts` enforces it with a `superRefine`: *"subjectId is
+ * required when piiClass is 'direct' — crypto-shredding must be able to key the
+ * erasure"*. Classification is mandatory here for the same reason it is there:
+ * an unclassified event type cannot be declared.
+ */
+type PiiShape<O, OutKeys extends string> = O extends {
+    emits: {
+        piiClass: 'none';
+    };
+} ? {
+    readonly piiClass: 'none';
+    readonly subjectId?: never;
+} : {
+    readonly piiClass: 'pseudonymous' | 'direct';
+    readonly subjectId: OutKeys;
+};
+/**
+ * An operation carries a leading `permission` OR `narrows` with a reason, never
+ * both and never neither (rule 5 / CRM-EFF's check 14). `narrows` is the
+ * per-row proof walk: a salesperson listing their own customers must get their
+ * list, not a denial.
+ */
+type OpAuthority<O, PermKey extends string> = O extends {
+    narrows: unknown;
+} ? {
+    readonly narrows: {
+        readonly reason: string;
+    };
+    readonly permission?: never;
+} : {
+    readonly permission: PermKey;
+    readonly narrows?: never;
+};
+/**
+ * The per-operation constraint, self-referential in `O`.
+ *
+ * Each operation is checked against ITS OWN declared input and output rather
+ * than an erased supertype. Written the obvious way every check below compiles
+ * clean and enforces nothing — see `test/operations.test.ts`, which exists to
+ * prove they still bite.
+ */
+type OperationShape<O, Entities, PermKey extends string> = {
+    /** One line, imperative — what invoking this does. Feeds the API document. */
+    readonly summary: string;
+    /**
+     * The request body — the SAME Zod object the handler parses.
+     *
+     * **Omitted means no body at all**, and the handler then takes `undefined`.
+     * Found by the first adopter: three of Callout's six operations take no input,
+     * and a required `z.object({})` cannot say so — a handler accepting only
+     * `undefined` is not assignable to one accepting `{}`.
+     *
+     * This mirrors `ApiOperationDoc.input` ("Omit = no body") rather than
+     * inventing a second vocabulary for the same fact.
+     */
+    readonly input?: z.ZodObject<z.ZodRawShape>;
+    /** True when the handler accepts a body but also accepts none (filter-style reads). */
+    readonly inputOptional?: boolean;
+    /**
+     * Declared, not inferred (#695 Ask 2). Inference documents accidents: one
+     * inferred return carried `contacts?: undefined`, an artefact of an early
+     * return, which generation would have cemented into the published API.
+     *
+     * Declare a return where a caller branches on it — a UI lane is a caller that
+     * branches, which is why #682/#683 depend on this.
+     */
+    readonly output: z.ZodType;
+    readonly http?: {
+        readonly method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+        readonly path: CheckedPath<O>;
+    };
+    readonly emits?: {
+        /** The entity the event is about — a declared entity. */
+        readonly entity: keyof Entities & string;
+        /**
+         * Which OUTPUT field carries that entity's id.
+         *
+         * The #695 defect: 18 operations emitted `entityId: String(result.id)` on
+         * objects that answer with `contractId` / `runId` / `instanceId`. For a
+         * mutation writing a child the event is about the PARENT, so the two differ
+         * and nothing downstream would ever have flagged it.
+         */
+        readonly entityIdFrom: OutputKeys<O>;
+        readonly type: string;
+        readonly schemaVersion: number;
+        /**
+         * Fat payload, drawn from the output — minus anything the entity marks
+         * `erasable`. Immutable events are the one place in a scope an erasure
+         * cannot reach.
+         */
+        readonly payload?: readonly Exclude<OutputKeys<O>, ErasableOf<Entities, O>>[];
+    } & PiiShape<O, OutputKeys<O>>;
+    /**
+     * Per-field permission on the projection: omission, not denial. The caller
+     * still gets the row, without the fields they may not see.
+     */
+    readonly gates?: {
+        readonly [F in OutputKeys<O>]?: PermKey;
+    };
+} & OpAuthority<O, PermKey>;
+/**
+ * Declare a module's operations against its entities and permission keys.
+ *
+ * Curried so the entities and permissions are given explicitly while each
+ * operation still infers its own input and output — a callback parameter cannot
+ * be contextually typed by a generic being inferred from the object containing
+ * it.
+ *
+ * ```ts
+ * export const ops = defineOperations(calloutEntities, PERMISSIONS)({
+ *   'customer/create': {
+ *     summary: 'Register a customer',
+ *     permission: 'customer:manage',
+ *     input: z.object({ name: z.string() }),
+ *     output: z.object({ id: z.string(), number: z.string() }),
+ *     http: { method: 'POST', path: '/customers' },
+ *     emits: {
+ *       entity: 'customer', entityIdFrom: 'id',
+ *       type: 'callout.customer-created', schemaVersion: 1, piiClass: 'none',
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export declare function defineOperations<const Entities extends Record<string, EntityDef>, const Perms extends readonly string[]>(_entities: Entities, _permissions: Perms): <const Ops extends { readonly [K in keyof Ops]: OperationShape<Ops[K], Entities, Perms[number]>; }>(operations: Ops) => Ops;
+/**
+ * The permission keys an operation set actually requires, for the manifest.
+ *
+ * Read structurally rather than through a `{ permission?: string }` parameter:
+ * a `narrows` operation has neither `permission` nor `emits`, and TypeScript's
+ * weak-type rule rejects an object sharing no properties with the parameter.
+ */
+export declare function permissionsUsedBy(operations: Readonly<Record<string, object>>): string[];
+/** The event types an operation set emits, for `manifest.events.emits`. */
+export declare function eventsEmittedBy(operations: Readonly<Record<string, object>>): {
+    type: string;
+    schemaVersion: number;
+}[];
+/**
+ * The handler map a declared operation set requires — CRM-EFF's `satisfies Impl`
+ * seam, which is what makes the declaration BINDING rather than decorative.
+ *
+ * ```ts
+ * export const operations = { … } satisfies OperationImpl<typeof calloutOps, OperationContext>;
+ * ```
+ *
+ * Four things become compile errors at the exact method: a handler whose input
+ * disagrees with the declared `input`, one whose return disagrees with the
+ * declared `output`, an operation declared and not implemented, and one
+ * implemented and not declared.
+ *
+ * `Ctx` is a parameter rather than `OperationContext` because contracts is below
+ * the kernel and must not import it. The vertical supplies it.
+ */
+export type OperationImpl<Ops, Ctx> = {
+    [K in keyof Ops]: Ops[K] extends {
+        output: infer O;
+    } ? O extends z.ZodType ? (ctx: Ctx, input: ImplInput<Ops[K]>) => z.infer<O> | Promise<z.infer<O>> : never : never;
+};
+/** No declared `input` means the handler takes `undefined`. */
+type ImplInput<O> = O extends {
+    input: infer I;
+} ? I extends z.ZodType ? O extends {
+    inputOptional: true;
+} ? z.infer<I> | undefined : z.infer<I> : undefined : undefined;
+export {};
+//# sourceMappingURL=operations.d.ts.map

package/dist/operations.d.ts.map

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

package/dist/operations.js

@@ -0,0 +1,81 @@
+/**
+ * The operation surface of the model (#707).
+ *
+ * #697 declared the entities. This declares what can be *done* to them, and
+ * checks the joins that today are unchecked strings: which permission an
+ * operation requires, which output field an event takes its subject from,
+ * whether a payload carries something an erasure must be able to reach.
+ *
+ * ## A composer, not a second `defineModel`
+ *
+ * `defineOperations` sits beside `defineEntities` rather than swallowing it.
+ * Each half stays independently adoptable — which is what let the entity half
+ * ship and be taken up by two verticals before this existed. A vertical adopts
+ * operations when it is ready, not as the price of adopting entities.
+ *
+ * ## `input`, and the transcription that is not here
+ *
+ * `input` is the Zod object the handler already parses — the same object, not a
+ * description of it. That is the whole reason the model is TypeScript (#680): a
+ * schema language would need the shape written twice, and transcription is what
+ * produced 40 wrong argument names in the one app where this was measured.
+ */
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// The composer.
+// ---------------------------------------------------------------------------
+/**
+ * Declare a module's operations against its entities and permission keys.
+ *
+ * Curried so the entities and permissions are given explicitly while each
+ * operation still infers its own input and output — a callback parameter cannot
+ * be contextually typed by a generic being inferred from the object containing
+ * it.
+ *
+ * ```ts
+ * export const ops = defineOperations(calloutEntities, PERMISSIONS)({
+ *   'customer/create': {
+ *     summary: 'Register a customer',
+ *     permission: 'customer:manage',
+ *     input: z.object({ name: z.string() }),
+ *     output: z.object({ id: z.string(), number: z.string() }),
+ *     http: { method: 'POST', path: '/customers' },
+ *     emits: {
+ *       entity: 'customer', entityIdFrom: 'id',
+ *       type: 'callout.customer-created', schemaVersion: 1, piiClass: 'none',
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export function defineOperations(_entities, _permissions) {
+    return (operations) => operations;
+}
+/**
+ * The permission keys an operation set actually requires, for the manifest.
+ *
+ * Read structurally rather than through a `{ permission?: string }` parameter:
+ * a `narrows` operation has neither `permission` nor `emits`, and TypeScript's
+ * weak-type rule rejects an object sharing no properties with the parameter.
+ */
+export function permissionsUsedBy(operations) {
+    const keys = Object.values(operations).flatMap((op) => {
+        const permission = op.permission;
+        return typeof permission === 'string' ? [permission] : [];
+    });
+    return [...new Set(keys)].sort();
+}
+/** The event types an operation set emits, for `manifest.events.emits`. */
+export function eventsEmittedBy(operations) {
+    const seen = new Map();
+    for (const op of Object.values(operations)) {
+        const emits = op.emits;
+        if (typeof emits?.type === 'string' && typeof emits.schemaVersion === 'number') {
+            seen.set(emits.type, emits.schemaVersion);
+        }
+    }
+    return [...seen.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([type, schemaVersion]) => ({ type, schemaVersion }));
+}
+//# sourceMappingURL=operations.js.map

package/dist/operations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.js","sourceRoot":"","sources":["../src/operations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAiIxB,8EAA8E;AAC9E,gBAAgB;AAChB,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,gBAAgB,CAG9B,SAAmB,EAAE,YAAmB;IACxC,OAAO,CAKL,UAAe,EACV,EAAE,CAAC,UAAU,CAAC;AACvB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAA4C;IAC5E,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE;QACpD,MAAM,UAAU,GAAI,EAA+B,CAAC,UAAU,CAAC;QAC/D,OAAO,OAAO,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5D,CAAC,CAAC,CAAC;IACH,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AACnC,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,eAAe,CAC7B,UAA4C;IAE5C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAC;IACvC,KAAK,MAAM,EAAE,IAAI,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;QAC3C,MAAM,KAAK,GAAI,EAA8D,CAAC,KAAK,CAAC;QACpF,IAAI,OAAO,KAAK,EAAE,IAAI,KAAK,QAAQ,IAAI,OAAO,KAAK,CAAC,aAAa,KAAK,QAAQ,EAAE,CAAC;YAC/E,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;SACvB,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;SACtC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,aAAa,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC;AAC/D,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@substrat-run/contracts",
-  "version": "0.66.0",
+  "version": "0.68.0",
   "description": "Substrat kernel contract schemas — Zod is the source of truth (master plan D-22); OAS/JSON Schema are emitted artifacts",
   "license": "Apache-2.0",
   "repository": {
@@ -25,13 +25,15 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "typescript": "^7.0.0"
+    "typescript": "^7.0.0",
+    "vitest": "^3.0.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "test": "vitest run"
   }
 }