@objectstack/metadata-core 5.0.0

package/dist/repository-DJhCkVYK.d.ts

@@ -0,0 +1,307 @@
+import { z } from 'zod';
+
+/**
+ * Metadata Repository types — see ADR-0008 §2.
+ *
+ * All shapes are defined as Zod schemas so the same definition serves
+ * runtime validation and static typing (`z.infer<typeof X>`).
+ */
+
+/**
+ * Canonical metadata type names. Aligned with the `MetadataTypeSchema`
+ * enum in `@objectstack/spec/kernel/metadata-plugin.zod.ts`. New types are
+ * added here in lockstep with that file.
+ */
+declare const MetadataTypeSchema: z.ZodEnum<{
+    object: "object";
+    view: "view";
+    page: "page";
+    dashboard: "dashboard";
+    app: "app";
+    flow: "flow";
+    workflow: "workflow";
+    agent: "agent";
+    tool: "tool";
+    skill: "skill";
+    report: "report";
+    translation: "translation";
+    role: "role";
+    permission: "permission";
+    policy: "policy";
+    api: "api";
+    endpoint: "endpoint";
+    datasource: "datasource";
+    cube: "cube";
+    settings: "settings";
+}>;
+type MetadataType = z.infer<typeof MetadataTypeSchema>;
+/**
+ * Fully-qualified reference to a metadata item. Identity is `(org, type, name)`.
+ *
+ * Per ADR-0008 v2 (2026-05) the metadata layer no longer carries `project`
+ * or `branch`. Project survives only as an **artifact packaging concept**
+ * (the unit a CLI/CI run compiles into `dist/objectstack.json`); it does
+ * not appear in the runtime customization scope. Branching belongs to Git
+ * (or your VCS of choice) and never propagated cleanly into the runtime
+ * model — so it has been removed entirely.
+ *
+ * Higher layers may default `org='system'` for built-ins.
+ *
+ * `version` is optional: omit to mean "HEAD", supply to pin.
+ */
+declare const MetaRefSchema: z.ZodObject<{
+    org: z.ZodString;
+    type: z.ZodEnum<{
+        object: "object";
+        view: "view";
+        page: "page";
+        dashboard: "dashboard";
+        app: "app";
+        flow: "flow";
+        workflow: "workflow";
+        agent: "agent";
+        tool: "tool";
+        skill: "skill";
+        report: "report";
+        translation: "translation";
+        role: "role";
+        permission: "permission";
+        policy: "policy";
+        api: "api";
+        endpoint: "endpoint";
+        datasource: "datasource";
+        cube: "cube";
+        settings: "settings";
+    }>;
+    name: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type MetaRef = z.infer<typeof MetaRefSchema>;
+/**
+ * Construct a stable string key from a MetaRef (excluding `version`,
+ * which is mutable). Used as cache keys and log indexes.
+ */
+declare function refKey(ref: Pick<MetaRef, 'org' | 'type' | 'name'>): string;
+/**
+ * Full metadata item as stored / returned by the Repository.
+ *
+ * `body` is the **canonical, Zod-normalised** spec (with defaults filled
+ * in). `hash` is `sha256(canonicalize(body))`. Equal hashes imply equal
+ * specs.
+ */
+declare const MetadataItemSchema: z.ZodObject<{
+    ref: z.ZodObject<{
+        org: z.ZodString;
+        type: z.ZodEnum<{
+            object: "object";
+            view: "view";
+            page: "page";
+            dashboard: "dashboard";
+            app: "app";
+            flow: "flow";
+            workflow: "workflow";
+            agent: "agent";
+            tool: "tool";
+            skill: "skill";
+            report: "report";
+            translation: "translation";
+            role: "role";
+            permission: "permission";
+            policy: "policy";
+            api: "api";
+            endpoint: "endpoint";
+            datasource: "datasource";
+            cube: "cube";
+            settings: "settings";
+        }>;
+        name: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    body: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    hash: z.ZodString;
+    parentHash: z.ZodNullable<z.ZodString>;
+    authoredBy: z.ZodString;
+    authoredAt: z.ZodString;
+    message: z.ZodOptional<z.ZodString>;
+    seq: z.ZodNumber;
+    schemaVersion: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type MetadataItem = z.infer<typeof MetadataItemSchema>;
+/** Lightweight header for listing — `body` omitted. */
+type MetadataItemHeader = Omit<MetadataItem, 'body'>;
+declare const MetadataOpSchema: z.ZodEnum<{
+    create: "create";
+    update: "update";
+    delete: "delete";
+    rename: "rename";
+}>;
+type MetadataOp = z.infer<typeof MetadataOpSchema>;
+/**
+ * The single event payload broadcast by the change log. ADR-0008 §2.4.
+ *
+ * For `rename`, `previousName` carries the old machine name. For
+ * `delete`, `hash` is null. The payload is intentionally small —
+ * consumers re-fetch via the cache when they need the full body.
+ */
+declare const MetadataEventSchema: z.ZodObject<{
+    seq: z.ZodNumber;
+    op: z.ZodEnum<{
+        create: "create";
+        update: "update";
+        delete: "delete";
+        rename: "rename";
+    }>;
+    ref: z.ZodObject<{
+        org: z.ZodString;
+        type: z.ZodEnum<{
+            object: "object";
+            view: "view";
+            page: "page";
+            dashboard: "dashboard";
+            app: "app";
+            flow: "flow";
+            workflow: "workflow";
+            agent: "agent";
+            tool: "tool";
+            skill: "skill";
+            report: "report";
+            translation: "translation";
+            role: "role";
+            permission: "permission";
+            policy: "policy";
+            api: "api";
+            endpoint: "endpoint";
+            datasource: "datasource";
+            cube: "cube";
+            settings: "settings";
+        }>;
+        name: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    hash: z.ZodNullable<z.ZodString>;
+    parentHash: z.ZodNullable<z.ZodString>;
+    previousName: z.ZodOptional<z.ZodString>;
+    actor: z.ZodString;
+    message: z.ZodOptional<z.ZodString>;
+    ts: z.ZodString;
+    source: z.ZodString;
+}, z.core.$strip>;
+type MetadataEvent = z.infer<typeof MetadataEventSchema>;
+interface PutOptions {
+    /**
+     * Hash this writer believed was at HEAD. `null` means "creating, expect
+     * absence". A mismatch throws ConflictError.
+     */
+    parentVersion: string | null;
+    /** Identity of the writer; mirrored to MetadataEvent.actor. */
+    actor: string;
+    /** Optional human-readable commit message. */
+    message?: string;
+    /** Optional label for the change log "source" column. */
+    source?: string;
+}
+interface PutResult {
+    /** New content hash assigned to the spec. */
+    version: string;
+    /** Sequence number of the emitted MetadataEvent. */
+    seq: number;
+    /** The committed item (canonicalised). */
+    item: MetadataItem;
+}
+interface DeleteOptions {
+    parentVersion: string;
+    actor: string;
+    message?: string;
+    source?: string;
+}
+interface DeleteResult {
+    seq: number;
+}
+interface ListFilter {
+    org?: string;
+    type?: MetadataType;
+    /** Substring match on `name`; case-sensitive. */
+    nameContains?: string;
+    /** Pagination cursor; opaque string from a previous response. */
+    cursor?: string;
+    /** Page size; implementations may clamp. */
+    limit?: number;
+}
+interface WatchFilter {
+    org?: string;
+    type?: MetadataType;
+    /** When omitted, match all names within the scope. */
+    name?: string;
+}
+interface HistoryOptions {
+    /** Lower bound (exclusive) for pagination. */
+    sinceSeq?: number;
+    limit?: number;
+}
+
+/**
+ * The `MetadataRepository` interface — single point of pluggability for
+ * the metadata storage backend. See ADR-0008 §2.6.
+ *
+ * Implementations:
+ *
+ * - `InMemoryRepository` (this package, for tests & edge)
+ * - `FileSystemRepository` (`@objectstack/metadata`)
+ * - `LayeredRepository` (`@objectstack/metadata`)
+ * - `PostgresRepository` (`@objectstack/metadata-postgres`, M1)
+ *
+ * Implementation contract — what every backend MUST guarantee:
+ *
+ * 1. **Atomic put.** A successful `put()` either fully applies (item
+ *    visible to subsequent `get` AND an event present in the log) or
+ *    does not apply at all. No half-states.
+ * 2. **Monotonic seq per org.** `seq` is strictly increasing within
+ *    `org`. Different orgs have independent sequences. (Repositories
+ *    scoped to a single org may treat the entire repo as one log.)
+ * 3. **Optimistic locking.** `put` and `delete` throw `ConflictError`
+ *    when `parentVersion` does not match the current HEAD.
+ * 4. **Canonical hashing.** `item.hash === hashSpec(item.body)` — always.
+ * 5. **Event ordering.** Subscribers to `watch()` receive events in
+ *    monotonically-increasing `seq` order with no gaps.
+ * 6. **Resumability.** `watch(_, since)` MUST replay all events with
+ *    `seq > since` before delivering live events.
+ * 7. **Tombstones, not holes.** `delete` produces a `delete` event;
+ *    `get` returns null but `history` still shows the lineage.
+ */
+
+interface MetadataRepository {
+    /** Read HEAD or a pinned version. Returns null if absent. */
+    get(ref: MetaRef): Promise<MetadataItem | null>;
+    /**
+     * Write a new version. Atomic.
+     * @throws ConflictError if `parentVersion` does not match HEAD.
+     * @throws SchemaValidationError if `spec` fails Zod normalisation.
+     */
+    put(ref: MetaRef, spec: unknown, opts: PutOptions): Promise<PutResult>;
+    /**
+     * Soft-delete (tombstone). `parentVersion` is required.
+     * @throws ConflictError on parent mismatch.
+     */
+    delete(ref: MetaRef, opts: DeleteOptions): Promise<DeleteResult>;
+    /** Enumerate items matching a filter. Implementations may stream. */
+    list(filter: ListFilter): AsyncIterable<MetadataItemHeader>;
+    /** Per-item history; events in monotonic `seq` order. */
+    history(ref: MetaRef, opts?: HistoryOptions): AsyncIterable<MetadataEvent>;
+    /**
+     * Live event stream. The iterator MUST:
+     *
+     *   - Replay all events with `seq > since` before yielding any new event.
+     *   - Stay open until the consumer breaks the loop.
+     *   - Survive transient backend disconnects (implementation's choice
+     *     how to resume — Postgres LISTEN reconnect, JSONL tail, etc.).
+     */
+    watch(filter: WatchFilter, since?: number): AsyncIterable<MetadataEvent>;
+}
+/**
+ * Sentinel symbol used by `LayeredRepository` (M0 PR-5) to label which
+ * underlying layer emitted an event. Defined here so the contract is
+ * shared.
+ */
+declare const LAYER_SOURCE: unique symbol;
+
+export { type DeleteOptions as D, type HistoryOptions as H, LAYER_SOURCE as L, type MetaRef as M, type PutOptions as P, type WatchFilter as W, type DeleteResult as a, type ListFilter as b, MetaRefSchema as c, type MetadataEvent as d, MetadataEventSchema as e, type MetadataItem as f, type MetadataItemHeader as g, MetadataItemSchema as h, type MetadataOp as i, MetadataOpSchema as j, type MetadataRepository as k, type MetadataType as l, MetadataTypeSchema as m, type PutResult as n, refKey as r };

package/dist/testing.cjs

@@ -0,0 +1,254 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
+
+
+var _chunkF3VZBGKCcjs = require('./chunk-F3VZBGKC.cjs');
+
+// src/contract-suite.ts
+var _vitest = require('vitest');
+var refOf = (overrides = {}) => ({
+  org: "system",
+  type: "view",
+  name: "sample_view",
+  ...overrides
+});
+var spec = (label) => ({ label, columns: ["a", "b"] });
+async function take(iter, n, timeoutMs = 1e3) {
+  const out = [];
+  const it2 = iter[Symbol.asyncIterator]();
+  const deadline = Date.now() + timeoutMs;
+  while (out.length < n) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) break;
+    const result = await Promise.race([
+      it2.next(),
+      new Promise(
+        (resolve) => setTimeout(() => resolve({ value: void 0, done: true }), remaining)
+      )
+    ]);
+    if (result.done) break;
+    out.push(result.value);
+  }
+  await _optionalChain([it2, 'access', _ => _.return, 'optionalCall', _2 => _2(void 0)]);
+  return out;
+}
+function runRepositoryContractTests(label, factory, opts = {}) {
+  _vitest.describe.call(void 0, `MetadataRepository contract \u2014 ${label}`, () => {
+    _vitest.describe.call(void 0, "put / get", () => {
+      _vitest.it.call(void 0, "creates an item from null parent", async () => {
+        const repo = await factory();
+        const ref = refOf();
+        const res = await repo.put(ref, spec("hello"), { parentVersion: null, actor: "tester" });
+        _vitest.expect.call(void 0, res.version).toMatch(/^sha256:[0-9a-f]{64}$/);
+        _vitest.expect.call(void 0, res.version).toBe(_chunkF3VZBGKCcjs.hashSpec.call(void 0, spec("hello")));
+        _vitest.expect.call(void 0, res.seq).toBeGreaterThan(0);
+        _vitest.expect.call(void 0, res.item.parentHash).toBeNull();
+        _vitest.expect.call(void 0, res.item.authoredBy).toBe("tester");
+        const got = await repo.get(ref);
+        _vitest.expect.call(void 0, got).not.toBeNull();
+        _vitest.expect.call(void 0, got.hash).toBe(res.version);
+        _vitest.expect.call(void 0, got.body).toEqual(spec("hello"));
+      });
+      _vitest.it.call(void 0, "round-trips successive updates with parent chaining", async () => {
+        const repo = await factory();
+        const ref = refOf();
+        const a = await repo.put(ref, spec("one"), { parentVersion: null, actor: "t" });
+        const b = await repo.put(ref, spec("two"), { parentVersion: a.version, actor: "t" });
+        const c = await repo.put(ref, spec("three"), { parentVersion: b.version, actor: "t" });
+        _vitest.expect.call(void 0, b.item.parentHash).toBe(a.version);
+        _vitest.expect.call(void 0, c.item.parentHash).toBe(b.version);
+        _vitest.expect.call(void 0, c.seq).toBeGreaterThan(b.seq);
+        _vitest.expect.call(void 0, b.seq).toBeGreaterThan(a.seq);
+      });
+      _vitest.it.call(void 0, "canonical hash invariant: item.hash === hashSpec(item.body)", async () => {
+        const repo = await factory();
+        const ref = refOf();
+        await repo.put(ref, { z: 1, a: 2, m: [3, 1, 2] }, { parentVersion: null, actor: "t" });
+        const got = await repo.get(ref);
+        _vitest.expect.call(void 0, got.hash).toBe(_chunkF3VZBGKCcjs.hashSpec.call(void 0, got.body));
+      });
+      _vitest.it.call(void 0, "returns null for missing item", async () => {
+        const repo = await factory();
+        _vitest.expect.call(void 0, await repo.get(refOf({ name: "never_existed" }))).toBeNull();
+      });
+      _vitest.it.call(void 0, "no-op write with identical content returns current version", async () => {
+        const repo = await factory();
+        const ref = refOf();
+        const a = await repo.put(ref, spec("same"), { parentVersion: null, actor: "t" });
+        const b = await repo.put(ref, spec("same"), { parentVersion: a.version, actor: "t" });
+        _vitest.expect.call(void 0, b.version).toBe(a.version);
+        _vitest.expect.call(void 0, b.seq).toBe(a.seq);
+      });
+    });
+    _vitest.describe.call(void 0, "optimistic locking", () => {
+      _vitest.it.call(void 0, "throws ConflictError when parentVersion mismatches", async () => {
+        const repo = await factory();
+        const ref = refOf();
+        const a = await repo.put(ref, spec("v1"), { parentVersion: null, actor: "t" });
+        await _vitest.expect.call(void 0, 
+          repo.put(ref, spec("v2"), { parentVersion: null, actor: "t" })
+        ).rejects.toBeInstanceOf(_chunkF3VZBGKCcjs.ConflictError);
+        await _vitest.expect.call(void 0, 
+          repo.put(ref, spec("v2"), { parentVersion: "sha256:deadbeef".padEnd(71, "0"), actor: "t" })
+        ).rejects.toBeInstanceOf(_chunkF3VZBGKCcjs.ConflictError);
+        await _vitest.expect.call(void 0, 
+          repo.put(ref, spec("v2"), { parentVersion: a.version, actor: "t" })
+        ).resolves.toMatchObject({ seq: _vitest.expect.any(Number) });
+      });
+      _vitest.it.call(void 0, "throws ConflictError when creating over an existing item with null parent", async () => {
+        const repo = await factory();
+        const ref = refOf();
+        await repo.put(ref, spec("a"), { parentVersion: null, actor: "t" });
+        await _vitest.expect.call(void 0, 
+          repo.put(ref, spec("b"), { parentVersion: null, actor: "t" })
+        ).rejects.toBeInstanceOf(_chunkF3VZBGKCcjs.ConflictError);
+      });
+      _vitest.it.call(void 0, "delete requires correct parentVersion", async () => {
+        const repo = await factory();
+        const ref = refOf();
+        const a = await repo.put(ref, spec("a"), { parentVersion: null, actor: "t" });
+        await _vitest.expect.call(void 0, 
+          repo.delete(ref, { parentVersion: "sha256:wrong".padEnd(71, "0"), actor: "t" })
+        ).rejects.toBeInstanceOf(_chunkF3VZBGKCcjs.ConflictError);
+        await repo.delete(ref, { parentVersion: a.version, actor: "t" });
+      });
+    });
+    _vitest.describe.call(void 0, "monotonic seq per org", () => {
+      _vitest.it.call(void 0, "seq strictly increases within an org", async () => {
+        const repo = await factory();
+        const ref = refOf();
+        const a = await repo.put(ref, spec("1"), { parentVersion: null, actor: "t" });
+        const b = await repo.put(ref, spec("2"), { parentVersion: a.version, actor: "t" });
+        const c = await repo.put(refOf({ name: "other" }), spec("o"), { parentVersion: null, actor: "t" });
+        _vitest.expect.call(void 0, b.seq).toBeGreaterThan(a.seq);
+        _vitest.expect.call(void 0, c.seq).toBeGreaterThan(b.seq);
+      });
+      _vitest.it.call(void 0, "different orgs have independent sequences", async () => {
+        const repo = await factory();
+        const orgA = refOf({ org: "org_a" });
+        const orgB = refOf({ org: "org_b" });
+        let a;
+        let b;
+        try {
+          a = await repo.put(orgA, spec("a1"), { parentVersion: null, actor: "t" });
+          b = await repo.put(orgB, spec("b1"), { parentVersion: null, actor: "t" });
+        } catch (e2) {
+          return;
+        }
+        const c = await repo.put(orgA, spec("a2"), { parentVersion: a.version, actor: "t" });
+        const d = await repo.put(orgB, spec("b2"), { parentVersion: b.version, actor: "t" });
+        _vitest.expect.call(void 0, c.seq).toBeGreaterThan(a.seq);
+        _vitest.expect.call(void 0, d.seq).toBeGreaterThan(b.seq);
+      });
+    });
+    _vitest.describe.call(void 0, "delete / tombstones", () => {
+      _vitest.it.call(void 0, "get returns null after delete; history retains lineage", async () => {
+        const repo = await factory();
+        const ref = refOf();
+        const a = await repo.put(ref, spec("a"), { parentVersion: null, actor: "t" });
+        await repo.delete(ref, { parentVersion: a.version, actor: "t" });
+        _vitest.expect.call(void 0, await repo.get(ref)).toBeNull();
+        const hist = [];
+        for await (const evt of repo.history(ref)) hist.push(evt);
+        _vitest.expect.call(void 0, hist.map((e) => e.op)).toEqual(["create", "delete"]);
+        _vitest.expect.call(void 0, _optionalChain([hist, 'access', _3 => _3[1], 'optionalAccess', _4 => _4.parentHash])).toBe(a.version);
+        _vitest.expect.call(void 0, _optionalChain([hist, 'access', _5 => _5[1], 'optionalAccess', _6 => _6.hash])).toBeNull();
+      });
+      _vitest.it.call(void 0, "can recreate after delete with null parent", async () => {
+        const repo = await factory();
+        const ref = refOf();
+        const a = await repo.put(ref, spec("a"), { parentVersion: null, actor: "t" });
+        await repo.delete(ref, { parentVersion: a.version, actor: "t" });
+        const b = await repo.put(ref, spec("a-redux"), { parentVersion: null, actor: "t" });
+        _vitest.expect.call(void 0, b.item.parentHash).toBeNull();
+      });
+    });
+    _vitest.describe.call(void 0, "watch / history", () => {
+      _vitest.it.call(void 0, "history yields events in monotonic seq order", async () => {
+        const repo = await factory();
+        const ref = refOf();
+        const a = await repo.put(ref, spec("1"), { parentVersion: null, actor: "t" });
+        const b = await repo.put(ref, spec("2"), { parentVersion: a.version, actor: "t" });
+        const c = await repo.put(ref, spec("3"), { parentVersion: b.version, actor: "t" });
+        const evts = [];
+        for await (const e of repo.history(ref)) evts.push(e);
+        _vitest.expect.call(void 0, evts.map((e) => e.seq)).toEqual([a.seq, b.seq, c.seq]);
+        _vitest.expect.call(void 0, evts.every((e, i) => i === 0 || e.seq > evts[i - 1].seq)).toBe(true);
+      });
+      _vitest.it.call(void 0, "watch(sinceSeq) replays subsequent events then goes live", async () => {
+        const repo = await factory();
+        const ref = refOf();
+        const a = await repo.put(ref, spec("1"), { parentVersion: null, actor: "t" });
+        const b = await repo.put(ref, spec("2"), { parentVersion: a.version, actor: "t" });
+        const iter = repo.watch({ org: ref.org }, a.seq);
+        const collected = [];
+        const it2 = iter[Symbol.asyncIterator]();
+        const first = await it2.next();
+        _vitest.expect.call(void 0, first.done).toBe(false);
+        collected.push(first.value);
+        _vitest.expect.call(void 0, collected[0].seq).toBe(b.seq);
+        const livePromise = it2.next();
+        const c = await repo.put(ref, spec("3"), { parentVersion: b.version, actor: "t" });
+        const live = await livePromise;
+        _vitest.expect.call(void 0, live.done).toBe(false);
+        collected.push(live.value);
+        _vitest.expect.call(void 0, collected[1].seq).toBe(c.seq);
+        await _optionalChain([it2, 'access', _7 => _7.return, 'optionalCall', _8 => _8(void 0)]);
+      });
+      _vitest.it.call(void 0, "watch filters by type and name", async () => {
+        const repo = await factory();
+        await repo.put(refOf({ name: "a" }), spec("a"), { parentVersion: null, actor: "t" });
+        await repo.put(refOf({ name: "b" }), spec("b"), { parentVersion: null, actor: "t" });
+        const events = await take(
+          repo.watch({ org: "system", type: "view", name: "a" }),
+          5,
+          200
+        );
+        _vitest.expect.call(void 0, events.length).toBe(1);
+        _vitest.expect.call(void 0, events[0].ref.name).toBe("a");
+      });
+    });
+    _vitest.describe.call(void 0, "list", () => {
+      _vitest.it.call(void 0, "returns headers (no body) for matching items", async () => {
+        const repo = await factory();
+        await repo.put(refOf({ name: "alpha" }), spec("a"), { parentVersion: null, actor: "t" });
+        await repo.put(refOf({ name: "beta" }), spec("b"), { parentVersion: null, actor: "t" });
+        await repo.put(refOf({ type: "object", name: "thing" }), spec("o"), {
+          parentVersion: null,
+          actor: "t"
+        });
+        const headers = [];
+        for await (const h of repo.list({ type: "view" })) headers.push(h);
+        _vitest.expect.call(void 0, headers.length).toBe(2);
+        for (const h of headers) {
+          _vitest.expect.call(void 0, h.body).toBeUndefined();
+        }
+      });
+      _vitest.it.call(void 0, "limit clamps result size", async () => {
+        const repo = await factory();
+        for (let i = 0; i < 5; i++) {
+          await repo.put(refOf({ name: `v_${i}` }), spec(`v${i}`), { parentVersion: null, actor: "t" });
+        }
+        const headers = [];
+        for await (const h of repo.list({ type: "view", limit: 3 })) headers.push(h);
+        _vitest.expect.call(void 0, headers.length).toBe(3);
+      });
+    });
+    if (opts.supportsVersionedReads) {
+      _vitest.describe.call(void 0, "versioned reads", () => {
+        _vitest.it.call(void 0, "get with version pin returns that historical version", async () => {
+          const repo = await factory();
+          const ref = refOf();
+          const a = await repo.put(ref, spec("v1"), { parentVersion: null, actor: "t" });
+          await repo.put(ref, spec("v2"), { parentVersion: a.version, actor: "t" });
+          const pinned = await repo.get({ ...ref, version: a.version });
+          _vitest.expect.call(void 0, _optionalChain([pinned, 'optionalAccess', _9 => _9.hash])).toBe(a.version);
+          _vitest.expect.call(void 0, _optionalChain([pinned, 'optionalAccess', _10 => _10.body])).toEqual(spec("v1"));
+        });
+      });
+    }
+  });
+}
+
+
+exports.runRepositoryContractTests = runRepositoryContractTests;
+//# sourceMappingURL=testing.cjs.map

package/dist/testing.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/home/runner/work/framework/framework/packages/metadata-core/dist/testing.cjs","../src/contract-suite.ts"],"names":["it"],"mappings":"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","file":"/home/runner/work/framework/framework/packages/metadata-core/dist/testing.cjs","sourcesContent":[null,"// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * Parameterised Repository contract test suite. Every `MetadataRepository`\n * implementation MUST pass this suite. Reuse:\n *\n *     import { runRepositoryContractTests } from '@objectstack/metadata-core/test';\n *     runRepositoryContractTests('InMemory', () => new InMemoryRepository());\n *\n * The suite verifies the seven invariants from `repository.ts`:\n *\n *   1. Atomic put\n *   2. Monotonic seq per branch\n *   3. Optimistic locking (ConflictError)\n *   4. Canonical hashing (hash === hashSpec(body))\n *   5. Event ordering (monotonic seq, no gaps)\n *   6. Resumability (watch with `since` replays)\n *   7. Tombstones (delete event emitted, get returns null)\n */\n\nimport { describe, it, expect } from 'vitest';\nimport type { MetadataRepository } from './repository.js';\nimport type { MetaRef, MetadataEvent } from './types.js';\nimport { hashSpec } from './canonicalize.js';\nimport { ConflictError } from './errors.js';\n\nexport interface ContractSuiteOptions {\n  /** If the implementation supports `version`-pinned reads, set true. */\n  supportsVersionedReads?: boolean;\n}\n\nconst refOf = (overrides: Partial<MetaRef> = {}): MetaRef => ({\n  org: 'system',\n  type: 'view',\n  name: 'sample_view',\n  ...overrides,\n});\n\nconst spec = (label: string) => ({ label, columns: ['a', 'b'] });\n\n/** Drain at most `n` events from an async iterable with a timeout. */\nasync function take<T>(iter: AsyncIterable<T>, n: number, timeoutMs = 1000): Promise<T[]> {\n  const out: T[] = [];\n  const it = iter[Symbol.asyncIterator]();\n  const deadline = Date.now() + timeoutMs;\n  while (out.length < n) {\n    const remaining = deadline - Date.now();\n    if (remaining <= 0) break;\n    const result = await Promise.race([\n      it.next(),\n      new Promise<{ value: undefined; done: true }>((resolve) =>\n        setTimeout(() => resolve({ value: undefined, done: true }), remaining),\n      ),\n    ]);\n    if (result.done) break;\n    out.push(result.value as T);\n  }\n  // Close the iterator so the repo subscriber is freed.\n  await it.return?.(undefined);\n  return out;\n}\n\nexport function runRepositoryContractTests(\n  label: string,\n  factory: () => MetadataRepository | Promise<MetadataRepository>,\n  opts: ContractSuiteOptions = {},\n): void {\n  describe(`MetadataRepository contract — ${label}`, () => {\n    // ── 1. Atomic put + canonical hash ──────────────────────────────\n    describe('put / get', () => {\n      it('creates an item from null parent', async () => {\n        const repo = await factory();\n        const ref = refOf();\n        const res = await repo.put(ref, spec('hello'), { parentVersion: null, actor: 'tester' });\n        expect(res.version).toMatch(/^sha256:[0-9a-f]{64}$/);\n        expect(res.version).toBe(hashSpec(spec('hello')));\n        expect(res.seq).toBeGreaterThan(0);\n        expect(res.item.parentHash).toBeNull();\n        expect(res.item.authoredBy).toBe('tester');\n\n        const got = await repo.get(ref);\n        expect(got).not.toBeNull();\n        expect(got!.hash).toBe(res.version);\n        expect(got!.body).toEqual(spec('hello'));\n      });\n\n      it('round-trips successive updates with parent chaining', async () => {\n        const repo = await factory();\n        const ref = refOf();\n        const a = await repo.put(ref, spec('one'), { parentVersion: null, actor: 't' });\n        const b = await repo.put(ref, spec('two'), { parentVersion: a.version, actor: 't' });\n        const c = await repo.put(ref, spec('three'), { parentVersion: b.version, actor: 't' });\n        expect(b.item.parentHash).toBe(a.version);\n        expect(c.item.parentHash).toBe(b.version);\n        expect(c.seq).toBeGreaterThan(b.seq);\n        expect(b.seq).toBeGreaterThan(a.seq);\n      });\n\n      it('canonical hash invariant: item.hash === hashSpec(item.body)', async () => {\n        const repo = await factory();\n        const ref = refOf();\n        await repo.put(ref, { z: 1, a: 2, m: [3, 1, 2] }, { parentVersion: null, actor: 't' });\n        const got = await repo.get(ref);\n        expect(got!.hash).toBe(hashSpec(got!.body));\n      });\n\n      it('returns null for missing item', async () => {\n        const repo = await factory();\n        expect(await repo.get(refOf({ name: 'never_existed' }))).toBeNull();\n      });\n\n      it('no-op write with identical content returns current version', async () => {\n        const repo = await factory();\n        const ref = refOf();\n        const a = await repo.put(ref, spec('same'), { parentVersion: null, actor: 't' });\n        const b = await repo.put(ref, spec('same'), { parentVersion: a.version, actor: 't' });\n        expect(b.version).toBe(a.version);\n        expect(b.seq).toBe(a.seq);\n      });\n    });\n\n    // ── 2 & 3. Optimistic locking + Monotonic seq ───────────────────\n    describe('optimistic locking', () => {\n      it('throws ConflictError when parentVersion mismatches', async () => {\n        const repo = await factory();\n        const ref = refOf();\n        const a = await repo.put(ref, spec('v1'), { parentVersion: null, actor: 't' });\n        await expect(\n          repo.put(ref, spec('v2'), { parentVersion: null, actor: 't' }),\n        ).rejects.toBeInstanceOf(ConflictError);\n        await expect(\n          repo.put(ref, spec('v2'), { parentVersion: 'sha256:deadbeef'.padEnd(71, '0'), actor: 't' }),\n        ).rejects.toBeInstanceOf(ConflictError);\n        // Sanity: correct parent succeeds.\n        await expect(\n          repo.put(ref, spec('v2'), { parentVersion: a.version, actor: 't' }),\n        ).resolves.toMatchObject({ seq: expect.any(Number) });\n      });\n\n      it('throws ConflictError when creating over an existing item with null parent', async () => {\n        const repo = await factory();\n        const ref = refOf();\n        await repo.put(ref, spec('a'), { parentVersion: null, actor: 't' });\n        await expect(\n          repo.put(ref, spec('b'), { parentVersion: null, actor: 't' }),\n        ).rejects.toBeInstanceOf(ConflictError);\n      });\n\n      it('delete requires correct parentVersion', async () => {\n        const repo = await factory();\n        const ref = refOf();\n        const a = await repo.put(ref, spec('a'), { parentVersion: null, actor: 't' });\n        await expect(\n          repo.delete(ref, { parentVersion: 'sha256:wrong'.padEnd(71, '0'), actor: 't' }),\n        ).rejects.toBeInstanceOf(ConflictError);\n        await repo.delete(ref, { parentVersion: a.version, actor: 't' });\n      });\n    });\n\n    describe('monotonic seq per org', () => {\n      it('seq strictly increases within an org', async () => {\n        const repo = await factory();\n        const ref = refOf();\n        const a = await repo.put(ref, spec('1'), { parentVersion: null, actor: 't' });\n        const b = await repo.put(ref, spec('2'), { parentVersion: a.version, actor: 't' });\n        const c = await repo.put(refOf({ name: 'other' }), spec('o'), { parentVersion: null, actor: 't' });\n        expect(b.seq).toBeGreaterThan(a.seq);\n        expect(c.seq).toBeGreaterThan(b.seq);\n      });\n\n      it('different orgs have independent sequences', async () => {\n        const repo = await factory();\n        const orgA = refOf({ org: 'org_a' });\n        const orgB = refOf({ org: 'org_b' });\n        // Some backends (FileSystemRepository) are scoped to a single\n        // org; for those any foreign-org put throws — skip the test.\n        let a: { seq: number; version: string };\n        let b: { seq: number; version: string };\n        try {\n          a = await repo.put(orgA, spec('a1'), { parentVersion: null, actor: 't' });\n          b = await repo.put(orgB, spec('b1'), { parentVersion: null, actor: 't' });\n        } catch {\n          return;\n        }\n        const c = await repo.put(orgA, spec('a2'), { parentVersion: a.version, actor: 't' });\n        const d = await repo.put(orgB, spec('b2'), { parentVersion: b.version, actor: 't' });\n        expect(c.seq).toBeGreaterThan(a.seq);\n        expect(d.seq).toBeGreaterThan(b.seq);\n      });\n    });\n\n    // ── 4. Tombstones ───────────────────────────────────────────────\n    describe('delete / tombstones', () => {\n      it('get returns null after delete; history retains lineage', async () => {\n        const repo = await factory();\n        const ref = refOf();\n        const a = await repo.put(ref, spec('a'), { parentVersion: null, actor: 't' });\n        await repo.delete(ref, { parentVersion: a.version, actor: 't' });\n        expect(await repo.get(ref)).toBeNull();\n        const hist: MetadataEvent[] = [];\n        for await (const evt of repo.history(ref)) hist.push(evt);\n        expect(hist.map((e) => e.op)).toEqual(['create', 'delete']);\n        expect(hist[1]?.parentHash).toBe(a.version);\n        expect(hist[1]?.hash).toBeNull();\n      });\n\n      it('can recreate after delete with null parent', async () => {\n        const repo = await factory();\n        const ref = refOf();\n        const a = await repo.put(ref, spec('a'), { parentVersion: null, actor: 't' });\n        await repo.delete(ref, { parentVersion: a.version, actor: 't' });\n        const b = await repo.put(ref, spec('a-redux'), { parentVersion: null, actor: 't' });\n        expect(b.item.parentHash).toBeNull();\n      });\n    });\n\n    // ── 5. Event ordering & watch replay ────────────────────────────\n    describe('watch / history', () => {\n      it('history yields events in monotonic seq order', async () => {\n        const repo = await factory();\n        const ref = refOf();\n        const a = await repo.put(ref, spec('1'), { parentVersion: null, actor: 't' });\n        const b = await repo.put(ref, spec('2'), { parentVersion: a.version, actor: 't' });\n        const c = await repo.put(ref, spec('3'), { parentVersion: b.version, actor: 't' });\n        const evts: MetadataEvent[] = [];\n        for await (const e of repo.history(ref)) evts.push(e);\n        expect(evts.map((e) => e.seq)).toEqual([a.seq, b.seq, c.seq]);\n        expect(evts.every((e, i) => i === 0 || e.seq > evts[i - 1]!.seq)).toBe(true);\n      });\n\n      it('watch(sinceSeq) replays subsequent events then goes live', async () => {\n        const repo = await factory();\n        const ref = refOf();\n        const a = await repo.put(ref, spec('1'), { parentVersion: null, actor: 't' });\n        const b = await repo.put(ref, spec('2'), { parentVersion: a.version, actor: 't' });\n\n        // Start watching with `since = a.seq` — must replay b, then deliver a live event.\n        const iter = repo.watch({ org: ref.org }, a.seq);\n        const collected: MetadataEvent[] = [];\n        const it = iter[Symbol.asyncIterator]();\n\n        // First yield should be the replay of `b`.\n        const first = await it.next();\n        expect(first.done).toBe(false);\n        collected.push(first.value as MetadataEvent);\n        expect(collected[0]!.seq).toBe(b.seq);\n\n        // Now trigger a live event and collect it.\n        const livePromise = it.next();\n        const c = await repo.put(ref, spec('3'), { parentVersion: b.version, actor: 't' });\n        const live = await livePromise;\n        expect(live.done).toBe(false);\n        collected.push(live.value as MetadataEvent);\n        expect(collected[1]!.seq).toBe(c.seq);\n\n        await it.return?.(undefined);\n      });\n\n      it('watch filters by type and name', async () => {\n        const repo = await factory();\n        await repo.put(refOf({ name: 'a' }), spec('a'), { parentVersion: null, actor: 't' });\n        await repo.put(refOf({ name: 'b' }), spec('b'), { parentVersion: null, actor: 't' });\n        const events = await take(\n          repo.watch({ org: 'system', type: 'view', name: 'a' }),\n          5,\n          200,\n        );\n        expect(events.length).toBe(1);\n        expect(events[0]!.ref.name).toBe('a');\n      });\n    });\n\n    // ── list ────────────────────────────────────────────────────────\n    describe('list', () => {\n      it('returns headers (no body) for matching items', async () => {\n        const repo = await factory();\n        await repo.put(refOf({ name: 'alpha' }), spec('a'), { parentVersion: null, actor: 't' });\n        await repo.put(refOf({ name: 'beta' }), spec('b'), { parentVersion: null, actor: 't' });\n        await repo.put(refOf({ type: 'object', name: 'thing' }), spec('o'), {\n          parentVersion: null,\n          actor: 't',\n        });\n        const headers: unknown[] = [];\n        for await (const h of repo.list({ type: 'view' })) headers.push(h);\n        expect(headers.length).toBe(2);\n        for (const h of headers) {\n          expect((h as { body?: unknown }).body).toBeUndefined();\n        }\n      });\n\n      it('limit clamps result size', async () => {\n        const repo = await factory();\n        for (let i = 0; i < 5; i++) {\n          await repo.put(refOf({ name: `v_${i}` }), spec(`v${i}`), { parentVersion: null, actor: 't' });\n        }\n        const headers: unknown[] = [];\n        for await (const h of repo.list({ type: 'view', limit: 3 })) headers.push(h);\n        expect(headers.length).toBe(3);\n      });\n    });\n\n    // ── Optional behaviour ──────────────────────────────────────────\n    if (opts.supportsVersionedReads) {\n      describe('versioned reads', () => {\n        it('get with version pin returns that historical version', async () => {\n          const repo = await factory();\n          const ref = refOf();\n          const a = await repo.put(ref, spec('v1'), { parentVersion: null, actor: 't' });\n          await repo.put(ref, spec('v2'), { parentVersion: a.version, actor: 't' });\n          const pinned = await repo.get({ ...ref, version: a.version });\n          expect(pinned?.hash).toBe(a.version);\n          expect(pinned?.body).toEqual(spec('v1'));\n        });\n      });\n    }\n  });\n}\n"]}

package/dist/testing.d.cts

@@ -0,0 +1,10 @@
+import { k as MetadataRepository } from './repository-DJhCkVYK.cjs';
+import 'zod';
+
+interface ContractSuiteOptions {
+    /** If the implementation supports `version`-pinned reads, set true. */
+    supportsVersionedReads?: boolean;
+}
+declare function runRepositoryContractTests(label: string, factory: () => MetadataRepository | Promise<MetadataRepository>, opts?: ContractSuiteOptions): void;
+
+export { type ContractSuiteOptions, runRepositoryContractTests };

package/dist/testing.d.ts

@@ -0,0 +1,10 @@
+import { k as MetadataRepository } from './repository-DJhCkVYK.js';
+import 'zod';
+
+interface ContractSuiteOptions {
+    /** If the implementation supports `version`-pinned reads, set true. */
+    supportsVersionedReads?: boolean;
+}
+declare function runRepositoryContractTests(label: string, factory: () => MetadataRepository | Promise<MetadataRepository>, opts?: ContractSuiteOptions): void;
+
+export { type ContractSuiteOptions, runRepositoryContractTests };