@zixcel/projection-contracts 0.10.2 → 0.10.4

package/README.md

@@ -7,7 +7,7 @@ selected owner-visible source revisions. Deterministic lineage and publication
 fences keep presentation tied to the accepted source without owning its meaning.
 
 ```sh
-npm install @zixcel/projection-contracts@0.10.2
+npm install @zixcel/projection-contracts
 ```
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zixcel/projection-contracts",
-  "version": "0.10.2",
+  "version": "0.10.4",
   "description": "Renderer-independent bounded projection, lineage and Scene contracts",
   "type": "module",
   "license": "Apache-2.0",
@@ -33,16 +33,12 @@
     }
   },
   "dependencies": {
-    "ohash": "2.0.11",
+    "ohash": "2.0.12",
     "@zixcel/interaction": "0.10.1"
   },
-  "scripts": {
-    "test": "node --test test/*.test.mjs",
-    "typecheck": "tsc --noEmit --strict --module NodeNext --moduleResolution NodeNext --target ES2022 test/public-types.mts"
-  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/zixcel/projection-runtime.git",
+    "url": "git+https://github.com/zixcel/data-presentation.git",
     "directory": "packages/projection-contracts"
   },
   "publishConfig": {
@@ -51,8 +47,18 @@
   },
   "types": "./src/index.d.mts",
   "devDependencies": {
-    "typescript": "5.9.3",
+    "typescript": "7.0.2",
     "@types/node": "24.12.0"
   },
-  "packageManager": "pnpm@10.29.3"
-}
+  "keywords": [
+    "typed-contracts",
+    "schema-validation",
+    "data-presentation",
+    "javascript"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mts",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit && tsc --noEmit --strict --module NodeNext --moduleResolution NodeNext --target ES2022 test/public-types.mts",
+    "build": "tsc -p tsconfig.build.json && node ../../scripts/build-projection-contracts.mts"
+  }
+}

package/src/canonical.d.mts

@@ -0,0 +1 @@
+export declare function canonical(value: unknown, maximum?: number): string;

package/src/client.d.mts

@@ -1,12 +1,3 @@
-/** Browser-safe exact projection wire types; owner meaning remains external. */
+export { validateSnapshot } from './producer.mjs';
+export { canonical, copy, frozen, shape, text, roles, ProjectionError, LIMITS } from './contract.mjs';
 export type * from './types/snapshot.mjs';
-import type { DataProjection, SceneProjection } from './types/snapshot.mjs';
-export function validateSnapshot(value: unknown): DataProjection | SceneProjection;
-export function canonical(value: unknown, maximum?: number): string;
-export function copy<T>(value: T): T;
-export function frozen<T>(value: T): Readonly<T>;
-export function shape(value: unknown, required: string[], optional?: string[]): void;
-export function text(value: unknown, maximum?: number): string;
-export const roles: readonly import('./types/snapshot.mjs').RegionRole[];
-export const LIMITS: Readonly<import('./types/input.mjs').ProjectionLimits>;
-export class ProjectionError extends Error { readonly code: string; constructor(code: string) }

package/src/client.mjs

@@ -1,3 +1,16 @@
-// Shared validation, not a browser-specific schema or a canonical source reader.
-export {validateSnapshot} from './producer.mjs'
-export {canonical,copy,frozen,shape,text,roles,ProjectionError,LIMITS} from './contract.mjs'
+// Generated from canonical TypeScript; do not edit.
+
+// implementation/client.mts
+import { validateSnapshot } from "./producer.mjs";
+import { canonical, copy, frozen, shape, text, roles, ProjectionError, LIMITS } from "./contract.mjs";
+export {
+  LIMITS,
+  ProjectionError,
+  canonical,
+  copy,
+  frozen,
+  roles,
+  shape,
+  text,
+  validateSnapshot
+};

package/src/contract.d.mts

@@ -0,0 +1,28 @@
+import { canonical } from './canonical.mjs';
+import type { Json, RegionRole, SourceRef } from './types/snapshot.mjs';
+import type { ProjectionLimits, ProjectionRequest } from './types/input.mjs';
+export { canonical };
+export declare class ProjectionError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+export declare function fail(code: string): never;
+export declare const LIMITS: Readonly<ProjectionLimits>;
+export declare function shape(v: unknown, required: readonly string[], optional?: readonly string[]): asserts v is Record<string, unknown>;
+export declare function record(v: unknown): Record<string, unknown>;
+export declare function text(v: unknown, max?: number): string;
+export declare function list(v: unknown, max: number): unknown[];
+export declare const refs: (v: unknown, max?: number) => string[];
+export declare function choice<const T extends readonly string[]>(value: unknown, values: T): T[number];
+export declare function limits(input?: unknown): Readonly<ProjectionLimits>;
+export declare const digest: (value: unknown) => string;
+export declare function frozen<T>(value: T): Readonly<T>;
+export declare const copy: <T>(v: T) => T;
+export declare const json: (v: unknown) => Json;
+export declare function sourceRef(v: unknown): SourceRef;
+export declare const sourceKey: (v: unknown) => string;
+export declare function unique<T>(values: T[], key?: (value: T) => unknown): T[];
+export declare const roles: readonly RegionRole[];
+export declare function request(v: unknown): ProjectionRequest & {
+    readonly limits: Readonly<ProjectionLimits>;
+};

package/src/contract.mjs

@@ -1,59 +1,181 @@
-import {sha256} from '#hash'
-const encoder=new TextEncoder()
-const byteLength=value=>encoder.encode(value).length
-export class ProjectionError extends Error {constructor(code){super(code);this.code=code}}
-export const fail=code=>{throw new ProjectionError(code)}
-export const LIMITS=Object.freeze({sources:8,items:256,relations:512,provenance:512,unresolved:64,regions:16,actions:64,snapshotBytes:524288})
-export function limits(input={}){
-  shape(input,[],Object.keys(LIMITS));const result={...LIMITS,...input}
-  for(const key in result)if(!Number.isSafeInteger(result[key])||result[key]<1||result[key]>LIMITS[key])fail('ProjectionLimitExceeded')
-  return Object.freeze(result)
-}
-export function shape(v,required,optional=[]){
-  if(!v||Object.getPrototypeOf(v)!==Object.prototype||required.some(k=>!Object.hasOwn(v,k)))fail('InvalidProjection')
-  for(const k of Object.getOwnPropertyNames(v)){
-    const d=Object.getOwnPropertyDescriptor(v,k)
-    if(!d.enumerable||d.get||d.set||(!required.includes(k)&&!optional.includes(k)))fail('InvalidProjection')
+// Generated from canonical TypeScript; do not edit.
+
+// implementation/contract.mts
+import { sha256 } from "#hash";
+
+// implementation/canonical.mts
+var encoder = new TextEncoder();
+var byteLength = (value) => encoder.encode(value).length;
+function canonical(value, maximum = 2097152) {
+  if (!Number.isSafeInteger(maximum) || maximum < 1 || maximum > 2097152) fail("ProjectionLimitExceeded");
+  let bytes = 0, nodes = 0;
+  const add = (n) => {
+    bytes += n;
+    if (bytes > maximum) fail("ProjectionLimitExceeded");
+  };
+  function walk(v, depth) {
+    if (++nodes > 32768 || depth > 16) fail("ProjectionLimitExceeded");
+    if (v === null || typeof v === "boolean") {
+      add(5);
+      return v;
+    }
+    if (typeof v === "number") {
+      if (!Number.isSafeInteger(v)) fail("InvalidProjection");
+      add(24);
+      return v;
+    }
+    if (typeof v === "string") {
+      if (v.length > maximum) fail("ProjectionLimitExceeded");
+      if (!v.isWellFormed()) fail("InvalidProjection");
+      add(byteLength(v) + 2);
+      return v;
+    }
+    if (Array.isArray(v)) {
+      const count = v.length;
+      add(count + 2);
+      if (count > 4096) fail("ProjectionLimitExceeded");
+      if (Object.getPrototypeOf(v) !== Array.prototype || Object.getOwnPropertySymbols(v).length) fail("InvalidProjection");
+      if (Object.getOwnPropertyNames(v).length !== count + 1) fail("InvalidProjection");
+      const out2 = [];
+      for (let i = 0; i < count; i++) {
+        const d = Object.getOwnPropertyDescriptor(v, String(i));
+        if (!d || !d.enumerable || !("value" in d)) fail("InvalidProjection");
+        out2.push(walk(d.value, depth + 1));
+      }
+      return out2;
+    }
+    if (!v || typeof v !== "object" || Object.getPrototypeOf(v) !== Object.prototype) fail("InvalidProjection");
+    const keys = Object.getOwnPropertyNames(v);
+    if (keys.length > 1024 || Object.getOwnPropertySymbols(v).length) fail("ProjectionLimitExceeded");
+    const out = {};
+    add(keys.length + 2);
+    for (const k of keys.sort()) {
+      const d = Object.getOwnPropertyDescriptor(v, k);
+      if (!d || !d.enumerable || !("value" in d) || ["__proto__", "constructor", "prototype", "toJSON"].includes(k)) fail("InvalidProjection");
+      text(k, 512);
+      add(byteLength(k) + 3);
+      out[k] = walk(d.value, depth + 1);
+    }
+    return out;
+  }
+  const encoded = JSON.stringify(walk(value, 0));
+  if (byteLength(encoded) > maximum) fail("ProjectionLimitExceeded");
+  return encoded;
+}
+
+// implementation/contract.mts
+var encoder2 = new TextEncoder();
+var ProjectionError = class extends Error {
+  code;
+  constructor(code) {
+    super(code);
+    this.code = code;
+  }
+};
+function fail(code) {
+  throw new ProjectionError(code);
+}
+var LIMITS = Object.freeze({ sources: 8, items: 256, relations: 512, provenance: 512, unresolved: 64, regions: 16, actions: 64, snapshotBytes: 524288 });
+function shape(v, required, optional = []) {
+  if (!v || typeof v !== "object" || Object.getPrototypeOf(v) !== Object.prototype || required.some((k) => !Object.hasOwn(v, k))) fail("InvalidProjection");
+  for (const k of Object.getOwnPropertyNames(v)) {
+    const d = Object.getOwnPropertyDescriptor(v, k);
+    if (!d || !d.enumerable || !("value" in d) || !required.includes(k) && !optional.includes(k)) fail("InvalidProjection");
+  }
+  if (Object.getOwnPropertySymbols(v).length) fail("InvalidProjection");
+}
+function record(v) {
+  if (!v || typeof v !== "object" || Object.getPrototypeOf(v) !== Object.prototype) fail("InvalidProjection");
+  return v;
+}
+function text(v, max = 512) {
+  if (typeof v !== "string" || !v.length || v.length > max || encoder2.encode(v).length > max || !v.isWellFormed() || /[\x00-\x1f\x7f]/u.test(v)) fail("InvalidProjection");
+  return v;
+}
+function list(v, max) {
+  if (!Array.isArray(v) || v.length > max) fail("ProjectionLimitExceeded");
+  return v;
+}
+var refs = (v, max = 32) => list(v, max).map((x) => text(x));
+function choice(value, values) {
+  if (typeof value !== "string" || !values.includes(value)) fail("InvalidProjection");
+  return value;
+}
+function limits(input = {}) {
+  shape(input, [], Object.keys(LIMITS));
+  const result = { ...LIMITS };
+  for (const key of Object.keys(LIMITS)) {
+    const value = Object.hasOwn(input, key) ? input[key] : LIMITS[key];
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1 || value > LIMITS[key]) fail("ProjectionLimitExceeded");
+    result[key] = value;
   }
-  if(Object.getOwnPropertySymbols(v).length)fail('InvalidProjection')
-}
-export function text(v,max=512){if(typeof v!=='string'||!v.length||v.length>max||byteLength(v)>max||!v.isWellFormed()||/[\x00-\x1f\x7f]/u.test(v))fail('InvalidProjection');return v}
-export function list(v,max){if(!Array.isArray(v)||v.length>max)fail('ProjectionLimitExceeded');return v}
-export function refs(v,max=32){return list(v,max).map(x=>text(x))}
-// Bounded plain JSON only. No callbacks, toJSON, prototypes or renderer execution.
-export function canonical(value,maximum=2097152){
-  let bytes=0,nodes=0
-  const add=n=>{bytes+=n;if(bytes>maximum)fail('ProjectionLimitExceeded')}
-  function walk(v,depth){
-    if(++nodes>32768||depth>16)fail('ProjectionLimitExceeded')
-    if(v===null||typeof v==='boolean'){add(5);return v}
-    if(typeof v==='number'){if(!Number.isSafeInteger(v))fail('InvalidProjection');add(24);return v}
-    if(typeof v==='string'){if(v.length>maximum)fail('ProjectionLimitExceeded');if(!v.isWellFormed())fail('InvalidProjection');add(byteLength(v)+2);return v}
-    if(Array.isArray(v)){add(v.length+2);if(v.length>4096)fail('ProjectionLimitExceeded');return v.map(x=>walk(x,depth+1))}
-    if(!v||Object.getPrototypeOf(v)!==Object.prototype)fail('InvalidProjection')
-    const keys=Object.getOwnPropertyNames(v);if(keys.length>1024||Object.getOwnPropertySymbols(v).length)fail('ProjectionLimitExceeded')
-    const out={};add(keys.length+2)
-    for(const k of keys.sort()){
-      const d=Object.getOwnPropertyDescriptor(v,k)
-      if(!d.enumerable||d.get||d.set||['__proto__','constructor','prototype','toJSON'].includes(k))fail('InvalidProjection')
-      text(k,512);add(byteLength(k)+3);out[k]=walk(v[k],depth+1)
+  return Object.freeze(result);
+}
+var digest = (value) => sha256(canonical(value));
+function frozen(value) {
+  const pending = [{ value, depth: 0 }], seen = /* @__PURE__ */ new WeakSet();
+  let nodes = 0;
+  while (pending.length) {
+    const current = pending.pop();
+    if (++nodes > 32768 || current.depth > 20) fail("ProjectionLimitExceeded");
+    const v = current.value;
+    if (!v || typeof v !== "object" || seen.has(v)) continue;
+    seen.add(v);
+    for (const key of Object.keys(v)) {
+      const d = Object.getOwnPropertyDescriptor(v, key);
+      if (!d || !("value" in d)) fail("InvalidProjection");
+      pending.push({ value: d.value, depth: current.depth + 1 });
+      if (pending.length > 32768) fail("ProjectionLimitExceeded");
     }
-    return out
+    Object.freeze(v);
   }
-  const encoded=JSON.stringify(walk(value,0));if(byteLength(encoded)>maximum)fail('ProjectionLimitExceeded');return encoded
-}
-export const digest=value=>sha256(canonical(value))
-export function frozen(v){if(v&&typeof v==='object'){Object.values(v).forEach(frozen);Object.freeze(v)}return v}
-export function copy(v){return JSON.parse(canonical(v))}
-export function sourceRef(v){shape(v,['owner','ref','revision','kind']);for(const k of ['owner','ref','revision','kind'])text(v[k]);return copy(v)}
-export const sourceKey=v=>canonical(sourceRef(v))
-export function unique(values,key=x=>x){const ids=new Set();for(const v of values){const id=key(v);if(ids.has(id))fail('InvalidProjection');ids.add(id)}return values}
-export const roles=Object.freeze(['Primary','Context','Interpretation','Evidence','Provenance','Resolution','Inspector','Actions','Activity'])
-export function request(v){
-  canonical(v);shape(v,['key','producer','sources','focus','purpose','visibilityRef','limits'])
-  text(v.key);text(v.focus);text(v.purpose);text(v.visibilityRef)
-  shape(v.producer,['id','version','contract','configuration']);text(v.producer.id);text(v.producer.version);text(v.producer.contract);text(v.producer.configuration)
-  const l=limits(v.limits),sources=unique(list(v.sources,l.sources).map(sourceRef),s=>canonical([s.owner,s.ref])).sort((a,b)=>sourceKey(a)<sourceKey(b)?-1:1)
-  if(!sources.length)fail('SourceUnavailable')
-  return frozen({...copy(v),sources,limits:l})
+  return value;
+}
+var copy = (v) => JSON.parse(canonical(v));
+var json = (v) => JSON.parse(canonical(v));
+function sourceRef(v) {
+  shape(v, ["owner", "ref", "revision", "kind"]);
+  return copy({ owner: text(v.owner), ref: text(v.ref), revision: text(v.revision), kind: text(v.kind) });
+}
+var sourceKey = (v) => canonical(sourceRef(v));
+function unique(values, key = (x) => x) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const v of values) {
+    const id = key(v);
+    if (ids.has(id)) fail("InvalidProjection");
+    ids.add(id);
+  }
+  return values;
+}
+var roles = Object.freeze(["Primary", "Context", "Interpretation", "Evidence", "Provenance", "Resolution", "Inspector", "Actions", "Activity"]);
+function request(v) {
+  canonical(v);
+  shape(v, ["key", "producer", "sources", "focus", "purpose", "visibilityRef", "limits"]);
+  shape(v.producer, ["id", "version", "contract", "configuration"]);
+  const producer = { id: text(v.producer.id), version: text(v.producer.version), contract: text(v.producer.contract), configuration: text(v.producer.configuration) };
+  const l = limits(v.limits), sources = unique(list(v.sources, l.sources).map(sourceRef), (s) => canonical([s.owner, s.ref])).sort((a, b) => sourceKey(a) < sourceKey(b) ? -1 : 1);
+  if (!sources.length) fail("SourceUnavailable");
+  return frozen({ key: text(v.key), producer, sources, focus: text(v.focus), purpose: text(v.purpose), visibilityRef: text(v.visibilityRef), limits: l });
 }
+export {
+  LIMITS,
+  ProjectionError,
+  canonical,
+  choice,
+  copy,
+  digest,
+  fail,
+  frozen,
+  json,
+  limits,
+  list,
+  record,
+  refs,
+  request,
+  roles,
+  shape,
+  sourceKey,
+  sourceRef,
+  text,
+  unique
+};

package/src/hash-browser.d.mts

@@ -0,0 +1 @@
+export declare const sha256: (value: string) => string;

package/src/hash-browser.mjs

@@ -1,5 +1,11 @@
-// Same SHA-256 UTF-8 bytes and hexadecimal identity as the Node contract.
-// Reuse the already selected unjs primitive, never a second projection algorithm.
-import {digest} from 'ohash/crypto'
-export const sha256=value=>Array.from(atob(digest(value).replaceAll('-','+').replaceAll('_','/')+'='),
-  c=>c.charCodeAt(0).toString(16).padStart(2,'0')).join('')
+// Generated from canonical TypeScript; do not edit.
+
+// implementation/hash-browser.mts
+import { digest } from "ohash/crypto";
+var sha256 = (value) => Array.from(
+  atob(digest(value).replaceAll("-", "+").replaceAll("_", "/") + "="),
+  (c) => c.charCodeAt(0).toString(16).padStart(2, "0")
+).join("");
+export {
+  sha256
+};

package/src/hash-node.d.mts

@@ -0,0 +1 @@
+export declare const sha256: (value: string) => string;

package/src/hash-node.mjs

@@ -1,2 +1,8 @@
-import {createHash} from 'node:crypto'
-export const sha256=value=>createHash('sha256').update(value).digest('hex')
+// Generated from canonical TypeScript; do not edit.
+
+// implementation/hash-node.mts
+import { createHash } from "node:crypto";
+var sha256 = (value) => createHash("sha256").update(value).digest("hex");
+export {
+  sha256
+};

package/src/index.d.mts

@@ -1,27 +1,6 @@
-export { ProjectionError, LIMITS, canonical } from './client.mjs';
-export type * from './client.mjs';
+export { ProjectionError, LIMITS, canonical } from './contract.mjs';
+export { produce, scene, validateSnapshot, rebuild, recovery, adoptSnapshot } from './producer.mjs';
+export { ProjectionSlot, pendingRepair, repair } from './publication.mjs';
 export type * from './types/input.mjs';
-import type { DataProjection, SceneProjection } from './client.mjs';
-import type { ProjectionRequest, ExactSource, SceneConfiguration, ReadExact } from './types/input.mjs';
-export type Snapshot = DataProjection | SceneProjection;
-export interface PublicationTicket { readonly key: string; readonly expected: string }
-export interface PublicationReceipt extends PublicationTicket { readonly publication: string; readonly revision: string }
-export interface PendingRepair { readonly ticket: PublicationTicket; readonly request: ProjectionRequest; readonly failure: 'ProjectionUnavailable' | 'ProjectionLimitExceeded' }
-/** Validate and deterministically seal explicitly selected owner-visible data. */
-export function produce(input: ProjectionRequest, exactSources: readonly ExactSource[]): DataProjection;
-export function scene(data: DataProjection, configuration: SceneConfiguration): SceneProjection;
-export function validateSnapshot(value: unknown): Snapshot;
-export function rebuild(input: ProjectionRequest, readExact: ReadExact): DataProjection;
-export function recovery(snapshot: Snapshot, receiverRevision: string | null):
-  { kind: 'NoChange'; revision: string } | { kind: 'Snapshot'; revision: string; payload: Uint8Array };
-export function adoptSnapshot(snapshot: Snapshot, expected: { key: string; revision: string }): Readonly<Snapshot>;
-/** Disposable in-memory publication fence; it does not survive process restart. */
-export class ProjectionSlot {
-  constructor(key: string);
-  begin(): Readonly<PublicationTicket>;
-  publish(ticket: PublicationTicket, snapshot: Snapshot): Readonly<PublicationReceipt>;
-  read(): Readonly<Snapshot> | null;
-  dropCache(): void;
-}
-export function pendingRepair(ticket: PublicationTicket, input: ProjectionRequest, code: PendingRepair['failure']): Readonly<PendingRepair>;
-export function repair(slot: ProjectionSlot, pending: PendingRepair, readExact: ReadExact): Readonly<PublicationReceipt>;
+export type * from './types/snapshot.mjs';
+export type * from './types/publication.mjs';

package/src/index.mjs

@@ -1,3 +1,20 @@
-export {ProjectionError,LIMITS,canonical} from './contract.mjs'
-export {produce,scene,validateSnapshot,rebuild,recovery,adoptSnapshot} from './producer.mjs'
-export {ProjectionSlot,pendingRepair,repair} from './publication.mjs'
+// Generated from canonical TypeScript; do not edit.
+
+// implementation/index.mts
+import { ProjectionError, LIMITS, canonical } from "./contract.mjs";
+import { produce, scene, validateSnapshot, rebuild, recovery, adoptSnapshot } from "./producer.mjs";
+import { ProjectionSlot, pendingRepair, repair } from "./publication.mjs";
+export {
+  LIMITS,
+  ProjectionError,
+  ProjectionSlot,
+  adoptSnapshot,
+  canonical,
+  pendingRepair,
+  produce,
+  rebuild,
+  recovery,
+  repair,
+  scene,
+  validateSnapshot
+};

package/src/produce.d.mts

@@ -0,0 +1,3 @@
+import type { ProjectionRequest, ExactSource } from './types/input.mjs';
+import type { DataProjection } from './types/snapshot.mjs';
+export declare function produce(input: ProjectionRequest, exactSources: readonly ExactSource[]): DataProjection;

package/src/producer.d.mts

@@ -0,0 +1,4 @@
+export { produce } from './produce.mjs';
+export { scene } from './scene.mjs';
+export { validateSnapshot } from './snapshot.mjs';
+export { rebuild, recovery, adoptSnapshot } from './recovery.mjs';