@volter/twin 0.1.0

package/dist/src/queueLifecycle.js

@@ -0,0 +1,95 @@
+// 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

@@ -0,0 +1,58 @@
+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

@@ -0,0 +1,137 @@
+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

@@ -0,0 +1,29 @@
+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

@@ -0,0 +1,68 @@
+// 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

@@ -0,0 +1,78 @@
+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

@@ -0,0 +1,50 @@
+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

@@ -0,0 +1,44 @@
+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;
+};

package/dist/src/serve.js

@@ -0,0 +1,93 @@
+import { hashFieldValue } from "./shadow.js";
+import { appendActionIfAbsent, projectResources } from "./actions.js";
+// The twin's current view = the OBSERVED mirror (events.jsonl) with the local
+// ACTION log (actions.jsonl) projected over it (R18). Observed facts and local
+// actions are kept separate; this is the single projected read model.
+export function twinResources(service, root) {
+    return projectResources(service, root);
+}
+// Resolve a read request against the twin's resources. Returns the matched
+// resource(s) + an HTTP-ish status, deterministically from state.
+//   GET /                       -> { service, mode, resourceTypes, count }
+//   GET /<type>                 -> list of resources of that type
+//   GET /<type>/<id>            -> one resource (id may be url-encoded)
+export function resolveTwinRead(service, pathname, opts = {}) {
+    const resources = twinResources(service, opts.root);
+    const parts = pathname.replace(/^\/+|\/+$/g, '').split('/').filter(Boolean);
+    if (parts.length === 0) {
+        const types = [...new Set(resources.map((r) => r.type))].sort();
+        return { status: 200, body: { service, resourceTypes: types, count: resources.length } };
+    }
+    const type = parts[0];
+    const ofType = resources.filter((r) => r.type === type);
+    if (parts.length === 1) {
+        return { status: 200, body: { type, count: ofType.length, items: ofType } };
+    }
+    const id = decodeURIComponent(parts.slice(1).join('/'));
+    const found = ofType.find((r) => r.id === id);
+    if (!found)
+        return { status: 404, body: { error: 'not_found', type, id } };
+    return { status: 200, body: found };
+}
+// Simulator/fork-mode write: the twin ACCEPTS a write as a LOCAL ACTION appended
+// to the action log (R18) — NOT an observed event and NOT an egress/real write.
+// State is the mirror with this action projected over it, so a subsequent read
+// returns the change. The observed event log is untouched; the real service is
+// provably untouched (no network I/O, no egress). Pushing the action to the real
+// vendor is a separate, explicit step that records egress + confirms the action.
+export async function applyTwinWrite(service, write, root) {
+    const occurredAt = write.occurredAt ?? new Date().toISOString();
+    // Idempotency: dedup a RE-ISSUED IDENTICAL write only. The key includes a hash of the write
+    // CONTENT (operation + subject + fields), not just the timestamp — so two DIFFERENT writes to
+    // the same subject in the same millisecond are BOTH kept (previously the second silently
+    // no-opped: e.g. a sprint "start" then "close" in the same ms lost the close). Check + append
+    // run atomically under the actions lock, so concurrent processes can't double-apply either.
+    const contentHash = hashFieldValue({ operation: write.operation, subjectId: write.subjectId, fields: write.fields });
+    const actionId = `twin:${service}:${write.operation}:${write.subjectId}:${occurredAt}:${contentHash}`;
+    // correlationId (D3): pass a caller-supplied request-scoped id through (e.g. propagated
+    // from an inbound HTTP request id) so it lands on the action row; appendActionIfAbsent
+    // generates one when omitted, so it's never missing.
+    const { appended } = appendActionIfAbsent({ id: actionId, service, op: 'set', operation: write.operation, subject: { type: write.subjectType, id: write.subjectId }, occurredAt, ...(write.actor ? { actor: write.actor } : {}), ...(write.preconditions?.length ? { preconditions: write.preconditions } : {}), ...(write.correlationId ? { correlationId: write.correlationId } : {}), fields: write.fields }, root);
+    // Resolve by (type, id) — an id alone is ambiguous when two resource TYPES share it.
+    const resource = projectResources(service, root).find((r) => r.type === write.subjectType && r.id === write.subjectId)
+        ?? { id: write.subjectId, type: write.subjectType, updatedAt: occurredAt, ...write.fields };
+    return { result: { status: appended ? 'performed' : 'replayed', actionId }, resource };
+}
+export function createTwinServer(options) {
+    const readOnly = options.readOnly ?? false;
+    const server = Bun.serve({
+        port: options.port ?? 0,
+        idleTimeout: 60,
+        async fetch(request) {
+            const url = new URL(request.url);
+            const json = (status, body) => new Response(JSON.stringify(body, null, 2), { status, headers: { 'content-type': 'application/json' } });
+            if (request.method === 'GET') {
+                // Re-read per request so a concurrently-syncing twin serves fresh state.
+                const { status, body } = resolveTwinRead(options.service, url.pathname, { root: options.root });
+                return json(status, body);
+            }
+            // Writes are accepted as local actions unless this twin was started read-only.
+            if (readOnly)
+                return json(405, { error: 'read_only', hint: 'this twin was started read-only; omit readOnly to accept writes' });
+            const parts = url.pathname.replace(/^\/+|\/+$/g, '').split('/').filter(Boolean);
+            if (parts.length < 2)
+                return json(400, { error: 'write_needs_type_and_id', hint: 'POST /<type>/<id> with a JSON body of fields' });
+            let fields;
+            try {
+                fields = (await request.json());
+            }
+            catch {
+                return json(400, { error: 'invalid_json_body' });
+            }
+            const { result, resource } = await applyTwinWrite(options.service, {
+                operation: `${request.method.toLowerCase()}.${parts[0]}`,
+                subjectType: parts[0],
+                subjectId: decodeURIComponent(parts.slice(1).join('/')),
+                fields,
+                actor: { kind: 'agent' },
+            }, options.root);
+            return json(result.status === 'replayed' ? 200 : 201, { status: result.status, resource });
+        },
+    });
+    return { port: server.port ?? 0, stop: () => server.stop(true) };
+}