@czap/core 0.1.0

package/dist/harness/pure-transform.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Harness template for the `pureTransform` assembly arm.
+ *
+ * Emits a property test per declared invariant: derives a fast-check
+ * arbitrary from the capsule's input schema (`schemaToArbitrary`),
+ * invokes the capsule's `run` handler against each sample, and asserts
+ * the invariant `check(input, output)` holds.
+ *
+ * If the capsule does not export a `run` handler the test is emitted as
+ * `it.skip` with a TODO comment — vacuous `() => true` placeholders are
+ * banned (per memory: "no vanity tests, real APIs, deterministic
+ * assertions").
+ *
+ * @module
+ */
+import type { CapsuleDef } from '../assembly.js';
+/** Emitted file contents for a capsule harness (test + bench pair). */
+export interface HarnessOutput {
+    readonly testFile: string;
+    readonly benchFile: string;
+}
+/**
+ * Optional metadata the compile-time driver passes to harness templates so
+ * the generated test file can `import` the real capsule binding from its
+ * source file. When `bindingImport` is undefined, the harness emits an
+ * `it.skip` placeholder rather than a vacuous test.
+ */
+export interface HarnessContext {
+    /** ESM-style import specifier (with `.js` extension) for the test file. */
+    readonly bindingImport?: string;
+    /** Exported binding name to import from `bindingImport`. */
+    readonly bindingName?: string;
+    /** Import specifier for `schemaToArbitrary`, default to source path. */
+    readonly arbitraryImport?: string;
+}
+/**
+ * Generate the test + bench file contents for a `pureTransform` capsule.
+ * The emitted files are strings; the repo compiler writes them to
+ * `tests/generated/<name>.{test,bench}.ts`.
+ */
+export declare function generatePureTransform(cap: CapsuleDef<'pureTransform', unknown, unknown, unknown>, ctx?: HarnessContext): HarnessOutput;
+//# sourceMappingURL=pure-transform.d.ts.map

package/dist/harness/pure-transform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pure-transform.d.ts","sourceRoot":"","sources":["../../src/harness/pure-transform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,2EAA2E;IAC3E,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,wEAAwE;IACxE,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAID;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,UAAU,CAAC,eAAe,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAC3D,GAAG,GAAE,cAAmB,GACvB,aAAa,CAwEf"}

package/dist/harness/pure-transform.js

@@ -0,0 +1,76 @@
+const DEFAULT_ARBITRARY_IMPORT = '../../packages/core/src/harness/arbitrary-from-schema.js';
+/**
+ * Generate the test + bench file contents for a `pureTransform` capsule.
+ * The emitted files are strings; the repo compiler writes them to
+ * `tests/generated/<name>.{test,bench}.ts`.
+ */
+export function generatePureTransform(cap, ctx = {}) {
+    const arbitraryImport = ctx.arbitraryImport ?? DEFAULT_ARBITRARY_IMPORT;
+    if (ctx.bindingImport === undefined || ctx.bindingName === undefined) {
+        // No real binding wired — emit honest skip per task constraint.
+        const testFile = `// GENERATED — do not edit by hand
+import { describe, it } from 'vitest';
+
+describe('${cap.name}', () => {
+  it.skip('invariants under random input (no binding wired)', () => {
+    // TODO(harness): no capsule binding import wired by capsule-compile.
+    // Add bindingImport + bindingName to the manifest entry to enable.
+  });
+});
+`;
+        const benchFile = `// GENERATED — do not edit by hand
+import { bench } from 'vitest';
+
+bench('${cap.name}', () => {
+  // handler invocation with a canonical fixture
+}, { time: 500 });
+`;
+        return { testFile, benchFile };
+    }
+    const testFile = `// GENERATED — do not edit by hand
+import { describe, it } from 'vitest';
+import * as fc from 'fast-check';
+import { ${ctx.bindingName} } from '${ctx.bindingImport}';
+import { schemaToArbitrary, UnsupportedSchemaError } from '${arbitraryImport}';
+
+describe('${cap.name}', () => {
+  const cap = ${ctx.bindingName};
+  let arb: fc.Arbitrary<unknown>;
+  let arbError: unknown;
+  try {
+    arb = schemaToArbitrary(cap.input as never) as fc.Arbitrary<unknown>;
+  } catch (err) {
+    arbError = err;
+  }
+  if (cap.run === undefined || arbError !== undefined) {
+    it.skip(
+      arbError instanceof UnsupportedSchemaError
+        ? \`invariants — input schema not arbitrary-derivable (\${arbError.message})\`
+        : 'invariants — capsule has no run handler',
+      () => {},
+    );
+  } else {
+    for (const inv of cap.invariants) {
+      it(\`invariant: \${inv.name}\`, () => {
+        fc.assert(
+          fc.property(arb, (input) => {
+            const output = cap.run!(input as never);
+            return inv.check(input as never, output as never);
+          }),
+          { numRuns: 100 },
+        );
+      });
+    }
+  }
+});
+`;
+    const benchFile = `// GENERATED — do not edit by hand
+import { bench } from 'vitest';
+
+bench('${cap.name}', () => {
+  // handler invocation with a canonical fixture
+}, { time: 500 });
+`;
+    return { testFile, benchFile };
+}
+//# sourceMappingURL=pure-transform.js.map

package/dist/harness/pure-transform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pure-transform.js","sourceRoot":"","sources":["../../src/harness/pure-transform.ts"],"names":[],"mappings":"AAsCA,MAAM,wBAAwB,GAAG,0DAA0D,CAAC;AAE5F;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CACnC,GAA2D,EAC3D,MAAsB,EAAE;IAExB,MAAM,eAAe,GAAG,GAAG,CAAC,eAAe,IAAI,wBAAwB,CAAC;IAExE,IAAI,GAAG,CAAC,aAAa,KAAK,SAAS,IAAI,GAAG,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACrE,gEAAgE;QAChE,MAAM,QAAQ,GAAG;;;YAGT,GAAG,CAAC,IAAI;;;;;;CAMnB,CAAC;QACE,MAAM,SAAS,GAAG;;;SAGb,GAAG,CAAC,IAAI;;;CAGhB,CAAC;QACE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;IACjC,CAAC;IAED,MAAM,QAAQ,GAAG;;;WAGR,GAAG,CAAC,WAAW,YAAY,GAAG,CAAC,aAAa;6DACM,eAAe;;YAEhE,GAAG,CAAC,IAAI;gBACJ,GAAG,CAAC,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6B9B,CAAC;IAEA,MAAM,SAAS,GAAG;;;SAGX,GAAG,CAAC,IAAI;;;CAGhB,CAAC;IAEA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;AACjC,CAAC"}

package/dist/harness/receipted-mutation.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Harness template for the `receiptedMutation` assembly arm.
+ *
+ * Receipted mutations have side effects, so the harness can't drive them
+ * with random inputs and assert generic invariants. Each test case is
+ * emitted as `it.skip` with a TODO until the arm acquires a typed
+ * runtime invocation channel.
+ *
+ * Per memory: "no vanity tests" — emitting a `() => true` placeholder
+ * pretending to verify behavior is worse than skipping honestly.
+ *
+ * @module
+ */
+import type { CapsuleDef } from '../assembly.js';
+import type { HarnessOutput } from './pure-transform.js';
+/**
+ * Generate the test + bench file contents for a `receiptedMutation` capsule.
+ * Emits `it.skip` placeholders covering contract shape, idempotency, audit
+ * receipt, and fault reachability — each carries a TODO naming the
+ * invocation channel it would need.
+ */
+export declare function generateReceiptedMutation(cap: CapsuleDef<'receiptedMutation', unknown, unknown, unknown>): HarnessOutput;
+//# sourceMappingURL=receipted-mutation.d.ts.map

package/dist/harness/receipted-mutation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipted-mutation.d.ts","sourceRoot":"","sources":["../../src/harness/receipted-mutation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,UAAU,CAAC,mBAAmB,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,GAC9D,aAAa,CAiCf"}

package/dist/harness/receipted-mutation.js

@@ -0,0 +1,52 @@
+/**
+ * Harness template for the `receiptedMutation` assembly arm.
+ *
+ * Receipted mutations have side effects, so the harness can't drive them
+ * with random inputs and assert generic invariants. Each test case is
+ * emitted as `it.skip` with a TODO until the arm acquires a typed
+ * runtime invocation channel.
+ *
+ * Per memory: "no vanity tests" — emitting a `() => true` placeholder
+ * pretending to verify behavior is worse than skipping honestly.
+ *
+ * @module
+ */
+/**
+ * Generate the test + bench file contents for a `receiptedMutation` capsule.
+ * Emits `it.skip` placeholders covering contract shape, idempotency, audit
+ * receipt, and fault reachability — each carries a TODO naming the
+ * invocation channel it would need.
+ */
+export function generateReceiptedMutation(cap) {
+    const testFile = `// GENERATED — do not edit by hand
+import { describe, it } from 'vitest';
+
+describe('${cap.name}', () => {
+  it.skip('contract shape: input and output decode/encode round-trip', () => {
+    // TODO(harness): wire schema round-trip via cap.input / cap.output.
+  });
+
+  it.skip('is idempotent: two identical inputs produce equivalent receipts', () => {
+    // TODO(harness): receipted mutations need a runtime channel to invoke
+    // — until cap exposes a typed mutate handler, skip rather than fake.
+  });
+
+  it.skip('emits audit receipt with declared capabilities', () => {
+    // TODO(harness): same — needs runtime channel to read emitted receipts.
+  });
+
+  it.skip('fault injection: declared faults are reachable', () => {
+    // TODO(harness): faults table not yet on the capsule contract.
+  });
+});
+`;
+    const benchFile = `// GENERATED — do not edit by hand
+import { bench } from 'vitest';
+
+bench('${cap.name}', () => {
+  // mutation invocation with a canonical fixture
+}, { time: 500 });
+`;
+    return { testFile, benchFile };
+}
+//# sourceMappingURL=receipted-mutation.js.map

package/dist/harness/receipted-mutation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipted-mutation.js","sourceRoot":"","sources":["../../src/harness/receipted-mutation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CACvC,GAA+D;IAE/D,MAAM,QAAQ,GAAG;;;YAGP,GAAG,CAAC,IAAI;;;;;;;;;;;;;;;;;;CAkBnB,CAAC;IAEA,MAAM,SAAS,GAAG;;;SAGX,GAAG,CAAC,IAAI;;;CAGhB,CAAC;IAEA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;AACjC,CAAC"}

package/dist/harness/scene-composition.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Harness template for the `sceneComposition` assembly arm.
+ *
+ * Scene composition tests need a deterministic frame-stream channel
+ * (`compileScene` + `renderFrame`) on the capsule contract to drive
+ * determinism, sync-accuracy, per-frame budget, and invariant
+ * preservation. Without that channel each case is emitted as `it.skip`.
+ *
+ * @module
+ */
+import type { CapsuleDef } from '../assembly.js';
+import type { HarnessOutput } from './pure-transform.js';
+/**
+ * Generate the test + bench file contents for a `sceneComposition` capsule.
+ * Emits `it.skip` placeholders for determinism, sync, budget, and
+ * invariant-preservation cases.
+ */
+export declare function generateSceneComposition(cap: CapsuleDef<'sceneComposition', unknown, unknown, unknown>): HarnessOutput;
+//# sourceMappingURL=scene-composition.d.ts.map

package/dist/harness/scene-composition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-composition.d.ts","sourceRoot":"","sources":["../../src/harness/scene-composition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,UAAU,CAAC,kBAAkB,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,GAC7D,aAAa,CAgCf"}

package/dist/harness/scene-composition.js

@@ -0,0 +1,47 @@
+/**
+ * Harness template for the `sceneComposition` assembly arm.
+ *
+ * Scene composition tests need a deterministic frame-stream channel
+ * (`compileScene` + `renderFrame`) on the capsule contract to drive
+ * determinism, sync-accuracy, per-frame budget, and invariant
+ * preservation. Without that channel each case is emitted as `it.skip`.
+ *
+ * @module
+ */
+/**
+ * Generate the test + bench file contents for a `sceneComposition` capsule.
+ * Emits `it.skip` placeholders for determinism, sync, budget, and
+ * invariant-preservation cases.
+ */
+export function generateSceneComposition(cap) {
+    const testFile = `// GENERATED — do not edit by hand
+import { describe, it } from 'vitest';
+
+describe('${cap.name}', () => {
+  it.skip('determinism: identical seed produces identical frame stream across 3 runs', () => {
+    // TODO(harness): needs cap.compile + cap.renderFrame on the contract.
+  });
+
+  it.skip('sync accuracy: audio and video frame timestamps align within +/- 1ms', () => {
+    // TODO(harness): same — needs typed frame stream.
+  });
+
+  it.skip('per-frame budget: p95 frame time below declared budget (${cap.budgets.p95Ms ?? 'n/a'}ms)', () => {
+    // TODO(harness): needs cap.renderFrame to time individual frames.
+  });
+
+  it.skip('invariant preservation: every declared scene invariant holds across playback', () => {
+    // TODO(harness): same — needs frame walker.
+  });
+});
+`;
+    const benchFile = `// GENERATED — do not edit by hand
+import { bench } from 'vitest';
+
+bench('${cap.name} — full playback', () => {
+  // render full scene duration, measure total wall-clock
+}, { time: 2000 });
+`;
+    return { testFile, benchFile };
+}
+//# sourceMappingURL=scene-composition.js.map

package/dist/harness/scene-composition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-composition.js","sourceRoot":"","sources":["../../src/harness/scene-composition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CACtC,GAA8D;IAE9D,MAAM,QAAQ,GAAG;;;YAGP,GAAG,CAAC,IAAI;;;;;;;;;qEASiD,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI,KAAK;;;;;;;;CAQ9F,CAAC;IAEA,MAAM,SAAS,GAAG;;;SAGX,GAAG,CAAC,IAAI;;;CAGhB,CAAC;IAEA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;AACjC,CAAC"}

package/dist/harness/site-adapter.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Harness template for the `siteAdapter` assembly arm.
+ *
+ * Site adapters convert between native host objects and czap representations.
+ * Without typed `toCzap` / `fromCzap` channels on the capsule contract the
+ * harness can't drive round-trip equality, so each case is emitted as
+ * `it.skip` rather than a vacuous placeholder.
+ *
+ * @module
+ */
+import type { CapsuleDef } from '../assembly.js';
+import type { HarnessOutput } from './pure-transform.js';
+/**
+ * Generate the test + bench file contents for a `siteAdapter` capsule.
+ * Emits `it.skip` placeholders for round-trip and host-capability tests.
+ */
+export declare function generateSiteAdapter(cap: CapsuleDef<'siteAdapter', unknown, unknown, unknown>): HarnessOutput;
+//# sourceMappingURL=site-adapter.d.ts.map

package/dist/harness/site-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"site-adapter.d.ts","sourceRoot":"","sources":["../../src/harness/site-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,UAAU,CAAC,aAAa,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,GAAG,aAAa,CAwB5G"}

package/dist/harness/site-adapter.js

@@ -0,0 +1,38 @@
+/**
+ * Harness template for the `siteAdapter` assembly arm.
+ *
+ * Site adapters convert between native host objects and czap representations.
+ * Without typed `toCzap` / `fromCzap` channels on the capsule contract the
+ * harness can't drive round-trip equality, so each case is emitted as
+ * `it.skip` rather than a vacuous placeholder.
+ *
+ * @module
+ */
+/**
+ * Generate the test + bench file contents for a `siteAdapter` capsule.
+ * Emits `it.skip` placeholders for round-trip and host-capability tests.
+ */
+export function generateSiteAdapter(cap) {
+    const testFile = `// GENERATED — do not edit by hand
+import { describe, it } from 'vitest';
+
+describe('${cap.name}', () => {
+  it.skip('round-trip equality: native -> czap -> native preserves structure', () => {
+    // TODO(harness): needs cap.toCzap / cap.fromCzap on the contract.
+  });
+
+  it.skip('host capability matrix: each declared site supports the adapter', () => {
+    // TODO(harness): needs per-site dispatcher to invoke under each runtime.
+  });
+});
+`;
+    const benchFile = `// GENERATED — do not edit by hand
+import { bench } from 'vitest';
+
+bench('${cap.name}', () => {
+  // adapter call with a canonical native fixture
+}, { time: 500 });
+`;
+    return { testFile, benchFile };
+}
+//# sourceMappingURL=site-adapter.js.map

package/dist/harness/site-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"site-adapter.js","sourceRoot":"","sources":["../../src/harness/site-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAyD;IAC3F,MAAM,QAAQ,GAAG;;;YAGP,GAAG,CAAC,IAAI;;;;;;;;;CASnB,CAAC;IAEA,MAAM,SAAS,GAAG;;;SAGX,GAAG,CAAC,IAAI;;;CAGhB,CAAC;IAEA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;AACjC,CAAC"}

package/dist/harness/state-machine.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Harness template for the `stateMachine` assembly arm.
+ *
+ * State machines need a typed `step(state, event)` channel to drive
+ * randomized event sequences and check invariants at every step. The
+ * capsule contract doesn't yet expose one, so each case is emitted as
+ * `it.skip` rather than a vacuous `() => true` placeholder.
+ *
+ * @module
+ */
+import type { CapsuleDef } from '../assembly.js';
+import type { HarnessOutput } from './pure-transform.js';
+/**
+ * Generate the test + bench file contents for a `stateMachine` capsule.
+ * Emits `it.skip` placeholders covering illegal transitions, replay, and
+ * invariant preservation — each carries a TODO naming the missing handler.
+ */
+export declare function generateStateMachine(cap: CapsuleDef<'stateMachine', unknown, unknown, unknown>): HarnessOutput;
+//# sourceMappingURL=state-machine.d.ts.map

package/dist/harness/state-machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-machine.d.ts","sourceRoot":"","sources":["../../src/harness/state-machine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,UAAU,CAAC,cAAc,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,GAAG,aAAa,CA6B9G"}

package/dist/harness/state-machine.js

@@ -0,0 +1,44 @@
+/**
+ * Harness template for the `stateMachine` assembly arm.
+ *
+ * State machines need a typed `step(state, event)` channel to drive
+ * randomized event sequences and check invariants at every step. The
+ * capsule contract doesn't yet expose one, so each case is emitted as
+ * `it.skip` rather than a vacuous `() => true` placeholder.
+ *
+ * @module
+ */
+/**
+ * Generate the test + bench file contents for a `stateMachine` capsule.
+ * Emits `it.skip` placeholders covering illegal transitions, replay, and
+ * invariant preservation — each carries a TODO naming the missing handler.
+ */
+export function generateStateMachine(cap) {
+    const testFile = `// GENERATED — do not edit by hand
+import { describe, it } from 'vitest';
+
+describe('${cap.name}', () => {
+  it.skip('rejects every illegal transition', () => {
+    // TODO(harness): needs cap.transitions table + cap.step handler.
+  });
+
+  it.skip('replays deterministically from an event log', () => {
+    // TODO(harness): needs cap.step + cap.initialState.
+  });
+
+  it.skip('invariant holds across random event paths', () => {
+    // TODO(harness): same — schemaToArbitrary on cap.input would feed
+    // events, but invariants need (state, event) → state to be checkable.
+  });
+});
+`;
+    const benchFile = `// GENERATED — do not edit by hand
+import { bench } from 'vitest';
+
+bench('${cap.name}', () => {
+  // state-machine step with a canonical event
+}, { time: 500 });
+`;
+    return { testFile, benchFile };
+}
+//# sourceMappingURL=state-machine.js.map

package/dist/harness/state-machine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-machine.js","sourceRoot":"","sources":["../../src/harness/state-machine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAA0D;IAC7F,MAAM,QAAQ,GAAG;;;YAGP,GAAG,CAAC,IAAI;;;;;;;;;;;;;;CAcnB,CAAC;IAEA,MAAM,SAAS,GAAG;;;SAGX,GAAG,CAAC,IAAI;;;CAGhB,CAAC;IAEA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;AACjC,CAAC"}

package/dist/hlc.d.ts

@@ -0,0 +1,99 @@
+/**
+ * HLC -- Hybrid Logical Clock.
+ *
+ * Pure functions + Effect-based managed clock.
+ *
+ * @module
+ */
+import type { Effect } from 'effect';
+import { Ref } from 'effect';
+interface HLCShape {
+    readonly wall_ms: number;
+    readonly counter: number;
+    readonly node_id: string;
+}
+/**
+ * Compare two HLC timestamps. Returns -1, 0, or 1.
+ *
+ * Compares wall_ms first, then counter, then node_id lexicographically.
+ *
+ * @example
+ * ```ts
+ * const a = HLC.create('node-1');
+ * const b = HLC.increment(a, 1000);
+ * const cmp = HLC.compare(a, b);
+ * // cmp === -1 (a is before b)
+ * ```
+ */
+export declare const compare: (a: HLCShape, b: HLCShape) => -1 | 0 | 1;
+/**
+ * Create a managed HLC clock as an Effect Ref.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from 'effect';
+ *
+ * const program = Effect.gen(function* () {
+ *   const clock = yield* HLC.makeClock('node-1');
+ *   const ts = yield* HLC.tick(clock);
+ *   // ts.wall_ms === Date.now() (approximately)
+ * });
+ * ```
+ */
+export declare const makeClock: (nodeId: string) => Effect.Effect<Ref.Ref<HLCShape>>;
+/**
+ * Tick a managed clock forward, returning the new HLC timestamp.
+ *
+ * @example
+ * ```ts
+ * const ts = yield* HLC.tick(clock);
+ * // ts.wall_ms >= previous wall_ms
+ * ```
+ */
+export declare const tick: (clock: Ref.Ref<HLCShape>) => Effect.Effect<HLCShape>;
+/**
+ * Receive a remote HLC timestamp and merge it into the managed clock.
+ *
+ * @example
+ * ```ts
+ * const remoteTs = HLC.decode(remoteEncoded);
+ * const merged = yield* HLC.receive(clock, remoteTs);
+ * // merged.wall_ms >= remoteTs.wall_ms
+ * ```
+ */
+export declare const receive: (clock: Ref.Ref<HLCShape>, remote: HLCShape) => Effect.Effect<HLCShape>;
+/**
+ * HLC namespace -- Hybrid Logical Clock.
+ *
+ * Pure functions for creating, comparing, incrementing, and merging HLC
+ * timestamps, plus Effect-based managed clock helpers. Encodes to/from
+ * a deterministic colon-separated hex string format.
+ *
+ * @example
+ * ```ts
+ * import { HLC } from '@czap/core';
+ *
+ * const a = HLC.increment(HLC.create('A'), Date.now());
+ * const b = HLC.increment(HLC.create('B'), Date.now());
+ * const merged = HLC.merge(a, b, Date.now());
+ * const encoded = HLC.encode(merged);
+ * const decoded = HLC.decode(encoded);
+ * ```
+ */
+export declare const HLC: {
+    create: (nodeId: string) => HLCShape;
+    compare: (a: HLCShape, b: HLCShape) => -1 | 0 | 1;
+    increment: (hlc: HLCShape, now?: number) => HLCShape;
+    merge: (local: HLCShape, remote: HLCShape, now?: number) => HLCShape;
+    encode: (hlc: HLCShape) => string;
+    decode: (s: string) => HLCShape;
+    makeClock: (nodeId: string) => Effect.Effect<Ref.Ref<HLCShape>>;
+    tick: (clock: Ref.Ref<HLCShape>) => Effect.Effect<HLCShape>;
+    receive: (clock: Ref.Ref<HLCShape>, remote: HLCShape) => Effect.Effect<HLCShape>;
+};
+export declare namespace HLC {
+    /** Structural shape of a hybrid logical clock timestamp: `{ wall_ms, counter, node_id }`. */
+    type Shape = HLCShape;
+}
+export {};
+//# sourceMappingURL=hlc.d.ts.map

package/dist/hlc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hlc.d.ts","sourceRoot":"","sources":["../src/hlc.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC;AAI7B,UAAU,QAAQ;IAChB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAiBD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,OAAO,GAAI,GAAG,QAAQ,EAAE,GAAG,QAAQ,KAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAQ3D,CAAC;AA4GF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,SAAS,GAAI,QAAQ,MAAM,KAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAA8B,CAAC;AAEzG;;;;;;;;GAQG;AACH,eAAO,MAAM,IAAI,GAAI,OAAO,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,CACC,CAAC;AAExE;;;;;;;;;GASG;AACH,eAAO,MAAM,OAAO,GAAI,OAAO,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,QAAQ,QAAQ,KAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,CAChB,CAAC;AAE5E;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,GAAG;qBAlMS,MAAM,KAAG,QAAQ;iBAmBf,QAAQ,KAAK,QAAQ,KAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;qBA0BpC,QAAQ,QAAO,MAAM,KAAO,QAAQ;mBA8BtC,QAAQ,UAAU,QAAQ,QAAO,MAAM,KAAO,QAAQ;kBA+BvD,QAAQ,KAAG,MAAM;gBAkBnB,MAAM,KAAG,QAAQ;wBAyBH,MAAM,KAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;kBAW/C,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC;qBAaxC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,UAAU,QAAQ,KAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC;CA+B3F,CAAC;AAEF,MAAM,CAAC,OAAO,WAAW,GAAG,CAAC;IAC3B,6FAA6F;IAC7F,KAAY,KAAK,GAAG,QAAQ,CAAC;CAC9B"}