@volter/twin 0.1.0 → 0.1.1

package/dist/src/queueLifecycle.d.ts

@@ -1,62 +0,0 @@
-import type { QueuedWorldServiceEvent } from './types.js';
-export type QueueRowStatus = 'queued' | 'committed' | 'ignored' | 'superseded' | 'poisoned';
-export type QueueStatusTransition = {
-    queueId: string;
-    status: QueueRowStatus;
-    at: string;
-    reason?: string;
-    /** for committed rows: the canonical event id it produced. */
-    eventId?: string;
-    /** for superseded rows: the row that replaced it. */
-    supersededBy?: string;
-};
-export type QueueRowWithStatus = {
-    row: QueuedWorldServiceEvent;
-    status: QueueRowStatus;
-    transition?: QueueStatusTransition;
-};
-export declare function setQueueRowStatus(service: string, queueId: string, status: QueueRowStatus, opts?: {
-    root?: string;
-    at?: string;
-    reason?: string;
-    eventId?: string;
-    supersededBy?: string;
-}): QueueStatusTransition;
-export declare function queueRowStatus(service: string, queueId: string, root?: string): QueueRowStatus;
-/** Every queue row with its current lifecycle status. */
-export declare function listQueueWithStatus(service: string, root?: string): QueueRowWithStatus[];
-/** Rows still awaiting a decision (status === 'queued'). */
-export declare function pendingQueueRows(service: string, root?: string): QueuedWorldServiceEvent[];
-export type QueueCounts = Record<QueueRowStatus, number>;
-export declare function queueCounts(service: string, root?: string): QueueCounts;
-/** Commit a single queued row into the canonical event log + stamp `committed`. */
-export declare function commitQueueRow(service: string, queueId: string, opts?: {
-    root?: string;
-    at?: string;
-}): {
-    appended: boolean;
-    eventId?: string;
-};
-export declare function ignoreQueueRow(service: string, queueId: string, opts?: {
-    root?: string;
-    at?: string;
-    reason?: string;
-}): QueueStatusTransition;
-export declare function supersedeQueueRow(service: string, queueId: string, supersededBy: string, opts?: {
-    root?: string;
-    at?: string;
-    reason?: string;
-}): QueueStatusTransition;
-export declare function poisonQueueRow(service: string, queueId: string, opts?: {
-    root?: string;
-    at?: string;
-    reason?: string;
-}): QueueStatusTransition;
-/** Commit all rows currently `queued`, in deterministic provider-time order; stamps committed. */
-export declare function commitPendingQueue(service: string, opts?: {
-    root?: string;
-    at?: string;
-}): {
-    committed: number;
-    eventIds: string[];
-};

package/dist/src/queueLifecycle.js

@@ -1,95 +0,0 @@
-// Event queue lifecycle (the twins architecture notes → "Event Intake Queue").
-// Listener/webhook/broker deliveries land in the durable queue (events stay
-// NON-canonical until committed). This module gives queue rows the named
-// lifecycle the doc specifies — queued | committed | ignored | superseded |
-// poisoned — as an append-only status ledger over the existing queue, so the
-// queue file itself stays immutable delivery history. Current status = the latest
-// transition (default `queued`). Deterministic: caller may supply `at`.
-import { existsSync, mkdirSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { appendDurable, appendEvent, listQueuedEvents, rebuildGenericState, worldPaths } from "./storage.js";
-function statusPath(service, root) {
-    return join(worldPaths(service, root).dir, 'event-queue-status.jsonl');
-}
-function readTransitions(service, root) {
-    const path = statusPath(service, root);
-    if (!existsSync(path))
-        return [];
-    return readFileSync(path, 'utf8').split('\n').filter((l) => l.trim()).map((l) => JSON.parse(l));
-}
-/** Latest transition per queue row (append order is the tiebreak — last wins). */
-function latestByRow(service, root) {
-    const latest = new Map();
-    for (const t of readTransitions(service, root))
-        latest.set(t.queueId, t); // later lines overwrite
-    return latest;
-}
-export function setQueueRowStatus(service, queueId, status, opts = {}) {
-    const path = statusPath(service, opts.root);
-    mkdirSync(join(path, '..'), { recursive: true });
-    const transition = {
-        queueId,
-        status,
-        at: opts.at ?? new Date().toISOString(),
-        ...(opts.reason ? { reason: opts.reason } : {}),
-        ...(opts.eventId ? { eventId: opts.eventId } : {}),
-        ...(opts.supersededBy ? { supersededBy: opts.supersededBy } : {}),
-    };
-    appendDurable(path, `${JSON.stringify(transition)}\n`);
-    return transition;
-}
-export function queueRowStatus(service, queueId, root) {
-    return latestByRow(service, root).get(queueId)?.status ?? 'queued';
-}
-/** Every queue row with its current lifecycle status. */
-export function listQueueWithStatus(service, root) {
-    const latest = latestByRow(service, root);
-    return listQueuedEvents(service, root).map((row) => {
-        const transition = latest.get(row.id);
-        return { row, status: transition?.status ?? 'queued', ...(transition ? { transition } : {}) };
-    });
-}
-/** Rows still awaiting a decision (status === 'queued'). */
-export function pendingQueueRows(service, root) {
-    return listQueueWithStatus(service, root).filter((r) => r.status === 'queued').map((r) => r.row);
-}
-export function queueCounts(service, root) {
-    const counts = { queued: 0, committed: 0, ignored: 0, superseded: 0, poisoned: 0 };
-    for (const r of listQueueWithStatus(service, root))
-        counts[r.status] += 1;
-    return counts;
-}
-/** Commit a single queued row into the canonical event log + stamp `committed`. */
-export function commitQueueRow(service, queueId, opts = {}) {
-    const status = queueRowStatus(service, queueId, opts.root);
-    if (status !== 'queued')
-        throw new Error(`queue row ${queueId} is ${status}, not committable`);
-    const row = listQueuedEvents(service, opts.root).find((r) => r.id === queueId);
-    if (!row)
-        throw new Error(`queue row not found: ${queueId}`);
-    const result = appendEvent(row.event, opts.root);
-    rebuildGenericState(service, opts.root);
-    setQueueRowStatus(service, queueId, 'committed', { ...opts, eventId: result.event.id });
-    return { appended: result.appended, eventId: result.event.id };
-}
-export function ignoreQueueRow(service, queueId, opts = {}) {
-    return setQueueRowStatus(service, queueId, 'ignored', opts);
-}
-export function supersedeQueueRow(service, queueId, supersededBy, opts = {}) {
-    return setQueueRowStatus(service, queueId, 'superseded', { ...opts, supersededBy });
-}
-export function poisonQueueRow(service, queueId, opts = {}) {
-    return setQueueRowStatus(service, queueId, 'poisoned', opts);
-}
-/** Commit all rows currently `queued`, in deterministic provider-time order; stamps committed. */
-export function commitPendingQueue(service, opts = {}) {
-    const pending = pendingQueueRows(service, opts.root)
-        .sort((a, b) => a.event.occurredAt.localeCompare(b.event.occurredAt) || a.receivedAt.localeCompare(b.receivedAt) || a.id.localeCompare(b.id));
-    const eventIds = [];
-    for (const row of pending) {
-        const { eventId } = commitQueueRow(service, row.id, opts);
-        if (eventId)
-            eventIds.push(eventId);
-    }
-    return { committed: eventIds.length, eventIds };
-}

package/dist/src/reconcile.d.ts

@@ -1,58 +0,0 @@
-import type { TwinResource } from './serve.js';
-export type ReconcilePolicy = 'hub-wins' | 'twin-wins' | 'merge';
-export type FieldDecision = {
-    field: string;
-    base: unknown;
-    fork: unknown;
-    real: unknown;
-    forkChanged: boolean;
-    realChanged: boolean;
-    resolution: 'unchanged' | 'take-fork' | 'take-real' | 'conflict';
-    value: unknown;
-};
-export type SubjectReconcile = {
-    id: string;
-    type: string;
-    inFork: boolean;
-    inReal: boolean;
-    existence: 'both' | 'fork-only' | 'real-only';
-    fields: FieldDecision[];
-    conflicts: FieldDecision[];
-};
-export type ReconcilePlan = {
-    policy: ReconcilePolicy;
-    subjects: SubjectReconcile[];
-    toPush: Array<{
-        id: string;
-        type: string;
-        fields: Record<string, unknown>;
-    }>;
-    toPull: Array<{
-        id: string;
-        type: string;
-        fields: Record<string, unknown>;
-    }>;
-    conflictCount: number;
-};
-/**
- * Compute a three-way reconciliation plan. Inputs are resource snapshots keyed
- * by id (base = at fork time, fork = twin now, real = fresh pull). Pure.
- */
-export declare function reconcile(opts: {
-    policy: ReconcilePolicy;
-    base: TwinResource[];
-    fork: TwinResource[];
-    real: TwinResource[];
-}): ReconcilePlan;
-/** True when the plan can be enacted without a human decision. */
-export declare function isCleanlyReconcilable(plan: ReconcilePlan): boolean;
-/**
- * Whether enacting this plan's `toPush` requires explicit approval before
- * `syncPush` may perform it. Nothing pushed → nothing to gate. Otherwise: any
- * unresolved conflict anywhere in the plan requires approval (never silently
- * applied), and so does any pushed field whose resolution is 'take-fork' while
- * `realChanged` is true — twin-wins discarding a change that also happened on the
- * real side, the "destructive twin-wins reconcile push" case that must not go out
- * silently.
- */
-export declare function reconcileRequiresApproval(plan: ReconcilePlan): boolean;

package/dist/src/reconcile.js

@@ -1,137 +0,0 @@
-const META_FIELDS = new Set(['id', 'type', 'updatedAt']);
-function eq(a, b) {
-    return JSON.stringify(a) === JSON.stringify(b);
-}
-function dataFields(r) {
-    if (!r)
-        return {};
-    const out = {};
-    for (const [k, v] of Object.entries(r))
-        if (!META_FIELDS.has(k))
-            out[k] = v;
-    return out;
-}
-function decideField(field, base, fork, real, policy) {
-    const forkChanged = !eq(base, fork);
-    const realChanged = !eq(base, real);
-    let resolution;
-    let value;
-    if (!forkChanged && !realChanged) {
-        resolution = 'unchanged';
-        value = base;
-    }
-    else if (forkChanged && !realChanged) {
-        // only the twin changed it
-        resolution = policy === 'hub-wins' ? 'take-real' : 'take-fork';
-        value = resolution === 'take-fork' ? fork : real;
-    }
-    else if (!forkChanged && realChanged) {
-        // only the real service changed it
-        resolution = policy === 'twin-wins' ? 'take-fork' : 'take-real';
-        value = resolution === 'take-fork' ? fork : real;
-    }
-    else {
-        // BOTH changed (relative to base) — the genuine conflict case
-        if (eq(fork, real)) {
-            resolution = 'take-fork'; // converged independently to the same value
-            value = fork;
-        }
-        else if (policy === 'hub-wins') {
-            resolution = 'take-real';
-            value = real;
-        }
-        else if (policy === 'twin-wins') {
-            resolution = 'take-fork';
-            value = fork;
-        }
-        else {
-            resolution = 'conflict'; // merge policy surfaces it; no silent pick
-            value = real; // safe default: do NOT overwrite real on an unresolved conflict
-        }
-    }
-    return { field, base, fork, real, forkChanged, realChanged, resolution, value };
-}
-/**
- * Compute a three-way reconciliation plan. Inputs are resource snapshots keyed
- * by id (base = at fork time, fork = twin now, real = fresh pull). Pure.
- */
-export function reconcile(opts) {
-    const { policy } = opts;
-    const baseById = new Map(opts.base.map((r) => [r.id, r]));
-    const forkById = new Map(opts.fork.map((r) => [r.id, r]));
-    const realById = new Map(opts.real.map((r) => [r.id, r]));
-    const allIds = [...new Set([...forkById.keys(), ...realById.keys()])].sort();
-    const subjects = [];
-    const toPush = [];
-    const toPull = [];
-    let conflictCount = 0;
-    for (const id of allIds) {
-        const baseR = baseById.get(id);
-        const forkR = forkById.get(id);
-        const realR = realById.get(id);
-        const inFork = !!forkR;
-        const inReal = !!realR;
-        const existence = inFork && inReal ? 'both' : inFork ? 'fork-only' : 'real-only';
-        const type = (forkR?.type ?? realR?.type ?? baseR?.type ?? 'unknown');
-        const baseF = dataFields(baseR);
-        const forkF = dataFields(forkR);
-        const realF = dataFields(realR);
-        const fieldNames = [...new Set([...Object.keys(baseF), ...Object.keys(forkF), ...Object.keys(realF)])].sort();
-        const fields = fieldNames.map((f) => decideField(f, baseF[f], forkF[f], realF[f], policy));
-        const conflicts = fields.filter((d) => d.resolution === 'conflict');
-        conflictCount += conflicts.length;
-        subjects.push({ id, type, inFork, inReal, existence, fields, conflicts });
-        // Enactment summaries (gated; not applied here):
-        const pushFields = {};
-        const pullFields = {};
-        if (existence === 'both') {
-            // field-level convergence only makes sense when the subject is on both sides:
-            // - fields resolved 'take-fork' that differ from real → push to real.
-            // - fields resolved 'take-real' that differ from fork → pull into twin.
-            for (const d of fields) {
-                if (d.resolution === 'take-fork' && !eq(d.value, d.real))
-                    pushFields[d.field] = d.value;
-                if (d.resolution === 'take-real' && !eq(d.value, d.fork))
-                    pullFields[d.field] = d.value;
-            }
-        }
-        else if (existence === 'fork-only') {
-            // present in the twin, absent in real. Under twin-wins/merge that's a
-            // create-on-real candidate; under hub-wins (real authoritative) the fork's
-            // creation is discarded — neither pushed nor pulled.
-            if (policy !== 'hub-wins')
-                for (const [k, v] of Object.entries(forkF))
-                    pushFields[k] = v;
-        }
-        else {
-            // real-only: a create-in-twin candidate (pull) under every policy.
-            for (const [k, v] of Object.entries(realF))
-                pullFields[k] = v;
-        }
-        if (Object.keys(pushFields).length > 0)
-            toPush.push({ id, type, fields: pushFields });
-        if (Object.keys(pullFields).length > 0)
-            toPull.push({ id, type, fields: pullFields });
-    }
-    return { policy, subjects, toPush, toPull, conflictCount };
-}
-/** True when the plan can be enacted without a human decision. */
-export function isCleanlyReconcilable(plan) {
-    return plan.conflictCount === 0;
-}
-/**
- * Whether enacting this plan's `toPush` requires explicit approval before
- * `syncPush` may perform it. Nothing pushed → nothing to gate. Otherwise: any
- * unresolved conflict anywhere in the plan requires approval (never silently
- * applied), and so does any pushed field whose resolution is 'take-fork' while
- * `realChanged` is true — twin-wins discarding a change that also happened on the
- * real side, the "destructive twin-wins reconcile push" case that must not go out
- * silently.
- */
-export function reconcileRequiresApproval(plan) {
-    if (plan.toPush.length === 0)
-        return false;
-    if (plan.conflictCount > 0)
-        return true;
-    return plan.subjects.some((s) => s.fields.some((f) => f.resolution === 'take-fork' && f.realChanged));
-}

package/dist/src/refs.d.ts

@@ -1,29 +0,0 @@
-export type WorldRemoteRef = {
-    service: string;
-    provider: string;
-    /** "main" by default; a named checkpoint otherwise. */
-    name: string;
-    eventId?: string;
-    cursor?: string;
-    providerVersion?: string;
-    observedAt: string;
-};
-export type WorldLocalRef = {
-    service: string;
-    /** the fork this ref belongs to. */
-    forkId: string;
-    /** the remote ref the fork is based on (provider + name + checkpoint). */
-    baseRemoteRef: WorldRemoteRef;
-    recordedAt: string;
-};
-/** Record/advance a provider checkpoint (e.g. after a confirmed pull). */
-export declare function writeRemoteRef(ref: WorldRemoteRef, root?: string): WorldRemoteRef;
-export declare function readRemoteRef(service: string, provider: string, name?: string, root?: string): WorldRemoteRef | null;
-export declare function listRemoteRefs(service: string, root?: string): WorldRemoteRef[];
-export declare function writeLocalRef(ref: WorldLocalRef, root?: string): WorldLocalRef;
-export declare function readLocalRef(service: string, forkId: string, root?: string): WorldLocalRef | null;
-/**
- * Is a fork's base ref still current against the live remote ref? A push against a
- * stale base must be blocked or explicitly reconciled (rebase) first.
- */
-export declare function isBaseStale(local: WorldLocalRef, root?: string): boolean;

package/dist/src/refs.js

@@ -1,68 +0,0 @@
-// Remote refs (the twins architecture notes → "Remote Refs"): the provider-side
-// baselines a fork or push is based on. `remote/<provider>/<name>` records the last
-// CONFIRMED provider checkpoint (cursor/version/event id/observed time); a local
-// ref records which remote ref a fork was based on, so a stale-base push can be
-// rejected before any provider call. Pure file I/O over the world dir; deterministic
-// (caller supplies observedAt).
-import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { readJsonFile, worldPaths } from "./storage.js";
-function refsDir(service, root) {
-    return join(worldPaths(service, root).dir, 'refs');
-}
-function remoteRefPath(service, provider, name, root) {
-    return join(refsDir(service, root), 'remote', provider, `${name}.json`);
-}
-function localRefPath(service, forkId, root) {
-    return join(refsDir(service, root), 'local', `${forkId}.json`);
-}
-function safe(part) {
-    if (!/^[A-Za-z0-9_.-]+$/.test(part))
-        throw new Error(`invalid ref segment: ${part}`);
-    return part;
-}
-/** Record/advance a provider checkpoint (e.g. after a confirmed pull). */
-export function writeRemoteRef(ref, root) {
-    const path = remoteRefPath(ref.service, safe(ref.provider), safe(ref.name), root);
-    mkdirSync(join(path, '..'), { recursive: true });
-    writeFileSync(path, `${JSON.stringify(ref, null, 2)}\n`);
-    return ref;
-}
-export function readRemoteRef(service, provider, name = 'main', root) {
-    const path = remoteRefPath(service, safe(provider), safe(name), root);
-    return existsSync(path) ? readJsonFile(path) : null;
-}
-export function listRemoteRefs(service, root) {
-    const base = join(refsDir(service, root), 'remote');
-    if (!existsSync(base))
-        return [];
-    const out = [];
-    for (const provider of readdirSync(base)) {
-        const providerDir = join(base, provider);
-        for (const file of readdirSync(providerDir)) {
-            if (file.endsWith('.json'))
-                out.push(readJsonFile(join(providerDir, file)));
-        }
-    }
-    return out.sort((a, b) => (a.provider === b.provider ? a.name.localeCompare(b.name) : a.provider.localeCompare(b.provider)));
-}
-export function writeLocalRef(ref, root) {
-    const path = localRefPath(ref.service, safe(ref.forkId), root);
-    mkdirSync(join(path, '..'), { recursive: true });
-    writeFileSync(path, `${JSON.stringify(ref, null, 2)}\n`);
-    return ref;
-}
-export function readLocalRef(service, forkId, root) {
-    const path = localRefPath(service, safe(forkId), root);
-    return existsSync(path) ? readJsonFile(path) : null;
-}
-/**
- * Is a fork's base ref still current against the live remote ref? A push against a
- * stale base must be blocked or explicitly reconciled (rebase) first.
- */
-export function isBaseStale(local, root) {
-    const current = readRemoteRef(local.service, local.baseRemoteRef.provider, local.baseRemoteRef.name, root);
-    if (!current)
-        return false; // no live checkpoint recorded yet → cannot be stale
-    return (current.eventId ?? current.cursor ?? '') !== (local.baseRemoteRef.eventId ?? local.baseRemoteRef.cursor ?? '');
-}

package/dist/src/schemas.d.ts

@@ -1,78 +0,0 @@
-import { z } from 'zod';
-export declare const WorldActorSchema: z.ZodObject<{
-    id: z.ZodOptional<z.ZodString>;
-    name: z.ZodOptional<z.ZodString>;
-    kind: z.ZodEnum<{
-        human: "human";
-        agent: "agent";
-        bot: "bot";
-        system: "system";
-    }>;
-}, z.core.$strip>;
-export declare const WorldSubjectSchema: z.ZodObject<{
-    type: z.ZodString;
-    id: z.ZodString;
-}, z.core.$strip>;
-export declare const WorldExternalRefSchema: z.ZodObject<{
-    provider: z.ZodString;
-    id: z.ZodOptional<z.ZodString>;
-    url: z.ZodOptional<z.ZodString>;
-    cursor: z.ZodOptional<z.ZodString>;
-    rawRef: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-export declare const WorldServiceEventSchema: z.ZodObject<{
-    id: z.ZodString;
-    service: z.ZodString;
-    type: z.ZodString;
-    schemaVersion: z.ZodNumber;
-    idempotencyKey: z.ZodString;
-    occurredAt: z.ZodString;
-    observedAt: z.ZodString;
-    origin: z.ZodEnum<{
-        agent: "agent";
-        virtual: "virtual";
-        external: "external";
-        connector: "connector";
-        replay: "replay";
-        migration: "migration";
-    }>;
-    actor: z.ZodOptional<z.ZodObject<{
-        id: z.ZodOptional<z.ZodString>;
-        name: z.ZodOptional<z.ZodString>;
-        kind: z.ZodEnum<{
-            human: "human";
-            agent: "agent";
-            bot: "bot";
-            system: "system";
-        }>;
-    }, z.core.$strip>>;
-    subject: z.ZodObject<{
-        type: z.ZodString;
-        id: z.ZodString;
-    }, z.core.$strip>;
-    causationId: z.ZodOptional<z.ZodString>;
-    correlationId: z.ZodOptional<z.ZodString>;
-    external: z.ZodOptional<z.ZodObject<{
-        provider: z.ZodString;
-        id: z.ZodOptional<z.ZodString>;
-        url: z.ZodOptional<z.ZodString>;
-        cursor: z.ZodOptional<z.ZodString>;
-        rawRef: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>;
-    data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-    raw: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, z.core.$strip>;
-export declare const GenericWorldStateSchema: z.ZodObject<{
-    version: z.ZodLiteral<1>;
-    service: z.ZodString;
-    rebuiltAt: z.ZodString;
-    eventCount: z.ZodNumber;
-    latestEventId: z.ZodOptional<z.ZodString>;
-    subjects: z.ZodRecord<z.ZodString, z.ZodObject<{
-        type: z.ZodString;
-        id: z.ZodString;
-        latestEventId: z.ZodString;
-        latestType: z.ZodString;
-        updatedAt: z.ZodString;
-    }, z.core.$strip>>;
-}, z.core.$strip>;

package/dist/src/schemas.js

@@ -1,50 +0,0 @@
-import { z } from 'zod';
-export const WorldActorSchema = z.object({
-    id: z.string().min(1).optional(),
-    name: z.string().min(1).optional(),
-    kind: z.enum(['human', 'agent', 'bot', 'system']),
-});
-export const WorldSubjectSchema = z.object({
-    type: z.string().min(1),
-    id: z.string().min(1),
-});
-export const WorldExternalRefSchema = z.object({
-    provider: z.string().min(1),
-    id: z.string().min(1).optional(),
-    url: z.string().min(1).optional(),
-    cursor: z.string().min(1).optional(),
-    rawRef: z.string().min(1).optional(),
-});
-export const WorldServiceEventSchema = z.object({
-    id: z.string().min(1),
-    service: z.string().min(1),
-    type: z.string().min(1),
-    schemaVersion: z.number().int().positive(),
-    idempotencyKey: z.string().min(1),
-    occurredAt: z.string().min(1),
-    observedAt: z.string().min(1),
-    origin: z.enum(['virtual', 'external', 'agent', 'connector', 'replay', 'migration']),
-    actor: WorldActorSchema.optional(),
-    subject: WorldSubjectSchema,
-    causationId: z.string().min(1).optional(),
-    correlationId: z.string().min(1).optional(),
-    external: WorldExternalRefSchema.optional(),
-    data: z.record(z.string(), z.unknown()),
-    raw: z.record(z.string(), z.unknown()).optional(),
-});
-// NOTE: WorldAnnotationSchema moved to @volter/tracker/world-annotations — annotating
-// world events as sources/noise is a tracker (verification) concern, not the twin's.
-export const GenericWorldStateSchema = z.object({
-    version: z.literal(1),
-    service: z.string().min(1),
-    rebuiltAt: z.string().min(1),
-    eventCount: z.number().int().nonnegative(),
-    latestEventId: z.string().min(1).optional(),
-    subjects: z.record(z.string(), z.object({
-        type: z.string().min(1),
-        id: z.string().min(1),
-        latestEventId: z.string().min(1),
-        latestType: z.string().min(1),
-        updatedAt: z.string().min(1),
-    })),
-});

package/dist/src/serve.d.ts

@@ -1,44 +0,0 @@
-import type { SubjectFields } from './shadow.js';
-import type { TwinActionPrecondition } from './actions.js';
-export type TwinResource = {
-    id: string;
-    type: string;
-    updatedAt: string;
-} & Record<string, unknown>;
-export declare function twinResources(service: string, root?: string): TwinResource[];
-export type TwinWriteResult = {
-    status: 'performed' | 'replayed';
-    actionId: string;
-};
-export declare function resolveTwinRead(service: string, pathname: string, opts?: {
-    root?: string;
-}): {
-    status: number;
-    body: unknown;
-};
-export declare function applyTwinWrite(service: string, write: {
-    operation: string;
-    provider?: string;
-    subjectType: string;
-    subjectId: string;
-    fields: SubjectFields;
-    occurredAt?: string;
-    actor?: {
-        kind: 'agent' | 'human' | 'bot' | 'system';
-        id?: string;
-    };
-    preconditions?: TwinActionPrecondition[];
-    correlationId?: string;
-}, root?: string): Promise<{
-    result: TwinWriteResult;
-    resource: TwinResource;
-}>;
-export declare function createTwinServer(options: {
-    service: string;
-    root?: string;
-    port?: number;
-    readOnly?: boolean;
-}): {
-    port: number;
-    stop: () => void;
-};