@czap/core 0.1.0

package/src/harness/cached-projection.ts

@@ -0,0 +1,46 @@
+/**
+ * Harness template for the `cachedProjection` assembly arm.
+ *
+ * Cached projections derive an output from a source via a deterministic
+ * pipeline with cache invalidation tied to source content addresses.
+ * Without a `derive(source)` channel on the contract the harness can't
+ * exercise cache-hit equality or invalidation, 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 `cachedProjection` capsule.
+ * Emits `it.skip` placeholders for cache-hit and invalidation tests.
+ */
+export function generateCachedProjection(
+  cap: CapsuleDef<'cachedProjection', unknown, unknown, unknown>,
+): HarnessOutput {
+  const testFile = `// GENERATED — do not edit by hand
+import { describe, it } from 'vitest';
+
+describe('${cap.name}', () => {
+  it.skip('cache hit: identical source yields the same derived output', () => {
+    // TODO(harness): needs cap.derive handler + content-addressed source.
+  });
+
+  it.skip('invalidation: source change produces new cache entry', () => {
+    // TODO(harness): same — needs cap.derive.
+  });
+});
+`;
+
+  const benchFile = `// GENERATED — do not edit by hand
+import { bench } from 'vitest';
+
+bench('${cap.name} — decode throughput', () => {
+  // decode a canonical source, measure p95 vs budget (${cap.budgets.p95Ms ?? 'n/a'}ms)
+}, { time: 500 });
+`;
+
+  return { testFile, benchFile };
+}

package/src/harness/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Harness — per-arm templates that emit test + bench + audit files
+ * from a capsule declaration. Each arm has its own generator.
+ *
+ * @module
+ */
+
+export { generatePureTransform } from './pure-transform.js';
+export type { HarnessOutput, HarnessContext } from './pure-transform.js';
+export { ArbitraryFromSchema, schemaToArbitrary, UnsupportedSchemaError } from './arbitrary-from-schema.js';
+export { generateReceiptedMutation } from './receipted-mutation.js';
+export { generateStateMachine } from './state-machine.js';
+export { generateSiteAdapter } from './site-adapter.js';
+export { generatePolicyGate } from './policy-gate.js';
+export { generateCachedProjection } from './cached-projection.js';
+export { generateSceneComposition } from './scene-composition.js';

package/src/harness/policy-gate.ts

@@ -0,0 +1,51 @@
+/**
+ * Harness template for the `policyGate` assembly arm.
+ *
+ * Policy gates resolve allow/deny against typed subjects. Without a
+ * `decide(subject)` channel on the capsule contract the harness can't
+ * exercise allow/deny branches or check reason chains, 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 `policyGate` capsule.
+ * Emits `it.skip` placeholders for allow / deny / reason-chain coverage.
+ */
+export function generatePolicyGate(cap: CapsuleDef<'policyGate', unknown, unknown, unknown>): HarnessOutput {
+  const testFile = `// GENERATED — do not edit by hand
+import { describe, it } from 'vitest';
+
+describe('${cap.name}', () => {
+  it.skip('allow branch: a subject meeting the policy resolves to allow', () => {
+    // TODO(harness): needs cap.decide handler to drive subject -> outcome.
+  });
+
+  it.skip('deny branch: a subject failing the policy resolves to deny', () => {
+    // TODO(harness): same — needs cap.decide.
+  });
+
+  it.skip('reason chain present on every decision', () => {
+    // TODO(harness): same — needs cap.decide and a typed reasons schema.
+  });
+
+  it.skip('no silent deny: every deny has a typed reason code', () => {
+    // TODO(harness): same — needs reasons enum on the contract.
+  });
+});
+`;
+
+  const benchFile = `// GENERATED — do not edit by hand
+import { bench } from 'vitest';
+
+bench('${cap.name}', () => {
+  // policy decision with a canonical fixture
+}, { time: 500 });
+`;
+
+  return { testFile, benchFile };
+}

package/src/harness/pure-transform.ts

@@ -0,0 +1,121 @@
+/**
+ * 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;
+}
+
+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: CapsuleDef<'pureTransform', unknown, unknown, unknown>,
+  ctx: HarnessContext = {},
+): HarnessOutput {
+  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 };
+}

package/src/harness/receipted-mutation.ts

@@ -0,0 +1,59 @@
+/**
+ * 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 function generateReceiptedMutation(
+  cap: CapsuleDef<'receiptedMutation', unknown, unknown, unknown>,
+): HarnessOutput {
+  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 };
+}

package/src/harness/scene-composition.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 function generateSceneComposition(
+  cap: CapsuleDef<'sceneComposition', unknown, unknown, unknown>,
+): HarnessOutput {
+  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 };
+}

package/src/harness/site-adapter.ts

@@ -0,0 +1,43 @@
+/**
+ * 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 function generateSiteAdapter(cap: CapsuleDef<'siteAdapter', unknown, unknown, unknown>): HarnessOutput {
+  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 };
+}

package/src/harness/state-machine.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 function generateStateMachine(cap: CapsuleDef<'stateMachine', unknown, unknown, unknown>): HarnessOutput {
+  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 };
+}

package/src/hlc.ts

@@ -0,0 +1,238 @@
+/**
+ * HLC -- Hybrid Logical Clock.
+ *
+ * Pure functions + Effect-based managed clock.
+ *
+ * @module
+ */
+
+import type { Effect } from 'effect';
+import { Ref } from 'effect';
+
+// Hybrid Logical Clock: physical wall-clock + logical counter for causal ordering. DagPosition encodes (timestamp, counter, nodeId) for DAG vertex identity.
+
+interface HLCShape {
+  readonly wall_ms: number;
+  readonly counter: number;
+  readonly node_id: string;
+}
+
+/**
+ * Create a new HLC timestamp initialized to zero for the given node.
+ *
+ * @example
+ * ```ts
+ * const hlc = HLC.create('node-1');
+ * // hlc === { wall_ms: 0, counter: 0, node_id: 'node-1' }
+ * ```
+ */
+const _create = (nodeId: string): HLCShape => ({
+  wall_ms: 0,
+  counter: 0,
+  node_id: nodeId,
+});
+
+/**
+ * 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 const compare = (a: HLCShape, b: HLCShape): -1 | 0 | 1 => {
+  if (a.wall_ms < b.wall_ms) return -1;
+  if (a.wall_ms > b.wall_ms) return 1;
+  if (a.counter < b.counter) return -1;
+  if (a.counter > b.counter) return 1;
+  if (a.node_id < b.node_id) return -1;
+  if (a.node_id > b.node_id) return 1;
+  return 0;
+};
+
+// 16-bit counter — supports 65535 events per ms before overflow
+const MAX_COUNTER = 0xffff;
+
+/**
+ * Increment an HLC for a local event.
+ *
+ * Advances wall_ms to max(current, now) and bumps the counter if the wall
+ * time didn't advance. Throws on counter overflow (`> 0xFFFF`).
+ *
+ * @example
+ * ```ts
+ * const hlc0 = HLC.create('node-1');
+ * const hlc1 = HLC.increment(hlc0, Date.now());
+ * // hlc1.wall_ms >= hlc0.wall_ms
+ * ```
+ */
+const _increment = (hlc: HLCShape, now: number = 0): HLCShape => {
+  const newWallMs = Math.max(hlc.wall_ms, now);
+  if (newWallMs === hlc.wall_ms) {
+    const next = hlc.counter + 1;
+    if (next > MAX_COUNTER)
+      throw new Error(
+        `HLC counter overflow: exceeded ${MAX_COUNTER} (>65535 events in 1ms — consider batching or increasing clock resolution)`,
+      );
+    return { wall_ms: newWallMs, counter: next, node_id: hlc.node_id };
+  }
+  return { wall_ms: newWallMs, counter: 0, node_id: hlc.node_id };
+};
+
+/**
+ * Merge a local HLC with a remote HLC on message receive.
+ *
+ * Takes the max of local, remote, and now for wall_ms, then adjusts the
+ * counter accordingly. Preserves the local node_id.
+ *
+ * Lamport causality: if wall clocks agree, increment the higher counter to preserve
+ * happened-before ordering. Reset counter only when wall clock advances (new causal epoch).
+ *
+ * @example
+ * ```ts
+ * const local = HLC.increment(HLC.create('A'), 1000);
+ * const remote = HLC.increment(HLC.create('B'), 2000);
+ * const merged = HLC.merge(local, remote, 1500);
+ * // merged.wall_ms === 2000, merged.node_id === 'A'
+ * ```
+ */
+const _merge = (local: HLCShape, remote: HLCShape, now: number = 0): HLCShape => {
+  const newWallMs = Math.max(local.wall_ms, remote.wall_ms, now);
+  let newCounter: number;
+  if (newWallMs === local.wall_ms && newWallMs === remote.wall_ms) {
+    newCounter = Math.max(local.counter, remote.counter) + 1;
+  } else if (newWallMs === local.wall_ms) {
+    newCounter = local.counter + 1;
+  } else if (newWallMs === remote.wall_ms) {
+    newCounter = remote.counter + 1;
+  } else {
+    newCounter = 0;
+  }
+  if (newCounter > MAX_COUNTER)
+    throw new Error(
+      `HLC counter overflow: exceeded ${MAX_COUNTER} (>65535 events in 1ms — consider batching or increasing clock resolution)`,
+    );
+  return { wall_ms: newWallMs, counter: newCounter, node_id: local.node_id };
+};
+
+/**
+ * Encode an HLC timestamp to a colon-separated hex string.
+ *
+ * Format: `{wall_ms_hex_12}:{counter_hex_4}:{node_id}`
+ *
+ * @example
+ * ```ts
+ * const hlc = HLC.increment(HLC.create('node-1'), 1000);
+ * const encoded = HLC.encode(hlc);
+ * // encoded === '0000000003e8:0000:node-1'
+ * ```
+ */
+const _encode = (hlc: HLCShape): string => {
+  // 12 hex digits = 48-bit wall clock (good to year 10889), 4 hex = 16-bit counter
+  const wallHex = hlc.wall_ms.toString(16).padStart(12, '0');
+  const counterHex = hlc.counter.toString(16).padStart(4, '0');
+  return `${wallHex}:${counterHex}:${hlc.node_id}`;
+};
+
+/**
+ * Decode an HLC timestamp from a colon-separated hex string.
+ *
+ * Inverse of `encode`. Supports node IDs containing colons.
+ *
+ * @example
+ * ```ts
+ * const hlc = HLC.decode('0000000003e8:0000:node-1');
+ * // hlc === { wall_ms: 1000, counter: 0, node_id: 'node-1' }
+ * ```
+ */
+const _decode = (s: string): HLCShape => {
+  const parts = s.split(':');
+  if (parts.length < 3) throw new Error(`Invalid HLC format: expected at least 3 colon-separated parts, got "${s}"`);
+  const wall_ms = parseInt(parts[0]!, 16);
+  const counter = parseInt(parts[1]!, 16);
+  const node_id = parts.slice(2).join(':');
+  if (isNaN(wall_ms)) throw new Error(`Invalid HLC format: wall_ms is not valid hex in "${s}"`);
+  if (isNaN(counter)) throw new Error(`Invalid HLC format: counter is not valid hex in "${s}"`);
+  return { wall_ms, counter, node_id };
+};
+
+/**
+ * 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 const makeClock = (nodeId: string): Effect.Effect<Ref.Ref<HLCShape>> => Ref.make(_create(nodeId));
+
+/**
+ * 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 const tick = (clock: Ref.Ref<HLCShape>): Effect.Effect<HLCShape> =>
+  Ref.updateAndGet(clock, (current) => _increment(current, Date.now()));
+
+/**
+ * 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 const receive = (clock: Ref.Ref<HLCShape>, remote: HLCShape): Effect.Effect<HLCShape> =>
+  Ref.updateAndGet(clock, (current) => _merge(current, remote, Date.now()));
+
+/**
+ * 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 const HLC = {
+  create: _create,
+  compare,
+  increment: _increment,
+  merge: _merge,
+  encode: _encode,
+  decode: _decode,
+  makeClock,
+  tick,
+  receive,
+};
+
+export declare namespace HLC {
+  /** Structural shape of a hybrid logical clock timestamp: `{ wall_ms, counter, node_id }`. */
+  export type Shape = HLCShape;
+}