@elytracms/core 0.0.6

package/dist/collaboration/comments.js

@@ -0,0 +1,118 @@
+import { z } from 'zod';
+import { createSequentialClock, createSequentialIds } from './core';
+/**
+ * Comment threads (EC-127). A thread anchors to a target — a graph node id or a CMS document ref —
+ * and holds an ordered list of messages. Threads can be resolved and reopened; state persists in
+ * the store. A notification hook fires on every change so a host can surface alerts.
+ */
+/** What a thread is attached to. */
+export const commentAnchorSchema = z.object({
+    kind: z.enum(['node', 'document']),
+    /** Node id (kind=node) or `${collection}/${id}` (kind=document). */
+    ref: z.string().min(1),
+});
+export const commentMessageSchema = z.object({
+    id: z.string(),
+    author: z.string().optional(),
+    body: z.string().min(1),
+    at: z.string(),
+});
+export const commentThreadSchema = z.object({
+    id: z.string(),
+    projectId: z.string().min(1),
+    anchor: commentAnchorSchema,
+    resolved: z.boolean(),
+    messages: z.array(commentMessageSchema),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+});
+export class CommentStore {
+    byProject = new Map();
+    clock;
+    ids;
+    listeners = new Set();
+    constructor(options = {}) {
+        this.clock = options.clock ?? createSequentialClock();
+        this.ids = options.ids ?? createSequentialIds();
+    }
+    /** Subscribe to comment changes; returns an unsubscribe function. */
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    notify(type, thread) {
+        for (const listener of this.listeners)
+            listener({ type, thread });
+    }
+    list_(projectId) {
+        const existing = this.byProject.get(projectId);
+        if (existing)
+            return existing;
+        const created = [];
+        this.byProject.set(projectId, created);
+        return created;
+    }
+    find(projectId, threadId) {
+        const list = this.list_(projectId);
+        const index = list.findIndex((t) => t.id === threadId);
+        return index < 0 ? undefined : { list, index };
+    }
+    /** Start a thread on an anchor with its first message. */
+    start(projectId, anchor, body, author) {
+        const now = this.clock();
+        const thread = commentThreadSchema.parse({
+            id: this.ids('thr'),
+            projectId,
+            anchor,
+            resolved: false,
+            messages: [{ id: this.ids('msg'), ...(author !== undefined ? { author } : {}), body, at: now }],
+            createdAt: now,
+            updatedAt: now,
+        });
+        this.list_(projectId).push(thread);
+        this.notify('created', thread);
+        return thread;
+    }
+    /** Reply to a thread. Returns the updated thread, or `undefined` if unknown. */
+    reply(projectId, threadId, body, author) {
+        const found = this.find(projectId, threadId);
+        if (!found)
+            return undefined;
+        const now = this.clock();
+        const message = commentMessageSchema.parse({ id: this.ids('msg'), ...(author !== undefined ? { author } : {}), body, at: now });
+        const updated = { ...found.list[found.index], messages: [...found.list[found.index].messages, message], updatedAt: now };
+        found.list[found.index] = updated;
+        this.notify('replied', updated);
+        return updated;
+    }
+    setResolved(projectId, threadId, resolved) {
+        const found = this.find(projectId, threadId);
+        if (!found)
+            return undefined;
+        const current = found.list[found.index];
+        if (current.resolved === resolved)
+            return current;
+        const updated = { ...current, resolved, updatedAt: this.clock() };
+        found.list[found.index] = updated;
+        this.notify(resolved ? 'resolved' : 'reopened', updated);
+        return updated;
+    }
+    resolve(projectId, threadId) {
+        return this.setResolved(projectId, threadId, true);
+    }
+    reopen(projectId, threadId) {
+        return this.setResolved(projectId, threadId, false);
+    }
+    /** All threads for a project (optionally filtered by anchor), newest → oldest. */
+    list(projectId, anchor) {
+        const all = [...this.list_(projectId)].reverse();
+        if (!anchor)
+            return all;
+        return all.filter((t) => t.anchor.kind === anchor.kind && t.anchor.ref === anchor.ref);
+    }
+    /** Count of open (unresolved) threads — for badges. */
+    openCount(projectId) {
+        return this.list_(projectId).filter((t) => !t.resolved).length;
+    }
+}
+//# sourceMappingURL=comments.js.map

package/dist/collaboration/comments.js.map

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

package/dist/collaboration/core.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @elytracms/collaboration core (brief §10, Phase 10). Versioning + collaboration is modelled as
+ * pure, in-memory stores over deterministic primitives (an injected clock + id counter), so every
+ * flow — versions, publish history, rollback, presence, comments, approval, environments — is
+ * reproducible from fixtures and never throws (validation is data, brief §4.11). A Convex backend
+ * sits behind the same store interfaces in production.
+ */
+/** Returns an ISO-8601 timestamp; injected so tests stay deterministic. */
+export type Clock = () => string;
+/** A monotonic id generator; injected for determinism. */
+export type IdGen = (kind: string) => string;
+/** Deterministic clock: starts at `startISO`, advances `stepMs` per call. */
+export declare function createSequentialClock(startISO?: string, stepMs?: number): Clock;
+/** Deterministic id generator: `${kind}_000001`, monotonic per-kind. */
+export declare function createSequentialIds(): IdGen;
+/** A participant in a collaboration session (presence, authorship, comments). */
+export interface Actor {
+    id: string;
+    name: string;
+}
+/** Options shared by every store — injected clock + id generator for determinism. */
+export interface StoreOptions {
+    clock?: Clock;
+    ids?: IdGen;
+}

package/dist/collaboration/core.js

@@ -0,0 +1,26 @@
+/**
+ * @elytracms/collaboration core (brief §10, Phase 10). Versioning + collaboration is modelled as
+ * pure, in-memory stores over deterministic primitives (an injected clock + id counter), so every
+ * flow — versions, publish history, rollback, presence, comments, approval, environments — is
+ * reproducible from fixtures and never throws (validation is data, brief §4.11). A Convex backend
+ * sits behind the same store interfaces in production.
+ */
+/** Deterministic clock: starts at `startISO`, advances `stepMs` per call. */
+export function createSequentialClock(startISO = '2026-01-01T00:00:00.000Z', stepMs = 1000) {
+    let current = Date.parse(startISO);
+    return () => {
+        const iso = new Date(current).toISOString();
+        current += stepMs;
+        return iso;
+    };
+}
+/** Deterministic id generator: `${kind}_000001`, monotonic per-kind. */
+export function createSequentialIds() {
+    const counters = new Map();
+    return (kind) => {
+        const next = (counters.get(kind) ?? 0) + 1;
+        counters.set(kind, next);
+        return `${kind}_${String(next).padStart(6, '0')}`;
+    };
+}
+//# sourceMappingURL=core.js.map

package/dist/collaboration/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../../src/collaboration/core.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH,6EAA6E;AAC7E,MAAM,UAAU,qBAAqB,CAAC,QAAQ,GAAG,0BAA0B,EAAE,MAAM,GAAG,IAAI;IACxF,IAAI,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAA;IAClC,OAAO,GAAG,EAAE;QACV,MAAM,GAAG,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,CAAA;QAC3C,OAAO,IAAI,MAAM,CAAA;QACjB,OAAO,GAAG,CAAA;IACZ,CAAC,CAAA;AACH,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,mBAAmB;IACjC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAA;IAC1C,OAAO,CAAC,IAAY,EAAE,EAAE;QACtB,MAAM,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAA;QAC1C,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;QACxB,OAAO,GAAG,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAA;IACnD,CAAC,CAAA;AACH,CAAC"}

package/dist/collaboration/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @elytracms/collaboration — versioning + collaboration over the canonical project (brief §10,
+ * Phase 10, EC-122–129). Project versions, draft/published preview, per-environment publish
+ * history, rollbacks, presence + soft locks + optimistic-concurrency conflicts, comment threads,
+ * and an approval-gated publishing workflow — all as pure, deterministic, never-throwing stores.
+ */
+export declare const PACKAGE = "@elytracms/core/collaboration";
+export * from './core';
+export * from './versions';
+export * from './publishing';
+export * from './approval';
+export * from './comments';
+export * from './presence';
+export * from './collaboration';

package/dist/collaboration/index.js

@@ -0,0 +1,15 @@
+/**
+ * @elytracms/collaboration — versioning + collaboration over the canonical project (brief §10,
+ * Phase 10, EC-122–129). Project versions, draft/published preview, per-environment publish
+ * history, rollbacks, presence + soft locks + optimistic-concurrency conflicts, comment threads,
+ * and an approval-gated publishing workflow — all as pure, deterministic, never-throwing stores.
+ */
+export const PACKAGE = '@elytracms/core/collaboration';
+export * from './core';
+export * from './versions';
+export * from './publishing';
+export * from './approval';
+export * from './comments';
+export * from './presence';
+export * from './collaboration';
+//# sourceMappingURL=index.js.map

package/dist/collaboration/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/collaboration/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,+BAA+B,CAAA;AAEtD,cAAc,QAAQ,CAAA;AACtB,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA"}

package/dist/collaboration/presence.d.ts

@@ -0,0 +1,62 @@
+import type { Actor, StoreOptions } from './core';
+/**
+ * Multi-user editing primitives (EC-126): presence (who is here + what they're focused on), soft
+ * node locks (advisory — claim a node so concurrent edits don't silently clobber), and optimistic
+ * concurrency conflict detection (an edit committed against a stale base version is reported as a
+ * conflict, never lost). These are the primitives; a Convex backend supplies live transport.
+ */
+export interface Participant {
+    actor: Actor;
+    /** The node the participant currently has selected, if any. */
+    focusNodeId?: string;
+    since: string;
+}
+export interface NodeLock {
+    nodeId: string;
+    actorId: string;
+    at: string;
+}
+/** The outcome of attempting to acquire a lock. */
+export interface LockResult {
+    ok: boolean;
+    /** The current owner (the requester on success, or the conflicting holder on failure). */
+    ownerId: string;
+}
+/** The outcome of committing an optimistic edit. */
+export interface CommitResult {
+    ok: boolean;
+    conflict: boolean;
+    /** When `conflict`, the head version the edit must be rebased onto. */
+    headVersion: number;
+}
+export declare class PresenceStore {
+    private readonly participants;
+    private readonly locks;
+    private readonly clock;
+    constructor(options?: StoreOptions);
+    private people;
+    private lockMap;
+    /** Mark an actor present (idempotent; preserves an existing focus). */
+    join(projectId: string, actor: Actor): Participant;
+    /** Remove an actor and release every lock it held (no edits are lost — locks are advisory). */
+    leave(projectId: string, actorId: string): void;
+    /** Update an actor's focused node (presence cursor). */
+    focus(projectId: string, actorId: string, focusNodeId: string | undefined): void;
+    /** Everyone present, in join order. */
+    list(projectId: string): Participant[];
+    /**
+     * Acquire a soft lock on a node. Succeeds if it is free or already held by the requester;
+     * fails (reporting the holder) if another actor holds it.
+     */
+    lockNode(projectId: string, nodeId: string, actorId: string): LockResult;
+    /** Release a lock the actor holds (no-op if free or held by someone else). */
+    unlockNode(projectId: string, nodeId: string, actorId: string): void;
+    /** The actor holding a node's lock, if any. */
+    lockOwner(projectId: string, nodeId: string): string | undefined;
+    /**
+     * Commit an optimistic edit made against `baseVersion`. If the head has advanced past the base
+     * (a concurrent commit landed), the edit is reported as a conflict to be rebased — never
+     * silently lost. Otherwise it succeeds against the new head.
+     */
+    commitEdit(baseVersion: number, headVersion: number): CommitResult;
+}

package/dist/collaboration/presence.js

@@ -0,0 +1,85 @@
+import { createSequentialClock } from './core';
+export class PresenceStore {
+    participants = new Map();
+    locks = new Map();
+    clock;
+    constructor(options = {}) {
+        this.clock = options.clock ?? createSequentialClock();
+    }
+    people(projectId) {
+        const existing = this.participants.get(projectId);
+        if (existing)
+            return existing;
+        const created = new Map();
+        this.participants.set(projectId, created);
+        return created;
+    }
+    lockMap(projectId) {
+        const existing = this.locks.get(projectId);
+        if (existing)
+            return existing;
+        const created = new Map();
+        this.locks.set(projectId, created);
+        return created;
+    }
+    /** Mark an actor present (idempotent; preserves an existing focus). */
+    join(projectId, actor) {
+        const people = this.people(projectId);
+        const existing = people.get(actor.id);
+        const participant = existing ?? { actor, since: this.clock() };
+        people.set(actor.id, participant);
+        return participant;
+    }
+    /** Remove an actor and release every lock it held (no edits are lost — locks are advisory). */
+    leave(projectId, actorId) {
+        this.people(projectId).delete(actorId);
+        const locks = this.lockMap(projectId);
+        for (const [nodeId, lock] of locks)
+            if (lock.actorId === actorId)
+                locks.delete(nodeId);
+    }
+    /** Update an actor's focused node (presence cursor). */
+    focus(projectId, actorId, focusNodeId) {
+        const participant = this.people(projectId).get(actorId);
+        if (participant) {
+            this.people(projectId).set(actorId, { ...participant, ...(focusNodeId !== undefined ? { focusNodeId } : { focusNodeId: undefined }) });
+        }
+    }
+    /** Everyone present, in join order. */
+    list(projectId) {
+        return [...this.people(projectId).values()];
+    }
+    /**
+     * Acquire a soft lock on a node. Succeeds if it is free or already held by the requester;
+     * fails (reporting the holder) if another actor holds it.
+     */
+    lockNode(projectId, nodeId, actorId) {
+        const locks = this.lockMap(projectId);
+        const held = locks.get(nodeId);
+        if (held && held.actorId !== actorId)
+            return { ok: false, ownerId: held.actorId };
+        locks.set(nodeId, { nodeId, actorId, at: this.clock() });
+        return { ok: true, ownerId: actorId };
+    }
+    /** Release a lock the actor holds (no-op if free or held by someone else). */
+    unlockNode(projectId, nodeId, actorId) {
+        const locks = this.lockMap(projectId);
+        if (locks.get(nodeId)?.actorId === actorId)
+            locks.delete(nodeId);
+    }
+    /** The actor holding a node's lock, if any. */
+    lockOwner(projectId, nodeId) {
+        return this.lockMap(projectId).get(nodeId)?.actorId;
+    }
+    /**
+     * Commit an optimistic edit made against `baseVersion`. If the head has advanced past the base
+     * (a concurrent commit landed), the edit is reported as a conflict to be rebased — never
+     * silently lost. Otherwise it succeeds against the new head.
+     */
+    commitEdit(baseVersion, headVersion) {
+        if (baseVersion < headVersion)
+            return { ok: false, conflict: true, headVersion };
+        return { ok: true, conflict: false, headVersion: headVersion + 1 };
+    }
+}
+//# sourceMappingURL=presence.js.map

package/dist/collaboration/presence.js.map

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

package/dist/collaboration/publishing.d.ts

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+import type { StoreOptions } from './core';
+/**
+ * Publishing (EC-129), publish history (EC-124), and draft-vs-published preview resolution
+ * (EC-123). A deployment IS one environment (EC-179, vision AD-8), so publishing is a single
+ * draft/published axis — NOT a per-environment matrix. The deployment pins the one version that
+ * is live; publishing, reverting and rolling back all append to an append-only event log. Moving
+ * a release between environments (staging → production) is a deployment/code-pipeline concern, not
+ * an in-deployment promote — see `env-is-deployment-boundary`.
+ */
+export type PublishAction = 'publish' | 'unpublish' | 'rollback';
+export type PreviewMode = 'draft' | 'published';
+/** Live publish state of the deployment. */
+export declare const publishStateSchema: z.ZodObject<{
+    publishedVersionId: z.ZodOptional<z.ZodString>;
+    publishedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PublishState = z.infer<typeof publishStateSchema>;
+/** A single publish-history event. */
+export declare const publishEventSchema: z.ZodObject<{
+    id: z.ZodString;
+    projectId: z.ZodString;
+    action: z.ZodEnum<{
+        rollback: "rollback";
+        publish: "publish";
+        unpublish: "unpublish";
+    }>;
+    versionId: z.ZodOptional<z.ZodString>;
+    author: z.ZodOptional<z.ZodString>;
+    note: z.ZodOptional<z.ZodString>;
+    at: z.ZodString;
+}, z.core.$strip>;
+export type PublishEvent = z.infer<typeof publishEventSchema>;
+export declare class PublishingStore {
+    /** projectId → live state. */
+    private readonly states;
+    /** projectId → events (append-only). */
+    private readonly events;
+    private readonly clock;
+    private readonly ids;
+    constructor(options?: StoreOptions);
+    private eventList;
+    private record;
+    /** The live state of the deployment (defaults to unpublished). */
+    state(projectId: string): PublishState;
+    /** Publish a version (EC-129). Appends a history event (EC-124). */
+    publish(projectId: string, versionId: string, author?: string): PublishState;
+    /** Revert to draft (no live version). */
+    unpublish(projectId: string, author?: string): PublishState;
+    /** Record a rollback publish (the version is a rollback version). */
+    rollback(projectId: string, versionId: string, author?: string): PublishState;
+    /** Full publish history, newest → oldest. */
+    history(projectId: string): PublishEvent[];
+    /**
+     * Resolve which version to render for a preview mode (EC-123). `published` → the live version;
+     * `draft` → the working draft version the caller supplies. Lets a preview render draft content
+     * distinctly from what is published.
+     */
+    resolveVersion(projectId: string, mode: PreviewMode, draftVersionId?: string): string | undefined;
+}

package/dist/collaboration/publishing.js

@@ -0,0 +1,93 @@
+import { z } from 'zod';
+import { createSequentialClock, createSequentialIds } from './core';
+/** Live publish state of the deployment. */
+export const publishStateSchema = z.object({
+    /** The version live in this deployment, or undefined when nothing is published. */
+    publishedVersionId: z.string().optional(),
+    publishedAt: z.string().optional(),
+});
+/** A single publish-history event. */
+export const publishEventSchema = z.object({
+    id: z.string(),
+    projectId: z.string().min(1),
+    action: z.enum(['publish', 'unpublish', 'rollback']),
+    versionId: z.string().optional(),
+    author: z.string().optional(),
+    note: z.string().optional(),
+    at: z.string(),
+});
+export class PublishingStore {
+    /** projectId → live state. */
+    states = new Map();
+    /** projectId → events (append-only). */
+    events = new Map();
+    clock;
+    ids;
+    constructor(options = {}) {
+        this.clock = options.clock ?? createSequentialClock();
+        this.ids = options.ids ?? createSequentialIds();
+    }
+    eventList(projectId) {
+        const existing = this.events.get(projectId);
+        if (existing)
+            return existing;
+        const created = [];
+        this.events.set(projectId, created);
+        return created;
+    }
+    record(projectId, action, versionId, author, note) {
+        const event = publishEventSchema.parse({
+            id: this.ids('pub'),
+            projectId,
+            action,
+            ...(versionId !== undefined ? { versionId } : {}),
+            ...(author !== undefined ? { author } : {}),
+            ...(note !== undefined ? { note } : {}),
+            at: this.clock(),
+        });
+        this.eventList(projectId).push(event);
+        return event;
+    }
+    /** The live state of the deployment (defaults to unpublished). */
+    state(projectId) {
+        return this.states.get(projectId) ?? {};
+    }
+    /** Publish a version (EC-129). Appends a history event (EC-124). */
+    publish(projectId, versionId, author) {
+        const at = this.clock();
+        const state = { publishedVersionId: versionId, publishedAt: at };
+        this.states.set(projectId, state);
+        this.record(projectId, 'publish', versionId, author);
+        return state;
+    }
+    /** Revert to draft (no live version). */
+    unpublish(projectId, author) {
+        const state = {};
+        this.states.set(projectId, state);
+        this.record(projectId, 'unpublish', undefined, author);
+        return state;
+    }
+    /** Record a rollback publish (the version is a rollback version). */
+    rollback(projectId, versionId, author) {
+        const at = this.clock();
+        const state = { publishedVersionId: versionId, publishedAt: at };
+        this.states.set(projectId, state);
+        this.record(projectId, 'rollback', versionId, author, 'Rolled back to a prior version.');
+        return state;
+    }
+    /** Full publish history, newest → oldest. */
+    history(projectId) {
+        return [...this.eventList(projectId)].reverse();
+    }
+    /**
+     * Resolve which version to render for a preview mode (EC-123). `published` → the live version;
+     * `draft` → the working draft version the caller supplies. Lets a preview render draft content
+     * distinctly from what is published.
+     */
+    resolveVersion(projectId, mode, draftVersionId) {
+        if (mode === 'draft')
+            return draftVersionId;
+        return this.state(projectId).publishedVersionId;
+    }
+}
+//# sourceMappingURL=publishing.js.map

package/dist/collaboration/publishing.js.map

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

package/dist/collaboration/versions.d.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+import type { StoreOptions } from './core';
+/**
+ * Project versioning (EC-122) + rollback (EC-125). A version is an immutable snapshot of project
+ * state (the serialized graph) with metadata. Versions are append-only and numbered per project;
+ * a rollback creates a NEW version whose snapshot equals a prior one's — history is never
+ * rewritten, so the rollback itself is auditable.
+ */
+export type VersionOrigin = 'edit' | 'import' | 'rollback';
+export declare const versionRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    projectId: z.ZodString;
+    number: z.ZodNumber;
+    snapshot: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+    author: z.ZodOptional<z.ZodString>;
+    origin: z.ZodEnum<{
+        edit: "edit";
+        import: "import";
+        rollback: "rollback";
+    }>;
+    parentId: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
+export type VersionRecord = z.infer<typeof versionRecordSchema>;
+export interface CreateVersionInput {
+    snapshot: string;
+    label?: string;
+    message?: string;
+    author?: string;
+    origin?: VersionOrigin;
+}
+/** In-memory, append-only version store. */
+export declare class VersionStore {
+    private readonly byProject;
+    private readonly clock;
+    private readonly ids;
+    constructor(options?: StoreOptions);
+    private list_;
+    /** Append a new version. Returns the created record. */
+    create(projectId: string, input: CreateVersionInput): VersionRecord;
+    /** All versions for a project, oldest → newest. */
+    list(projectId: string): VersionRecord[];
+    get(projectId: string, versionId: string): VersionRecord | undefined;
+    latest(projectId: string): VersionRecord | undefined;
+    /**
+     * Roll back to a prior version (EC-125): appends a NEW version carrying the target's snapshot.
+     * Returns `undefined` if the target version doesn't exist (the caller surfaces it as an issue).
+     */
+    rollback(projectId: string, toVersionId: string, author?: string): VersionRecord | undefined;
+}