@volter/world-core 2.0.0

package/dist/src/actions.js

@@ -0,0 +1,436 @@
+// Transaction/action log (scorecard R18) — the semantic correction that separates
+// OBSERVED facts from LOCAL transaction commits.
+//
+// The observed-event log (`events.jsonl`) holds only what was observed upstream
+// (connector pulls) or confirmed after a push. Local simulator/fork writes do NOT
+// go there — they are transaction commits in `actions.jsonl`, projected OVER the
+// observed mirror to produce the twin's current state. Undo is a `revert` commit;
+// a push that succeeds appends a `confirm` commit mapping the local transaction
+// to the observed event it produced, which SUPPRESSES the local projection (the
+// fact is now carried by the observed log, so it must not be double-counted).
+//
+// Projection = observed mirror, then apply each `set` transaction in order,
+// skipping any transaction that was reverted or confirmed.
+import { withAncestryLock } from "./ancestry.js";
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { canonicalJson, subjectKey } from "./hash.js";
+import { appendDurable, eventsLockPath, projectionLockPath, twinLog, withFileLock, worldPaths } from "./storage.js";
+import { landAsPlaceholder, placeholderPullActive } from "./placeholder-remote.js";
+import { aliasesFrom, dropCheckpoint, landedCopy, landedIds, parentEntries, readTree } from "./log.js";
+import { getActiveWorldStore } from "./world-store.js";
+export class TwinActionPreconditionError extends Error {
+    actionId;
+    failed;
+    constructor(actionId, failed) {
+        super(`Twin transaction precondition failed for ${actionId}: ${failed.subject.type}:${failed.subject.id}.${failed.field} ${failed.op}`);
+        this.actionId = actionId;
+        this.failed = failed;
+        this.name = 'TwinActionPreconditionError';
+    }
+}
+function actionsPath(service, root) {
+    return join(dirname(worldPaths(service, root).events), 'actions.jsonl');
+}
+const actionsLock = (service, root) => `${actionsPath(service, root)}.lock`;
+const projectionLock = (service, root) => projectionLockPath(worldPaths(service, root));
+/** Every appended action carries a correlationId — generate one when the caller
+ *  hasn't supplied it, so downstream joins (push ledger, logs) always have an id
+ *  to key on (D3). Preserves a caller-supplied id (e.g. propagated from an HTTP
+ *  request id) so a whole call chain can share one. */
+function withCorrelationId(action) {
+    // The wire's request id (the addressed service stamps every response with one and threads it
+    // into the handler's async context) is the correlation when the caller supplies none — the
+    // join from a request on the wire to the action rows it caused, with no pack involved.
+    return action.correlationId ? action : { ...action, correlationId: currentCorrelationId() ?? randomUUID() };
+}
+/** Subjects a `set` action touches: its own subject, every projection resource, and every
+ *  precondition subject — a precondition established the action's validity against that
+ *  subject's state, so remote movement there is drift for this action too. */
+export function touchedSubjects(action) {
+    const out = new Map();
+    out.set(subjectKey(action.subject), action.subject);
+    for (const r of [
+        ...(action.projection?.creates ?? []),
+        ...(action.projection?.updates ?? []),
+        ...(action.projection?.deletes ?? []),
+    ])
+        out.set(subjectKey(r), { type: r.type, id: r.id });
+    for (const p of action.preconditions ?? [])
+        out.set(subjectKey(p.subject), p.subject);
+    return [...out.values()];
+}
+const idMemos = new WeakMap();
+function logKey(path) { const s = getActiveWorldStore().stat(path); return s ? `${s.size}:${s.mtimeMs}` : '-'; }
+function idMemoSlot(path) {
+    const store = getActiveWorldStore();
+    let memos = idMemos.get(store);
+    if (!memos) {
+        memos = new Map();
+        idMemos.set(store, memos);
+    }
+    return memos;
+}
+function actionIds(service, root) {
+    const path = actionsPath(service, root);
+    const memos = idMemoSlot(path);
+    const key = logKey(path);
+    const held = memos.get(path);
+    if (held && held.key === key)
+        return held.ids;
+    const ids = new Set(listActions(service, root).map((a) => a.id));
+    memos.set(path, { key, ids });
+    return ids;
+}
+function appendActionRaw(action, root) {
+    const path = actionsPath(action.service, root);
+    getActiveWorldStore().mkdir(dirname(path));
+    const memos = idMemoSlot(path);
+    const held = memos.get(path);
+    const current = held !== undefined && held.key === logKey(path);
+    withAncestryLock(() => appendDurable(path, `${JSON.stringify(action)}\n`));
+    if (current) {
+        held.ids.add(action.id);
+        held.key = logKey(path);
+    }
+    else
+        memos.delete(path);
+    twinLog('action.append', { service: action.service, id: action.id, op: action.op, correlationId: action.correlationId });
+    appendObserver?.(action, root);
+}
+/** ONE observer of appended entries (state-system.ts: the runtime's `deploy: auto` hook). Called
+ *  under the append locks, so it must only schedule work, never do it. */
+let appendObserver;
+export function observeAppends(observer) { appendObserver = observer; }
+/** The placeholder remote (contract section of that name): while a service's placeholder-pull
+ *  window is open, a `set` write is a pull, not a commit — it lands as observed events and no
+ *  action row exists. Returns the action the caller hands back (its id names what landed). */
+function landIfPlaceholderPull(action, root) {
+    if (action.op !== 'set' || !placeholderPullActive(action.service, root))
+        return null;
+    const { events } = landAsPlaceholder(action, root);
+    twinLog('action.placeholder', { service: action.service, id: action.id, op: action.op, events: events.length });
+    return { ...action, id: events.at(-1)?.id ?? action.id };
+}
+function replayBody(action) {
+    const { correlationId: _correlationId, ...stampedBody } = action;
+    // A confirmation is content-addressed by the observed event ids. Its timestamp is observation
+    // metadata, just like the occurredAt/observedAt values that appendEvent ignores when replaying
+    // one content-addressed event. Two reconcilers confirming the same bytes at different wall-clock
+    // instants must therefore converge on the first durable confirmation rather than conflict.
+    // A KEYED write is the same request however long the retry took, so its timestamp is observation
+    // metadata too — exactly as a confirmation's is. Comparing it would turn the retry the key was
+    // asked for into a hard conflict.
+    const body = stampedBody.idempotencyKey !== undefined
+        ? (({ occurredAt: _occurredAt, ...rest }) => rest)(stampedBody)
+        : stampedBody;
+    return canonicalJson(body);
+}
+function existingExactAction(action, root) {
+    const existing = listActions(action.service, root).find((candidate) => candidate.id === action.id);
+    if (!existing)
+        return undefined;
+    if (replayBody(existing) !== replayBody(action)) {
+        throw new Error(`Conflicting duplicate twin action: ${action.service}/${action.id}`);
+    }
+    return existing;
+}
+/** The request-scoped correlation id (D3): set by the kernel fetch adapter for the duration of one
+ *  handler call from the wire's `x-twins-request-id`; read by appendAction as the default. */
+// created on first use, never at import: a browser bundle of a mirror client carries this module and has
+// no AsyncLocalStorage (see serve.ts identitySlot)
+let correlationStore;
+const correlationScope = () => (correlationStore ??= new AsyncLocalStorage());
+export function runWithCorrelationId(id, fn) { return correlationScope().run(id, fn); }
+export function currentCorrelationId() { return correlationScope().getStore(); }
+export function appendAction(action, root) {
+    // Evaluate and append under the service projection and actions locks. A precondition is a
+    // compare-and-set, not an advisory validation: checking outside either lock would let another
+    // writer invalidate it before this action lands. The shadow basis is stamped under the same
+    // lock so the recorded merge base is the mirror the preconditions were checked against.
+    return withFileLock(projectionLock(action.service, root), () => withFileLock(actionsLock(action.service, root), () => {
+        const stamped = withCorrelationId(action);
+        assertPreconditions(stamped, root);
+        const placeholder = landIfPlaceholderPull(stamped, root);
+        if (placeholder)
+            return placeholder;
+        appendActionRaw(stamped, root);
+        return stamped;
+    }));
+}
+/** Append `action` only if no exact action with the same id already exists — the whole
+ *  replay/precondition/append decision runs under the service projection + actions locks, so it's
+ *  atomic across processes (two concurrent identical writes converge to ONE action; distinct
+ *  writes both land). A reused id with different content fails loudly. */
+export function appendActionIfAbsent(action, root) {
+    return withFileLock(projectionLock(action.service, root), () => withFileLock(actionsLock(action.service, root), () => {
+        const identified = withCorrelationId(action);
+        // An exact retry is already committed. Resolve it before re-evaluating author-time
+        // preconditions against the state that first commit intentionally changed — and
+        // before paying the basis stamp's event-log read (the replayed path stays cheap).
+        const existing = existingExactAction(identified, root);
+        if (existing)
+            return { action: existing, appended: false };
+        const stamped = identified;
+        assertPreconditions(stamped, root);
+        const placeholder = landIfPlaceholderPull(stamped, root);
+        if (placeholder)
+            return { action: placeholder, appended: true, placeholder: true };
+        appendActionRaw(stamped, root);
+        return { action: stamped, appended: true };
+    }));
+}
+/**
+ * Append `build(n)` as an OCCURRENCE: the nth time this exact write has been made.
+ *
+ * A local vendor write is an occurrence, not a replay — two calls are two actions, even
+ * byte-identical in the same instant (docs/contributing/adding-a-twin.md#5-build-on-the-shared-kernel--dont-reinvent,
+ * "A local write is an occurrence"). `appendActionIfAbsent` cannot express that: its identity is content, and
+ * content provably cannot separate "the same request delivered twice" from "the same change made
+ * twice". So a caller wanting at-most-once passes an explicit key and uses that function; a caller
+ * recording what actually happened uses this one.
+ *
+ * The ordinal keeps every EXISTING action id byte-identical: occurrence 0 is `build(0)`'s own id,
+ * and only a genuine repeat becomes `<id>#1`, `#2`. It is derived under the same projection +
+ * actions locks as the append, so two processes racing take different ordinals rather than
+ * colliding, and it is deterministic — replaying one sequence of writes onto a fresh root yields
+ * the same ordinals, which is what serve-path determinism requires.
+ */
+export function appendActionOccurrence(base, root) {
+    return withFileLock(projectionLock(base.service, root), () => withFileLock(actionsLock(base.service, root), () => {
+        const stamped = occurrenceOf(base, actionIds(base.service, root), root);
+        assertPreconditions(stamped, root);
+        const placeholder = landIfPlaceholderPull(stamped, root);
+        if (placeholder)
+            return { action: placeholder, appended: true, placeholder: true };
+        appendActionRaw(stamped, root);
+        return { action: stamped, appended: true };
+    }));
+}
+/** The occurrence rule, shared by both appenders that use it — the ordinal AND the merge base.
+ *  Pure over (base, the log as it stands): the caller holds the lock. */
+function occurrenceOf(base, taken, root) {
+    {
+        let ordinal = 0;
+        while (taken.has(occurrenceId(base.id, ordinal)))
+            ordinal += 1;
+        // an occurrence past the first is its own entry: the tree it changes is read at the head, and a
+        // push onto a moved parent is refused by position, not by a basis stamped here (v2)
+        return withCorrelationId({ ...base, id: occurrenceId(base.id, ordinal) });
+    }
+}
+/** Occurrence 0 IS the base id — so nothing that exists today changes shape. The appender owns
+ *  this math; a caller passing an already-ordinalled id would stack them (`…#1#1`). */
+export function occurrenceId(base, ordinal) {
+    return ordinal === 0 ? base : `${base}#${ordinal}`;
+}
+/**
+ * Evaluate current projected state and optionally append one action under ONE service projection
+ * transaction (the shared projection lock plus the action-log lock). This is the narrow
+ * state-dependent seam for vendor operations whose acceptance and resulting fields depend on the
+ * latest observed + local projection (for example, immutable version publish).
+ *
+ * The callback must remain synchronous and side-effect free: it computes a decision from the
+ * supplied snapshot. Durable state changes only through the returned action, which this helper
+ * appends before releasing the lock.
+ */
+export function decideAndAppendAction(service, decide, root) {
+    return withFileLock(projectionLock(service, root), () => withFileLock(actionsLock(service, root), () => {
+        const resources = projectResources(service, root);
+        const decision = decide(resources);
+        if (decision.kind === 'skip')
+            return { value: decision.value, appended: false };
+        if (decision.action.service !== service) {
+            throw new Error(`Atomic action service mismatch: expected ${service}, got ${decision.action.service}`);
+        }
+        const identified = withCorrelationId(decision.action);
+        // This seam was left on content-dedupe when the occurrence ruling first landed, and 21 packs
+        // write through it — so they kept losing a write that returned a subject to a value it held
+        // one instant earlier, which is the whole defect.
+        if (decision.identity === 'caller') {
+            const existing = existingExactAction(identified, root);
+            if (existing)
+                return { value: decision.value, action: existing, appended: false };
+            const stamped = identified;
+            assertPreconditionsAgainst(stamped, resources);
+            const placeholder = landIfPlaceholderPull(stamped, root);
+            if (placeholder)
+                return { value: decision.value, action: placeholder, appended: true, placeholder: true };
+            appendActionRaw(stamped, root);
+            return { value: decision.value, action: stamped, appended: true };
+        }
+        const stamped = occurrenceOf(decision.action, actionIds(service, root), root);
+        assertPreconditionsAgainst(stamped, resources);
+        const placeholder = landIfPlaceholderPull(stamped, root);
+        if (placeholder)
+            return { value: decision.value, action: placeholder, appended: true, placeholder: true };
+        appendActionRaw(stamped, root);
+        return { value: decision.value, action: stamped, appended: true };
+    }));
+}
+export function appendTransactionCommit(commit, root) {
+    return appendAction(commit, root);
+}
+export function listActions(service, root) {
+    const path = actionsPath(service, root);
+    return getActiveWorldStore()
+        .readLines(path)
+        .filter((line) => line.trim())
+        .map((line) => JSON.parse(line));
+}
+const META = new Set(['id', 'type', 'updatedAt']);
+function projectedField(resource, field) {
+    if (!resource)
+        return undefined;
+    if (field === 'id' || field === 'type' || field === 'updatedAt')
+        return resource[field];
+    return resource[field];
+}
+/** The kernel's ONE deterministic check: does `actual` satisfy the precondition expression?
+ *  Shared by write-time preconditions (here), plan conflict detection (plan.ts) and changeset
+ *  verifiers (changeset.ts) — one evaluator, so a check means the same thing everywhere. */
+export function checkPrecondition(precondition, actual) {
+    switch (precondition.op) {
+        case 'exists': return actual !== undefined;
+        case 'not_exists': return actual === undefined;
+        case 'eq':
+        case 'version_eq': return Object.is(actual, precondition.value);
+        case 'neq': return !Object.is(actual, precondition.value);
+        default: return false;
+    }
+}
+/** Look a precondition subject's field up in projected resources (undefined = no resource or
+ *  no field — exactly what `exists`/`not_exists` distinguish). */
+export function projectedPreconditionValue(precondition, resources) {
+    const resource = resources.find((r) => r.type === precondition.subject.type && r.id === precondition.subject.id);
+    return projectedField(resource, precondition.field);
+}
+function assertPreconditionsAgainst(action, resources) {
+    if (!action.preconditions?.length)
+        return;
+    for (const precondition of action.preconditions) {
+        const actual = projectedPreconditionValue(precondition, resources);
+        if (!checkPrecondition(precondition, actual))
+            throw new TwinActionPreconditionError(action.id, precondition);
+    }
+}
+function assertPreconditions(action, root) {
+    // Most writes carry none: projecting (and cloning) the whole tree to check nothing cost every append O(tree).
+    if (!action.preconditions?.length)
+        return;
+    assertPreconditionsAgainst(action, projectResources(action.service, root));
+}
+/**
+ * Project the action log over the observed mirror → current twin resources.
+ * `set` actions overlay fields (creating subjects that don't exist in the mirror);
+ * reverted and confirmed actions are skipped (confirmed facts come from the
+ * observed log instead, so they are not projected twice).
+ */
+/** THE TREE (log.ts): what a read sees — the nearest checkpoint plus the entries since; the parent's
+ *  entries, then this branch's, skipping any the parent already holds. `until` folds only the
+ *  branch entries BEFORE that id — the state a write saw at its own append (the rebase's
+ *  evaluation point). */
+export function projectResources(service, root, opts = {}) {
+    return readTree(service, root, opts);
+}
+/** The local → vendor id aliases the landed copies carry: a read by the id a caller was handed before
+ *  its write was performed resolves to the row the vendor now owns. */
+export function subjectAliases(service, root) {
+    const out = new Map();
+    for (const [from, to] of aliasesFrom(parentEntries(service, root)))
+        out.set(from, to);
+    return out;
+}
+/** Resolve a subject id through the aliases: the vendor's id when a confirm rebound it, else the id itself. */
+export function resolveSubjectId(service, type, id, root) {
+    return subjectAliases(service, root).get(`${type}:${id}`) ?? id;
+}
+/**
+ * Confirm a local action after it was pushed to the real vendor (R18): record the
+ * confirmed fields as an OBSERVED event (origin 'external' — it's now real) and
+ * append a `confirm` action mapping the local action → that observed event id.
+ * Projection then drops the local action (the fact lives in the observed log), so
+ * the change is counted exactly once. Returns the observed event id.
+ */
+export function confirmAction(opts) {
+    // LANDING (log.ts): the entry is copied to the parent log with its receipt — no confirm row, no
+    // suppression; the fold skips a branch entry the parent holds.
+    const paths = worldPaths(opts.service, opts.root);
+    const base = listActions(opts.service, opts.root).find((a) => a.id === opts.actionId)
+        ?? { id: opts.actionId, service: opts.service, op: 'set', subject: opts.subject, occurredAt: opts.occurredAt };
+    const receipt = { status: 'deployed', at: opts.occurredAt, ...(opts.vendorSubjectId ? { externalId: opts.vendorSubjectId } : {}), ...(opts.receipt ?? {}) };
+    const copies = [
+        ...(opts.additionalObservations ?? []).map((o) => landedCopy(base, receipt, { subject: o.subject, fields: o.fields })),
+        landedCopy(base, receipt, { subject: opts.subject, fields: opts.fields, ...(opts.vendorSubjectId ? { vendorSubjectId: opts.vendorSubjectId } : {}) }),
+    ];
+    withFileLock(projectionLock(opts.service, opts.root), () => {
+        withAncestryLock(() => withFileLock(eventsLockPath(paths), () => {
+            const held = landedIds(parentEntries(opts.service, opts.root));
+            for (const copy of copies)
+                if (!held.has(copy.id))
+                    appendDurable(paths.events, `${JSON.stringify(copy)}\n`);
+        }));
+        dropCheckpoint(opts.service, opts.root);
+    });
+    const observedEventIds = copies.map((c) => c.id);
+    return { observedEventId: observedEventIds.at(-1), observedEventIds };
+}
+/**
+ * Revert one pending `set` action — decision AND append under the service projection +
+ * actions locks, so a concurrent writer (a connector confirming the same action from
+ * another process) cannot land between the check and the revert: the whole read-decide-
+ * append is ONE critical section. Idempotent: a repeat answers 'already-reverted'.
+ * Only `set` rows are revertable — reverting a revert or a confirm is a category error.
+ */
+export function revertAction(opts) {
+    return withFileLock(projectionLock(opts.service, opts.root), () => withFileLock(actionsLock(opts.service, opts.root), () => {
+        const all = listActions(opts.service, opts.root);
+        const target = all.find((a) => a.id === opts.actionId);
+        if (target === undefined)
+            return { status: 'not-found' };
+        if (target.op !== 'set')
+            return { status: 'not-revertable', op: target.op };
+        // landed and taken by the vendor: not revertable; a landed copy the vendor refused or failed is
+        const landedCopy = parentEntries(opts.service, opts.root).find((e) => e.id === opts.actionId || e.landsId === opts.actionId);
+        if (landedCopy && landedCopy.receipt?.status !== 'refused' && landedCopy.receipt?.status !== 'failed')
+            return { status: 'confirmed' };
+        if (all.some((a) => a.op === 'revert' && a.revertsActionId === opts.actionId))
+            return { status: 'already-reverted' };
+        const revert = withCorrelationId({
+            id: `revert:${opts.actionId}`,
+            service: opts.service,
+            op: 'revert',
+            subject: target.subject,
+            occurredAt: opts.occurredAt,
+            revertsActionId: opts.actionId,
+        });
+        appendActionRaw(revert, opts.root);
+        return { status: 'reverted', revertId: revert.id };
+    }));
+}
+/** The LOCAL OVERLAY: pending actions (set, not reverted, not yet confirmed) — the divergence
+ *  from the mirror, what a twin's projection folds over the observed state. A QUARANTINED row
+ *  (contract "A snapshot import never plants a push") is still local state and stays here; it
+ *  leaves only the PUSHABLE suffix below. */
+export function pendingActions(service, root) {
+    const actions = listActions(service, root);
+    const reverted = new Set(actions.filter((a) => a.op === 'revert').map((a) => a.revertsActionId));
+    const landed = landedIds(parentEntries(service, root));
+    return actions.filter((a) => a.op === 'set' && !reverted.has(a.id) && !landed.has(a.id));
+}
+/** A twin's OWN bookkeeping in its action log — a subject type beginning with `_` (stripe's
+ *  `_idempotency` store, for one): part of the overlay the twin serves from, never a change the
+ *  app made. It is not in the log a user reads, not in a diff, not in a changeset, not pushed. */
+export function isTwinBookkeeping(action) {
+    return action.subject.type.startsWith('_');
+}
+/** The PUSHABLE suffix — `log origin..HEAD` as the push arm, the pending door, plans and the
+ *  unpushed count read it: the overlay minus quarantined rows (an import is a copy, not a
+ *  decision; releasing a quarantined row is an explicit act, never a scheduler's) and minus the
+ *  twin's own bookkeeping. */
+export function pushablePendingActions(service, root) {
+    return pendingActions(service, root).filter((a) => a.quarantined === undefined && !isTwinBookkeeping(a));
+}
+export const listTransactionCommits = listActions;
+export const pendingTransactionCommits = pendingActions;

package/dist/src/ancestry.d.ts

@@ -0,0 +1,22 @@
+export declare const canonicalStatePath: (path: string) => string;
+/** Synchronous only; use exclusive acquisition without age-stealing a live owner.
+ * The coordinator lives outside service, instance and hosted World deletion trees. */
+export declare function withAncestryLock<T>(fn: () => T): T;
+/** Create an identity only for an existing parent. A recreated path gets a new identity. */
+export declare function stateGeneration(dir: string): string;
+/** Must be called in the same critical section as child pointer publication. A crash before
+ * publication leaves a pending pin; it can be ignored only once its writer is provably dead. */
+export declare function pinParent(parentDir: string, child: string, expected?: string): string;
+/** Mark publication complete only after branch.json exists. */
+export declare function commitParentPin(parentDir: string, child: string): void;
+/** Read-only identity validation. */
+export declare function checkParent(parentDir: string, expected?: string): void;
+/** Caller holds the coordinator through the actual deletion. A committed pin with missing
+ * child metadata is uncertainty, not permission: only explicit child removal releases it. */
+export declare function assertStateRemovable(path: string): void;
+export declare function assertNotBeingRemoved(path: string): void;
+/** force on scrub bypasses shape checking only, never another branch's ownership. The coordinator is held to decide
+ * and record the removal (`check`, the caller's own precondition, runs there too) and to release it, not through the
+ * deletion: every World on the machine shares the coordinator, and a large tree's deletion outlasts their writes'
+ * patience. The receipt, written first, keeps the path from being pinned or written while it is deleted. */
+export declare function withStateRemoval<T>(path: string, remove: () => T, check?: () => void): T;