@volter/world-core 3.0.138 → 3.0.140

package/dist/src/changeset.d.ts

@@ -1,6 +1,7 @@
 import { type HistoryReference } from './history.js';
 import type { TwinActionRevertSpec } from './actions.js';
 import type { TwinAction, TwinActionPrecondition } from './actions.js';
+import { type FieldChange } from './hash.js';
 /** One twin's action ledger, addressed the way the control plane addresses state:
  *  `worldPaths(stateService, controlRoot)`. `service` is the caller's label for it (in a world:
  *  the world service id); `stateService` is the control-plane service whose ledger this is.
@@ -60,7 +61,10 @@ export type LedgerDelta = {
     actions: ChangesetAction[];
     vendors: VendorSummary[];
     total: number;
+    /** Presentation only, outside changeset bodies: fields immediately before and after each write. */
+    fieldChanges?: Record<string, Record<string, FieldChange>>;
 };
+export declare const fieldDiffKey: (service: string, stateService: string, id: string) => string;
 /** A verifier: one deterministic check against post-replay projected state — the CI assertion
  *  of the operational PR (docs/concepts/the-model.md v1). The `assert` is the kernel's ONE check
  *  expression (`TwinActionPrecondition`: subject/field/op/value, evaluated by
@@ -189,6 +193,8 @@ export declare function diffLedgers(opts: {
     ledgers: LedgerRef[];
     base: WorldMarker;
 }): LedgerDelta;
+/** Read each write's pre-state through the authoritative kernel projection. No UI history fold. */
+export declare function describeActionFields(ledgers: LedgerRef[], actions: ChangesetAction[]): NonNullable<LedgerDelta['fieldChanges']>;
 /** Group a delta by vendor, then by operation — both in FIRST-OCCURRENCE order, so the rollup
  *  reads in the same causal order as the actions themselves. */
 export declare function summarizeByVendor(actions: ChangesetAction[]): VendorSummary[];
@@ -403,6 +409,11 @@ export type CompensationEntry = {
 export type ChangesetApplication = {
     at: string;
     contentHash: string;
+    /** A push receipt names its destination; absent on legacy and non-push applications. */
+    destination?: {
+        url: string;
+        namespace: string;
+    };
     outcome: 'applied' | 'partial' | 'refused';
     forced?: boolean;
     refusal?: string[];

package/dist/src/changeset.js

@@ -20,7 +20,7 @@ import { worldPaths } from "./storage.js";
 //            silently reporting the wrong delta.
 //
 //   DELTA    every action appended after the marker, across every ledger, ordered by
-//            `occurredAt` (the same causal order `volter-world tail` uses), grouped by vendor
+//            `occurredAt` with stable ledger/row ties (a timeline, not cross-vendor causality), grouped by vendor
 //            for rendering.
 //
 //   CHANGESET  a delta frozen into a content-addressed object: `{id, world, base, actions,
@@ -57,14 +57,15 @@ import { worldPaths } from "./storage.js";
 // the control root that holds it) and never learns what a world is. `volter-world` supplies
 // discovery and the CLI verbs; the state-level logic lives here, beside the ledgers it reads.
 import { createHash } from 'node:crypto';
-import { aliasesFrom } from "./log.js";
+import { aliasesFrom, readTreeMap, wholeLog } from "./log.js";
 import { appendActionIfAbsent, checkPrecondition, listActions, projectedPreconditionValue, projectResources, isTwinBookkeeping } from "./actions.js";
-import { canonicalJson, hashFieldValue } from "./hash.js";
+import { canonicalJson, diffSubjectFields, hashFieldValue } from "./hash.js";
 import { applyTwinWrite } from "./serve.js";
 export const MARKER_KIND = 'volter.world.marker.v1';
 export const CHANGESET_KIND = 'volter.world.changeset.v1';
 /** The id reserved for the synthetic "everything this world has ever recorded" base. */
 export const WORLD_BOOT_MARKER_ID = 'world-boot';
+export const fieldDiffKey = (service, stateService, id) => JSON.stringify([service, stateService, id]);
 /** Names that address a file on disk (markers, changesets): no separators, no traversal. */
 const SAFE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 export function assertSafeChangesetName(name, what = 'changeset') {
@@ -155,7 +156,36 @@ export function diffLedgers(opts) {
         return a.rowIndex - b.rowIndex;
     });
     const actions = ordered.map((o) => o.entry);
-    return { world: opts.world, base: opts.base, actions, vendors: summarizeByVendor(actions), total: actions.length };
+    return { world: opts.world, base: opts.base, actions, vendors: summarizeByVendor(actions), total: actions.length, fieldChanges: describeActionFields(opts.ledgers, actions) };
+}
+/** Read each write's pre-state through the authoritative kernel projection. No UI history fold. */
+export function describeActionFields(ledgers, actions) {
+    const fieldChanges = {};
+    for (const ledger of ledgers) {
+        const entries = wholeLog(ledger.stateService, ledger.controlRoot);
+        // An observation is atomic: its internal positions cannot be projected. Compare its
+        // writes with the state at the start of that batch, through the same kernel reader.
+        const positions = new Map();
+        let batchStart = 0;
+        entries.forEach((e, i) => {
+            if (!e.batch || e.batch !== entries[i - 1]?.batch)
+                batchStart = i;
+            if (!positions.has(e.id))
+                positions.set(e.id, e.batch ? batchStart : i);
+        });
+        for (const { action, service, stateService } of actions.filter(a => a.service === ledger.service && a.stateService === ledger.stateService)) {
+            const at = positions.get(action.id);
+            if (at === undefined || !action.fields)
+                continue;
+            const subject = readTreeMap(stateService, ledger.controlRoot, { at }).get(`${action.subject.type}:${action.subject.id}`);
+            const fields = subject?.fields ?? {};
+            fieldChanges[fieldDiffKey(service, stateService, action.id)] = diffSubjectFields({
+                subject: action.subject, fields, fieldHashes: Object.fromEntries(Object.entries(fields).map(([k, v]) => [k, hashFieldValue(v)])),
+                latestEventId: '', updatedAt: '',
+            }, action.fields);
+        }
+    }
+    return fieldChanges;
 }
 /** Group a delta by vendor, then by operation — both in FIRST-OCCURRENCE order, so the rollup
  *  reads in the same causal order as the actions themselves. */
@@ -198,6 +228,11 @@ export function formatLedgerDelta(delta, opts = {}) {
     for (const vendor of delta.vendors) {
         const parts = vendor.operations.map((o) => `${o.count} ${o.operation}${renderIds(o.subjectIds)}`);
         lines.push(`  ${vendor.service}: ${parts.join(', ')}`);
+        for (const item of delta.actions.filter(a => a.service === vendor.service)) {
+            for (const [field, change] of Object.entries(delta.fieldChanges?.[fieldDiffKey(item.service, item.stateService, item.action.id)] ?? {})) {
+                lines.push(`    ${item.action.subject.type}:${item.action.subject.id}.${field}: ${change.before === undefined ? '(absent)' : JSON.stringify(change.before)} → ${JSON.stringify(change.after)}`);
+            }
+        }
     }
     lines.push('', `  ${plural(delta.total, 'action')} across ${plural(delta.vendors.length, 'twin')}`);
     return `${lines.join('\n')}\n`;

package/dist/src/derived-core.js

@@ -679,13 +679,18 @@ async function keptFiles(m, call, root) {
     }
     return out;
 }
+/** Presentation tag only: keep provisioning in history without copying credential request data. */
+function provisioningInput(call) {
+    return call.request.headers.get('x-volter-world-activity') === 'provisioning' ? { input: { activity: 'provisioning' } } : {};
+}
 function recordedInput(m, call, merged) {
     const id = call.operation.id;
     const sent = sentOf.get(call);
-    const asSent = sent ? { path: sent.path, query: sent.query, body: sent.body, headers: sent.headers, ...(sent.lane ? { lane: sent.lane } : {}), ...(sent.requestId ? { requestId: sent.requestId } : {}), ...(sent.type ? { contentType: sent.type } : {}) } : { path: call.params, body: merged };
+    const activity = call.request.headers.get('x-volter-world-activity') === 'provisioning' ? { activity: 'provisioning' } : {};
+    const asSent = sent ? { ...activity, path: sent.path, query: sent.query, body: sent.body, headers: sent.headers, ...(sent.lane ? { lane: sent.lane } : {}), ...(sent.requestId ? { requestId: sent.requestId } : {}), ...(sent.type ? { contentType: sent.type } : {}) } : { ...activity, path: call.params, body: merged };
     if (id === 'graphql') {
         const b = (sent?.body ?? {});
-        return { graphql: { query: b.query, variables: b.variables ?? {}, ...(b.operationName ? { operationName: b.operationName } : {}) }, ...(sent?.lane ? { lane: sent.lane } : {}), headers: sent?.headers ?? {} };
+        return { ...activity, graphql: { query: b.query, variables: b.variables ?? {}, ...(b.operationName ? { operationName: b.operationName } : {}) }, ...(sent?.lane ? { lane: sent.lane } : {}), headers: sent?.headers ?? {} };
     }
     if (id === 'clock')
         return { clock: true };
@@ -1381,7 +1386,7 @@ export async function contextFor(m, call, scope) {
                 return mintId(m, resource, root, at);
             const { value } = await applyTwinWriteAtomic(m.service, (snapshot) => {
                 const id = mintId(m, resource, root, at, snapshot);
-                return { kind: 'write', value: id, write: { operation: `${resource.slice(1)}.issue`, subjectType: storedType(m, resource), subjectId: id, fields: { issuedAt: at }, occurredAt: at, actor: { kind: 'system' } } };
+                return { kind: 'write', value: id, write: { operation: `${resource.slice(1)}.issue`, subjectType: storedType(m, resource), subjectId: id, fields: { issuedAt: at }, ...provisioningInput(call), occurredAt: at, actor: { kind: 'system' } } };
             }, root);
             return value;
         },
@@ -1392,7 +1397,7 @@ export async function contextFor(m, call, scope) {
                 throw new Error(`semantics: ${type} is not a bookkeeping type (bookkeeping types start with _)`);
             if (id !== undefined) {
                 const before = operation ? stateBeforeWrite(m, type, id, root) : undefined;
-                const { result } = await applyTwinWrite(m.service, { operation: operation ?? `${type.slice(1)}.record`, subjectType: type, subjectId: id, fields, occurredAt: at, actor: { kind: 'system' } }, root);
+                const { result } = await applyTwinWrite(m.service, { operation: operation ?? `${type.slice(1)}.record`, subjectType: type, subjectId: id, fields, ...provisioningInput(call), occurredAt: at, actor: { kind: 'system' } }, root);
                 if (operation)
                     observeStateWrite(m, result, before, root, stateChecks);
                 return id;
@@ -1411,7 +1416,7 @@ export async function contextFor(m, call, scope) {
                     }
                     return `${prefix}${max + 1n}`;
                 })();
-                return { kind: 'write', value: subject, write: { operation: operation ?? `${type.slice(1)}.record`, subjectType: type, subjectId: subject, fields, occurredAt: at, actor: { kind: 'system' } } };
+                return { kind: 'write', value: subject, write: { operation: operation ?? `${type.slice(1)}.record`, subjectType: type, subjectId: subject, fields, ...provisioningInput(call), occurredAt: at, actor: { kind: 'system' } } };
             }, root, () => resourcesOfType(m.service, type, root));
             if (operation && result)
                 observeStateWrite(m, result, undefined, root, stateChecks);
@@ -1488,7 +1493,7 @@ export async function contextFor(m, call, scope) {
                 const w = d.write;
                 if (transitionObserver)
                     before = resources.find((r) => r.type === storedType(m, w.resource) && r.id === w.id);
-                return { kind: 'write', value: d.value, write: { operation: w.operation, subjectType: storedType(m, w.resource), subjectId: w.id, fields: w.fields, occurredAt: at, actor: { kind: 'agent' } } };
+                return { kind: 'write', value: d.value, write: { operation: w.operation, subjectType: storedType(m, w.resource), subjectId: w.id, fields: w.fields, ...provisioningInput(call), occurredAt: at, actor: { kind: 'agent' } } };
             }, root);
             if (result)
                 observeStateWrite(m, result, before, root, stateChecks);

package/dist/src/log.js

@@ -31,6 +31,8 @@ import { hashFieldValue } from "./hash.js";
 import { worldPaths } from "./storage.js";
 import { getActiveWorldStore } from "./world-store.js";
 export const CHECKPOINT_EVERY = 100;
+// Retained checkpoints and process memos are disposable projections, never history.
+const TREE_PROJECTION_VERSION = 2;
 export const DELTA_SUFFIX = '.delta';
 export function parentLogPath(service, root) { return worldPaths(service, root).events; }
 export function branchLogPath(service, root) { return join(dirname(worldPaths(service, root).events), 'actions.jsonl'); }
@@ -389,7 +391,13 @@ export function foldHistory(entries, layout, service) {
     const baseCount = layout.base ? historyLength(layout.base) : 0;
     const tree = layout.base ? foldHistory(entries.slice(0, baseCount), layout.base, service) : new Map();
     const parent = entries.slice(0, baseCount + layout.parent);
-    foldEntries(tree, parent.slice(baseCount));
+    const inheritedIds = landedIds(parent.slice(0, baseCount));
+    const ownParent = parent.slice(baseCount);
+    // A local acknowledgement is provenance for an inherited write, not a newer write.
+    // Reapplying it would overwrite later upstream fields (including vendor counters).
+    // Deployment outcomes remain observations and must still fold their returned fields.
+    const acknowledged = new Set([...inheritedIds, ...ownParent.filter(e => e.landsId && e.receipt?.status === 'landed' && inheritedIds.has(e.landsId)).map(e => e.id)]);
+    foldEntries(tree, ownParent, acknowledged);
     foldEntries(tree, entries.slice(baseCount + layout.parent, baseCount + layout.parent + layout.branch), landedIds(parent));
     foldAliases(tree, aliasesFrom(parent), service);
     return tree;
@@ -415,7 +423,7 @@ function statKey(path) { const s = getActiveWorldStore().stat(path); return s ?
 /** What a service's PARENT side at `root` is folded from (its parent log, branch.json and inherited history), as one
  *  string: while it stands, its aliases and landed ids are the same, whatever the branch's own log does. */
 export function parentStamp(service, root) { return parentKeyOf(service, root); }
-function parentKeyOf(service, root) { return `${statKey(parentLogPath(service, root))}|${getActiveWorldStore().read(branchMetaPath(service, root)) ?? ''}|${inheritedHistoryKey(service, root)}`; }
+function parentKeyOf(service, root) { return `${TREE_PROJECTION_VERSION}|${statKey(parentLogPath(service, root))}|${getActiveWorldStore().read(branchMetaPath(service, root)) ?? ''}|${inheritedHistoryKey(service, root)}`; }
 /** What a service's tree (and every subject's history) at `root` is folded from, as one string: while it
  *  stands, nothing was written. A pack that projects the tree into its own state memoizes on it. */
 export function treeStamp(service, root) { return `${parentKeyOf(service, root)}#${statKey(branchLogPath(service, root))}`; }
@@ -595,7 +603,7 @@ function readTreeMapFull(service, root, opts = {}) {
         const branchAll = branchEntries(service, root);
         const until = opts.until === undefined ? -1 : branchAll.findIndex(e => e.id === opts.until);
         const branch = until < 0 ? branchAll : branchAll.slice(0, until);
-        const parentDigest = hashFieldValue({ inherited, own });
+        const parentDigest = hashFieldValue({ projectionVersion: TREE_PROJECTION_VERSION, inherited, own });
         const branchDigest = hashFieldValue(branch);
         const raw = opts.until === undefined ? getActiveWorldStore().read(checkpointPath(service, root)) : null;
         const cp = raw === null ? null : parseExactJson(raw);
@@ -622,7 +630,7 @@ export function cutCheckpoint(service, root) {
         const subjects = [...readTreeMap(service, root).values()];
         const inherited = inheritedHistory(service, root);
         const own = ownParentEntries(service, root);
-        getActiveWorldStore().writeAtomic(checkpointPath(service, root), JSON.stringify({ parentDigest: hashFieldValue({ inherited, own }), branchDigest: hashFieldValue(branchEntries(service, root)), branchCount: branchEntries(service, root).length, subjects }));
+        getActiveWorldStore().writeAtomic(checkpointPath(service, root), JSON.stringify({ parentDigest: hashFieldValue({ projectionVersion: TREE_PROJECTION_VERSION, inherited, own }), branchDigest: hashFieldValue(branchEntries(service, root)), branchCount: branchEntries(service, root).length, subjects }));
     });
 }
 /** The branch's entries the parent does not hold: `set` rows, not reverted, not landed. */
@@ -776,8 +784,11 @@ export function rebaseBranch(service, root, opts = {}) {
         // a field both sides set to an INSTANT (updated_at, created) is when each wrote, not what: never a conflict
         const instant = (v) => typeof v === 'string' && /^\d{4}-\d\d-\d\dT\d\d:\d\d/.test(v) && Number.isFinite(Date.parse(v));
         const currentAliases = aliasesFrom(historyEntries(next));
+        const incomingLanded = landedIds(historyEntries(next));
         const conflicts = [];
-        for (const e of branchEntries(service, root)) {
+        // Acknowledged writes, including their counter effects, now belong to the incoming parent.
+        // Comparing them again against a later upstream write creates conflicts with already-landed work.
+        for (const e of unpushedEntries(service, root).filter(e => !incomingLanded.has(e.id))) {
             if (e.op !== 'set' || !e.fields || !existed.has(`${e.subject.type}:${e.subject.id}`))
                 continue;
             const fields = resolveReferences(service, e.subject.type, e.fields, currentAliases);

package/dist/src/pack-fetch.js

@@ -11,7 +11,7 @@ import { ORIGINAL_PATH_HEADER } from "./sigv4.js";
 import { placedCookies, TWIN_PREFIX_HEADER } from "./twin-fetch.js";
 import { PREFIX_PARAMS_HEADER } from "./derived.js";
 import { withHeaders } from "./with-headers.js";
-import { authRefusal, bindSemantics, contextFor, LANE_HEADER, SCENARIO_DECISION_HEADER, scenarioDecisionHeader, coreFor, crossCutting, derivedRequestScopes, vendorError } from "./derived-core.js";
+import { authRefusal, bindSemantics, contextFor, LANE_HEADER, SCENARIO_DECISION_HEADER, scenarioDecisionHeader, storedType, coreFor, crossCutting, derivedRequestScopes, vendorError } from "./derived-core.js";
 import { compileSurface, createDerivedFetch, matchOperation, pathParams } from "./derived.js";
 import { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, runAsVendorMove } from "./request-scope.js";
 import { parseScenarioDocument, ScenarioEngine, ScenarioError, statefulTwinManifest, twinManifest } from "./scenario.js";
@@ -428,7 +428,18 @@ export function createPackFetch(parts, options = {}) {
             const discoveryDoors = [...(m.doors ?? []), ...(m.machines ? [{ id: 'machine-pool', method: 'POST', path: '/_twin/machine-pool', note: 'Enroll the World execution pool: { kind: light | docker | none | fake, images?: { image: { context, command?, runtime? } } }.' }] : [])];
             // the workspaces a person can be shown (Viewing a World): each built workspace screen's id and path
             const laneDiscovery = await laneDoor(request, '/twin');
-            const shown = { ...(workspaces().length ? { screens: workspaces() } : {}), ...(Object.keys(laneDiscovery).length ? { lanes: laneDiscovery } : {}) };
+            const resources = {};
+            for (const [type, spec] of Object.entries(m.resources)) {
+                const resource = resources[storedType(m, type)] ??= { relations: [] };
+                const relations = [
+                    ...(spec.parent ? [{ field: spec.parent.field, to: storedType(m, spec.parent.resource) }] : []),
+                    ...Object.entries(spec.embeds ?? {}).map(([field, to]) => ({ field, to: storedType(m, to) })),
+                ];
+                for (const relation of relations)
+                    if (!resource.relations.some(r => r.field === relation.field && r.to === relation.to))
+                        resource.relations.push(relation);
+            }
+            const shown = { resources, ...(workspaces().length ? { screens: workspaces() } : {}), ...(Object.keys(laneDiscovery).length ? { lanes: laneDiscovery } : {}) };
             const identity = d.identity ?? (m.auth?.held ? 'Authenticate as the vendor does, using a credential issued in this World; unknown credentials are refused.' : undefined);
             // a model vendor's: its state, and what its scenario scripts, with the scenario's live counts
             if (parts.scenario && d.behavior) {

package/dist/src/runtime.d.ts

@@ -46,7 +46,7 @@ export { forkTwin, isFork, readForkMeta, } from './fork.js';
 export type { ForkMeta } from './fork.js';
 export { appendAction, appendTransactionCommit, checkPrecondition, confirmAction, listActions, listTransactionCommits, pendingActions, pushablePendingActions, isTwinBookkeeping, pendingTransactionCommits, projectResources, projectOwnerResources, OwnerStoreAmbiguousError, revertAction, TwinActionPreconditionError, subjectAliases, resolveSubjectId, runWithCorrelationId, currentCorrelationId } from './actions.js';
 export type { ActionProjection, ProjectedDelivery, ProjectedResource, ProjectedResourcePatch, ProjectedResourceRef, TwinAction, TwinActionOp, TwinActionPrecondition, TwinActionPreconditionOp, TwinActionRevertSpec, TwinTransactionCommit, TwinTransactionCommitOp, TwinTransactionPrecondition, TwinTransactionRevertSpec, } from './actions.js';
-export { approveChangeset, assertMarkerBelongsTo, assertSafeChangesetName, assertValidVerifiers, buildChangeset, captureMarker, changesetContentHash, changesetHashMatches, changesetReadiness, approverOf, CHANGESET_KIND, diffLedgers, formatApplication, formatChangeset, formatRebaseReport, narrateActions, narrationDrift, rebaseChangeset, formatChangesetStatus, formatLedgerDelta, formatReplayReport, formatVerification, MARKER_KIND, normalizeChangeset, parseVerifierExpression, replayChangeset, runChangesetVerifiers, summarizeByVendor, twinWriteShape, withApplication, withVerification, worldBootMarker, WORLD_BOOT_MARKER_ID, } from './changeset.js';
+export { approveChangeset, assertMarkerBelongsTo, assertSafeChangesetName, assertValidVerifiers, buildChangeset, captureMarker, changesetContentHash, changesetHashMatches, changesetReadiness, approverOf, CHANGESET_KIND, diffLedgers, describeActionFields, fieldDiffKey, formatApplication, formatChangeset, formatRebaseReport, narrateActions, narrationDrift, rebaseChangeset, formatChangesetStatus, formatLedgerDelta, formatReplayReport, formatVerification, MARKER_KIND, normalizeChangeset, parseVerifierExpression, replayChangeset, runChangesetVerifiers, summarizeByVendor, twinWriteShape, withApplication, withVerification, worldBootMarker, WORLD_BOOT_MARKER_ID, } from './changeset.js';
 export type { ApplyReceipt, RebaseActionResult, RebaseReport, RebaseTarget, Changeset, ChangesetAction, ChangesetApplication, CompensationEntry, ChangesetApproval, ChangesetReadiness, ChangesetVerification, ChangesetVerifier, ChangesetVerifierResult, LedgerDelta, LedgerPosition, LedgerRef, ReplayActionResult, ReplayReport, ReplayTarget, VendorSummary, WorldMarker, } from './changeset.js';
 export { getActivePackAssets, setActivePackAssets, packAsset, assetContentType, confinedAssetPath, LocalPackAssets, BindingPackAssets, type PackAssetStore } from './pack-assets.js';
 export { installedPackageDir, installedVendorPacks, packVendor, packRepository, isDerivedPack, vendorPackageDir, vendorOfPackModule } from './pack-paths.js';

package/dist/src/runtime.js

@@ -66,7 +66,7 @@ export { appendAction, appendTransactionCommit, checkPrecondition, confirmAction
 // the content-addressed, replayable changeset over that delta. State-level by construction
 // (it reads the same per-service action ledgers `actions.ts` writes); `volter-world` supplies
 // world discovery and thin verbs on top.
-export { approveChangeset, assertMarkerBelongsTo, assertSafeChangesetName, assertValidVerifiers, buildChangeset, captureMarker, changesetContentHash, changesetHashMatches, changesetReadiness, approverOf, CHANGESET_KIND, diffLedgers, formatApplication, formatChangeset, formatRebaseReport, narrateActions, narrationDrift, rebaseChangeset, formatChangesetStatus, formatLedgerDelta, formatReplayReport, formatVerification, MARKER_KIND, normalizeChangeset, parseVerifierExpression, replayChangeset, runChangesetVerifiers, summarizeByVendor, twinWriteShape, withApplication, withVerification, worldBootMarker, WORLD_BOOT_MARKER_ID, } from "./changeset.js";
+export { approveChangeset, assertMarkerBelongsTo, assertSafeChangesetName, assertValidVerifiers, buildChangeset, captureMarker, changesetContentHash, changesetHashMatches, changesetReadiness, approverOf, CHANGESET_KIND, diffLedgers, describeActionFields, fieldDiffKey, formatApplication, formatChangeset, formatRebaseReport, narrateActions, narrationDrift, rebaseChangeset, formatChangesetStatus, formatLedgerDelta, formatReplayReport, formatVerification, MARKER_KIND, normalizeChangeset, parseVerifierExpression, replayChangeset, runChangesetVerifiers, summarizeByVendor, twinWriteShape, withApplication, withVerification, worldBootMarker, WORLD_BOOT_MARKER_ID, } from "./changeset.js";
 export { getActivePackAssets, setActivePackAssets, packAsset, assetContentType, confinedAssetPath, LocalPackAssets, BindingPackAssets } from "./pack-assets.js";
 export { installedPackageDir, installedVendorPacks, packVendor, packRepository, isDerivedPack, vendorPackageDir, vendorOfPackModule } from "./pack-paths.js";
 // The git plane (contract "The git plane is a kernel library"): objects, packs, refs, smart HTTP.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-core",
-  "version": "3.0.138",
+  "version": "3.0.140",
   "description": "The kernel of Volter World: one log per twin, branches as pointers, checkpoints, the fold that keeps a twin current, the head that performs a write against the vendor, references, and the git plane. A twin package builds on it; the runtime serves it.",
   "keywords": [
     "twin",

package/src/changeset.ts

@@ -20,7 +20,7 @@ import { worldPaths } from './storage.ts';
 //            silently reporting the wrong delta.
 //
 //   DELTA    every action appended after the marker, across every ledger, ordered by
-//            `occurredAt` (the same causal order `volter-world tail` uses), grouped by vendor
+//            `occurredAt` with stable ledger/row ties (a timeline, not cross-vendor causality), grouped by vendor
 //            for rendering.
 //
 //   CHANGESET  a delta frozen into a content-addressed object: `{id, world, base, actions,
@@ -57,14 +57,14 @@ import { worldPaths } from './storage.ts';
 // the control root that holds it) and never learns what a world is. `volter-world` supplies
 // discovery and the CLI verbs; the state-level logic lives here, beside the ledgers it reads.
 import { createHash } from 'node:crypto';
-import { aliasesFrom, parentEntries, type Entry } from './log.ts';
+import { aliasesFrom, parentEntries, readTreeMap, wholeLog, type Entry } from './log.ts';
 import { appendActionIfAbsent, checkPrecondition, listActions, projectedPreconditionValue, projectResources, isTwinBookkeeping } from './actions.ts';
 import type { TwinActionRevertSpec } from './actions.ts';
 import { touchedSubjects } from './actions.ts';
 import type { PerformAction } from './head.ts';
 import type { RemoteExecute } from './remote-execute.ts';
 import type { TwinAction, TwinActionPrecondition, TwinActionPreconditionOp } from './actions.ts';
-import { canonicalJson, hashFieldValue } from './hash.ts';
+import { canonicalJson, diffSubjectFields, hashFieldValue, type FieldChange } from './hash.ts';
 import { applyTwinWrite } from './serve.ts';
 import type { TwinResource } from './serve.ts';
 
@@ -130,8 +130,12 @@ export type LedgerDelta = {
   actions: ChangesetAction[];
   vendors: VendorSummary[];
   total: number;
+  /** Presentation only, outside changeset bodies: fields immediately before and after each write. */
+  fieldChanges?: Record<string, Record<string, FieldChange>>;
 };
 
+export const fieldDiffKey = (service: string, stateService: string, id: string): string => JSON.stringify([service, stateService, id]);
+
 /** A verifier: one deterministic check against post-replay projected state — the CI assertion
  *  of the operational PR (docs/concepts/the-model.md v1). The `assert` is the kernel's ONE check
  *  expression (`TwinActionPrecondition`: subject/field/op/value, evaluated by
@@ -331,7 +335,34 @@ export function diffLedgers(opts: { world: string; ledgers: LedgerRef[]; base: W
   });
 
   const actions = ordered.map((o) => o.entry);
-  return { world: opts.world, base: opts.base, actions, vendors: summarizeByVendor(actions), total: actions.length };
+  return { world: opts.world, base: opts.base, actions, vendors: summarizeByVendor(actions), total: actions.length, fieldChanges: describeActionFields(opts.ledgers, actions) };
+}
+
+/** Read each write's pre-state through the authoritative kernel projection. No UI history fold. */
+export function describeActionFields(ledgers: LedgerRef[], actions: ChangesetAction[]): NonNullable<LedgerDelta['fieldChanges']> {
+  const fieldChanges: NonNullable<LedgerDelta['fieldChanges']> = {};
+  for (const ledger of ledgers) {
+    const entries = wholeLog(ledger.stateService, ledger.controlRoot);
+    // An observation is atomic: its internal positions cannot be projected. Compare its
+    // writes with the state at the start of that batch, through the same kernel reader.
+    const positions = new Map<string, number>();
+    let batchStart = 0;
+    entries.forEach((e, i) => {
+      if (!e.batch || e.batch !== entries[i - 1]?.batch) batchStart = i;
+      if (!positions.has(e.id)) positions.set(e.id, e.batch ? batchStart : i);
+    });
+    for (const { action, service, stateService } of actions.filter(a => a.service === ledger.service && a.stateService === ledger.stateService)) {
+      const at = positions.get(action.id);
+      if (at === undefined || !action.fields) continue;
+      const subject = readTreeMap(stateService, ledger.controlRoot, { at }).get(`${action.subject.type}:${action.subject.id}`);
+      const fields = subject?.fields ?? {};
+      fieldChanges[fieldDiffKey(service, stateService, action.id)] = diffSubjectFields({
+        subject: action.subject, fields, fieldHashes: Object.fromEntries(Object.entries(fields).map(([k, v]) => [k, hashFieldValue(v)])),
+        latestEventId: '', updatedAt: '',
+      }, action.fields);
+    }
+  }
+  return fieldChanges;
 }
 
 /** Group a delta by vendor, then by operation — both in FIRST-OCCURRENCE order, so the rollup
@@ -376,6 +407,11 @@ export function formatLedgerDelta(delta: LedgerDelta, opts: { title?: string } =
   for (const vendor of delta.vendors) {
     const parts = vendor.operations.map((o) => `${o.count} ${o.operation}${renderIds(o.subjectIds)}`);
     lines.push(`  ${vendor.service}: ${parts.join(', ')}`);
+    for (const item of delta.actions.filter(a => a.service === vendor.service)) {
+      for (const [field, change] of Object.entries(delta.fieldChanges?.[fieldDiffKey(item.service, item.stateService, item.action.id)] ?? {})) {
+        lines.push(`    ${item.action.subject.type}:${item.action.subject.id}.${field}: ${change.before === undefined ? '(absent)' : JSON.stringify(change.before)} → ${JSON.stringify(change.after)}`);
+      }
+    }
   }
   lines.push('', `  ${plural(delta.total, 'action')} across ${plural(delta.vendors.length, 'twin')}`);
   return `${lines.join('\n')}\n`;
@@ -984,6 +1020,8 @@ export type CompensationEntry = {
 export type ChangesetApplication = {
   at: string;
   contentHash: string;
+  /** A push receipt names its destination; absent on legacy and non-push applications. */
+  destination?: { url: string; namespace: string };
   outcome: 'applied' | 'partial' | 'refused';
   forced?: boolean;
   refusal?: string[];

package/src/derived-core.ts

@@ -1149,13 +1149,19 @@ async function keptFiles(m: DerivedManifest, call: DerivedCall, root: string | u
   return out;
 }
 
+/** Presentation tag only: keep provisioning in history without copying credential request data. */
+function provisioningInput(call: DerivedCall): { input?: { activity: 'provisioning' } } {
+  return call.request.headers.get('x-volter-world-activity') === 'provisioning' ? { input: { activity: 'provisioning' } } : {};
+}
+
 function recordedInput(m: DerivedManifest, call: DerivedCall, merged: Record<string, unknown>): Record<string, unknown> {
   const id = call.operation.id;
   const sent = sentOf.get(call);
-  const asSent = sent ? { path: sent.path, query: sent.query, body: sent.body, headers: sent.headers, ...(sent.lane ? { lane: sent.lane } : {}), ...(sent.requestId ? { requestId: sent.requestId } : {}), ...(sent.type ? { contentType: sent.type } : {}) } : { path: call.params, body: merged };
+  const activity = call.request.headers.get('x-volter-world-activity') === 'provisioning' ? { activity: 'provisioning' } : {};
+  const asSent = sent ? { ...activity, path: sent.path, query: sent.query, body: sent.body, headers: sent.headers, ...(sent.lane ? { lane: sent.lane } : {}), ...(sent.requestId ? { requestId: sent.requestId } : {}), ...(sent.type ? { contentType: sent.type } : {}) } : { ...activity, path: call.params, body: merged };
   if (id === 'graphql') {
     const b = (sent?.body ?? {}) as { query?: unknown; variables?: unknown; operationName?: unknown };
-    return { graphql: { query: b.query, variables: b.variables ?? {}, ...(b.operationName ? { operationName: b.operationName } : {}) }, ...(sent?.lane ? { lane: sent.lane } : {}), headers: sent?.headers ?? {} };
+    return { ...activity, graphql: { query: b.query, variables: b.variables ?? {}, ...(b.operationName ? { operationName: b.operationName } : {}) }, ...(sent?.lane ? { lane: sent.lane } : {}), headers: sent?.headers ?? {} };
   }
   if (id === 'clock') return { clock: true };
   if (id === 'unmatched') return { gap: true, ...asSent };
@@ -1994,7 +2000,7 @@ export async function contextFor(m: DerivedManifest, call: DerivedCall, scope: C
       if (scope.readOnly === true || isReadOnlyRequest(call.request)) return mintId(m, resource, root, at);
       const { value } = await applyTwinWriteAtomic(m.service, (snapshot) => {
         const id = mintId(m, resource, root, at, snapshot);
-        return { kind: 'write', value: id, write: { operation: `${resource.slice(1)}.issue`, subjectType: storedType(m, resource), subjectId: id, fields: { issuedAt: at }, occurredAt: at, actor: { kind: 'system' } } };
+        return { kind: 'write', value: id, write: { operation: `${resource.slice(1)}.issue`, subjectType: storedType(m, resource), subjectId: id, fields: { issuedAt: at }, ...provisioningInput(call), occurredAt: at, actor: { kind: 'system' } } };
       }, root);
       return value;
     },
@@ -2004,7 +2010,7 @@ export async function contextFor(m: DerivedManifest, call: DerivedCall, scope: C
       if (!type.startsWith('_')) throw new Error(`semantics: ${type} is not a bookkeeping type (bookkeeping types start with _)`);
       if (id !== undefined) {
         const before = operation ? stateBeforeWrite(m, type, id, root) : undefined;
-        const { result } = await applyTwinWrite(m.service, { operation: operation ?? `${type.slice(1)}.record`, subjectType: type, subjectId: id, fields, occurredAt: at, actor: { kind: 'system' } }, root);
+        const { result } = await applyTwinWrite(m.service, { operation: operation ?? `${type.slice(1)}.record`, subjectType: type, subjectId: id, fields, ...provisioningInput(call), occurredAt: at, actor: { kind: 'system' } }, root);
         if (operation) observeStateWrite(m, result, before, root, stateChecks);
         return id;
       }
@@ -2020,7 +2026,7 @@ export async function contextFor(m: DerivedManifest, call: DerivedCall, scope: C
           }
           return `${prefix}${max + 1n}`;
         })();
-        return { kind: 'write', value: subject, write: { operation: operation ?? `${type.slice(1)}.record`, subjectType: type, subjectId: subject, fields, occurredAt: at, actor: { kind: 'system' } } };
+        return { kind: 'write', value: subject, write: { operation: operation ?? `${type.slice(1)}.record`, subjectType: type, subjectId: subject, fields, ...provisioningInput(call), occurredAt: at, actor: { kind: 'system' } } };
       }, root, () => resourcesOfType(m.service, type, root));
       if (operation && result) observeStateWrite(m, result, undefined, root, stateChecks);
       return value;
@@ -2088,7 +2094,7 @@ export async function contextFor(m: DerivedManifest, call: DerivedCall, scope: C
           if (!d.write) return { kind: 'skip', value: d.value };
           const w = d.write;
           if (transitionObserver) before = resources.find((r) => r.type === storedType(m, w.resource) && r.id === w.id);
-          return { kind: 'write', value: d.value, write: { operation: w.operation, subjectType: storedType(m, w.resource), subjectId: w.id, fields: w.fields, occurredAt: at, actor: { kind: 'agent' } } };
+          return { kind: 'write', value: d.value, write: { operation: w.operation, subjectType: storedType(m, w.resource), subjectId: w.id, fields: w.fields, ...provisioningInput(call), occurredAt: at, actor: { kind: 'agent' } } };
         },
         root,
       );

package/src/log.ts

@@ -92,6 +92,8 @@ export type BranchMeta = {
 };
 
 export const CHECKPOINT_EVERY = 100;
+// Retained checkpoints and process memos are disposable projections, never history.
+const TREE_PROJECTION_VERSION = 2;
 export const DELTA_SUFFIX = '.delta';
 
 export function parentLogPath(service: string, root?: string): string { return worldPaths(service, root).events; }
@@ -434,7 +436,13 @@ export function foldHistory(entries: Entry[], layout: HistoryLayout, service?: s
   const baseCount = layout.base ? historyLength(layout.base) : 0;
   const tree: Tree = layout.base ? foldHistory(entries.slice(0, baseCount), layout.base, service) : new Map();
   const parent = entries.slice(0, baseCount + layout.parent);
-  foldEntries(tree, parent.slice(baseCount));
+  const inheritedIds = landedIds(parent.slice(0, baseCount));
+  const ownParent = parent.slice(baseCount);
+  // A local acknowledgement is provenance for an inherited write, not a newer write.
+  // Reapplying it would overwrite later upstream fields (including vendor counters).
+  // Deployment outcomes remain observations and must still fold their returned fields.
+  const acknowledged = new Set([...inheritedIds, ...ownParent.filter(e => e.landsId && e.receipt?.status === 'landed' && inheritedIds.has(e.landsId)).map(e => e.id)]);
+  foldEntries(tree, ownParent, acknowledged);
   foldEntries(tree, entries.slice(baseCount + layout.parent, baseCount + layout.parent + layout.branch), landedIds(parent));
   foldAliases(tree, aliasesFrom(parent), service);
   return tree;
@@ -476,7 +484,7 @@ function statKey(path: string): string { const s = getActiveWorldStore().stat(pa
 /** What a service's PARENT side at `root` is folded from (its parent log, branch.json and inherited history), as one
  *  string: while it stands, its aliases and landed ids are the same, whatever the branch's own log does. */
 export function parentStamp(service: string, root?: string): string { return parentKeyOf(service, root); }
-function parentKeyOf(service: string, root?: string): string { return `${statKey(parentLogPath(service, root))}|${getActiveWorldStore().read(branchMetaPath(service, root)) ?? ''}|${inheritedHistoryKey(service, root)}`; }
+function parentKeyOf(service: string, root?: string): string { return `${TREE_PROJECTION_VERSION}|${statKey(parentLogPath(service, root))}|${getActiveWorldStore().read(branchMetaPath(service, root)) ?? ''}|${inheritedHistoryKey(service, root)}`; }
 /** What a service's tree (and every subject's history) at `root` is folded from, as one string: while it
  *  stands, nothing was written. A pack that projects the tree into its own state memoizes on it. */
 export function treeStamp(service: string, root?: string): string { return `${parentKeyOf(service, root)}#${statKey(branchLogPath(service, root))}`; }
@@ -612,7 +620,7 @@ function readTreeMapFull(service: string, root?: string, opts: { until?: string;
   const branchAll = branchEntries(service, root);
   const until = opts.until === undefined ? -1 : branchAll.findIndex(e => e.id === opts.until);
   const branch = until < 0 ? branchAll : branchAll.slice(0, until);
-  const parentDigest = hashFieldValue({ inherited, own }); const branchDigest = hashFieldValue(branch);
+  const parentDigest = hashFieldValue({ projectionVersion: TREE_PROJECTION_VERSION, inherited, own }); const branchDigest = hashFieldValue(branch);
   const raw = opts.until === undefined ? getActiveWorldStore().read(checkpointPath(service, root)) : null;
   const cp = raw === null ? null : parseExactJson(raw) as Checkpoint;
   if (cp?.parentDigest === parentDigest && cp.branchDigest === branchDigest) return new Map(cp.subjects.map(s => [`${s.type}:${s.id}`, { ...s, fields: { ...s.fields } }]));
@@ -633,7 +641,7 @@ export function cutCheckpoint(service: string, root?: string): void {
   dropCheckpoint(service, root);
   const subjects = [...readTreeMap(service, root).values()];
   const inherited = inheritedHistory(service, root); const own = ownParentEntries(service, root);
-  getActiveWorldStore().writeAtomic(checkpointPath(service, root), JSON.stringify({ parentDigest: hashFieldValue({ inherited, own }), branchDigest: hashFieldValue(branchEntries(service, root)), branchCount: branchEntries(service, root).length, subjects }));
+  getActiveWorldStore().writeAtomic(checkpointPath(service, root), JSON.stringify({ parentDigest: hashFieldValue({ projectionVersion: TREE_PROJECTION_VERSION, inherited, own }), branchDigest: hashFieldValue(branchEntries(service, root)), branchCount: branchEntries(service, root).length, subjects }));
   });
 }
 
@@ -773,8 +781,11 @@ export function rebaseBranch(service: string, root?: string, opts: { origin?: bo
   // a field both sides set to an INSTANT (updated_at, created) is when each wrote, not what: never a conflict
   const instant = (v: unknown): boolean => typeof v === 'string' && /^\d{4}-\d\d-\d\dT\d\d:\d\d/.test(v) && Number.isFinite(Date.parse(v));
   const currentAliases = aliasesFrom(historyEntries(next));
+  const incomingLanded = landedIds(historyEntries(next));
   const conflicts: Array<{ entryId: string; subject: { type: string; id: string }; field: string; op: string; expected?: unknown; actual?: unknown }> = [];
-  for (const e of branchEntries(service, root)) {
+  // Acknowledged writes, including their counter effects, now belong to the incoming parent.
+  // Comparing them again against a later upstream write creates conflicts with already-landed work.
+  for (const e of unpushedEntries(service, root).filter(e => !incomingLanded.has(e.id))) {
     if (e.op !== 'set' || !e.fields || !existed.has(`${e.subject.type}:${e.subject.id}`)) continue;
     const fields = resolveReferences(service, e.subject.type, e.fields, currentAliases);
     for (const p of since) {

package/src/pack-fetch.ts

@@ -11,7 +11,7 @@ import { ORIGINAL_PATH_HEADER } from './sigv4.ts';
 import { placedCookies, TWIN_PREFIX_HEADER } from './twin-fetch.ts';
 import { PREFIX_PARAMS_HEADER } from './derived.ts';
 import { withHeaders } from './with-headers.ts';
-import { authRefusal, bindSemantics, contextFor, LANE_HEADER, SCENARIO_DECISION_HEADER, scenarioDecisionHeader, coreFor, crossCutting, derivedRequestScopes, vendorError, type CoreScope, type DerivedManifest, type ErrorSpec, type Handler, type HandlerContext, type LanesDecl, type VendorManifest } from './derived-core.ts';
+import { authRefusal, bindSemantics, contextFor, LANE_HEADER, SCENARIO_DECISION_HEADER, scenarioDecisionHeader, storedType, coreFor, crossCutting, derivedRequestScopes, vendorError, type CoreScope, type DerivedManifest, type ErrorSpec, type Handler, type HandlerContext, type LanesDecl, type VendorManifest } from './derived-core.ts';
 import { compileSurface, createDerivedFetch, matchOperation, pathParams, type DerivedFetch, type DerivedOperation, type DerivedOwner, type DerivedSurface, type Workspace, type BoardFrame } from './derived.ts';
 import { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, runAsVendorMove } from './request-scope.ts';
 import { parseScenarioDocument, ScenarioEngine, ScenarioError, statefulTwinManifest, twinManifest, type PackScenarioAdapter } from './scenario.ts';
@@ -457,7 +457,16 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
       const discoveryDoors = [...(m.doors ?? []), ...(m.machines ? [{ id: 'machine-pool', method: 'POST', path: '/_twin/machine-pool', note: 'Enroll the World execution pool: { kind: light | docker | none | fake, images?: { image: { context, command?, runtime? } } }.' }] : [])];
       // the workspaces a person can be shown (Viewing a World): each built workspace screen's id and path
       const laneDiscovery = await laneDoor(request, '/twin');
-      const shown = { ...(workspaces().length ? { screens: workspaces() } : {}), ...(Object.keys(laneDiscovery).length ? { lanes: laneDiscovery } : {}) };
+      const resources: Record<string, { relations: Array<{ field: string; to: string }> }> = {};
+      for (const [type, spec] of Object.entries(m.resources)) {
+        const resource = resources[storedType(m, type)] ??= { relations: [] };
+        const relations = [
+          ...(spec.parent ? [{ field: spec.parent.field, to: storedType(m, spec.parent.resource) }] : []),
+          ...Object.entries(spec.embeds ?? {}).map(([field, to]) => ({ field, to: storedType(m, to) })),
+        ];
+        for (const relation of relations) if (!resource.relations.some(r => r.field === relation.field && r.to === relation.to)) resource.relations.push(relation);
+      }
+      const shown = { resources, ...(workspaces().length ? { screens: workspaces() } : {}), ...(Object.keys(laneDiscovery).length ? { lanes: laneDiscovery } : {}) };
       const identity = d.identity ?? (m.auth?.held ? 'Authenticate as the vendor does, using a credential issued in this World; unknown credentials are refused.' : undefined);
       // a model vendor's: its state, and what its scenario scripts, with the scenario's live counts
       if (parts.scenario && d.behavior) {

package/src/runtime.ts

@@ -244,7 +244,7 @@ export {
   changesetReadiness,
   approverOf,
   CHANGESET_KIND,
-  diffLedgers,
+  diffLedgers, describeActionFields, fieldDiffKey,
   formatApplication,
   formatChangeset,
   formatRebaseReport,