@volter/world-core 2.0.32 → 2.0.34

package/dist/src/changeset.d.ts

@@ -141,6 +141,15 @@ export type Changeset = {
     /** The author's own words for the changeset (git's commit message) — what `volter changeset -m`
      *  records. Outside the hash, like the narration; a reviewer reads both. */
     message?: string;
+    /** Who cut it, as the World names a caller (`key:<name>`, `key:<name> for:<person>`, `person:<who>`, `machine`, `person`,
+     *  `token`); the command on this machine records its signed-in person, and is absent when no one is signed in there.
+     *  Outside the hash, as approvals are (docs/contributing/architecture.md, "Who acted is recorded"). */
+    cutBy?: string;
+    /** The person accountable for it: the cutting grant's person, else the pusher's person when it lands in a shared World
+     *  with none. Outside the hash. */
+    owner?: string;
+    /** Who pushed it into the World that keeps this copy, a caller as `cutBy` names one. Outside the hash. */
+    pushedBy?: string;
     /** v3 — set by `rebaseChangeset`: the hash this object was rebased from, and when. Outside the hash. */
     rebasedFrom?: {
         contentHash: string;
@@ -212,6 +221,8 @@ export declare function buildChangeset(opts: {
     createdAt?: string;
     message?: string;
     cut?: Record<string, HistoryReference>;
+    cutBy?: string;
+    owner?: string;
 }): Changeset;
 /** Fill the lifecycle fields a changeset authored before v1 lacks on disk, without touching
  *  its hash (absent and empty `verifiers` hash identically by construction). */
@@ -329,6 +340,9 @@ export type ChangesetReadiness = {
     contentHash: string;
     /** stored hash matches the body */
     hashOk: boolean;
+    /** the different people whose approvals bind to the current hash, and how many this World requires */
+    approvers: number;
+    required: number;
     /** a verification exists, binds to the current hash, and every verifier passed */
     verified: boolean;
     verification: ChangesetVerification | null;
@@ -340,7 +354,13 @@ export type ChangesetReadiness = {
     /** empty exactly when ready */
     reasons: string[];
 };
-export declare function changesetReadiness(changeset: Changeset): ChangesetReadiness;
+/** Ready to apply: hashed as authored, verified against its current contents, and approved for them by `rules.approvals`
+ *  different people (the World's changeset rules; one when it names none). */
+/** Whom an approval counts for: the person a key acts for (`key:<name> for:<person>`), else the principal itself. */
+export declare function approverOf(principal: string): string;
+export declare function changesetReadiness(changeset: Changeset, rules?: {
+    approvals?: number;
+}): ChangesetReadiness;
 /** The single honest line `changeset status` prints. No push here — v2's job; this line only
  *  tells the truth about the object. */
 export declare function formatChangesetStatus(readiness: ChangesetReadiness): string;

package/dist/src/index.d.ts

@@ -41,7 +41,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, 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, 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 * as git from './git/index.js';

package/dist/src/index.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, 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, 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";
 // The git plane (contract "The git plane is a kernel library"): objects, packs, refs, smart HTTP.
 export * as git from "./git/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-core",
-  "version": "2.0.32",
+  "version": "2.0.34",
   "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

@@ -210,6 +210,15 @@ export type Changeset = {
   /** The author's own words for the changeset (git's commit message) — what `volter changeset -m`
    *  records. Outside the hash, like the narration; a reviewer reads both. */
   message?: string;
+  /** Who cut it, as the World names a caller (`key:<name>`, `key:<name> for:<person>`, `person:<who>`, `machine`, `person`,
+   *  `token`); the command on this machine records its signed-in person, and is absent when no one is signed in there.
+   *  Outside the hash, as approvals are (docs/contributing/architecture.md, "Who acted is recorded"). */
+  cutBy?: string;
+  /** The person accountable for it: the cutting grant's person, else the pusher's person when it lands in a shared World
+   *  with none. Outside the hash. */
+  owner?: string;
+  /** Who pushed it into the World that keeps this copy, a caller as `cutBy` names one. Outside the hash. */
+  pushedBy?: string;
   /** v3 — set by `rebaseChangeset`: the hash this object was rebased from, and when. Outside the hash. */
   rebasedFrom?: { contentHash: string; at: string };
   /** PROTOCOL 2 — where the parent log stood when this was cut, per state service (its entry count):
@@ -454,7 +463,7 @@ export function parseVerifierExpression(expression: string, id: string): Changes
 }
 
 /** Freeze a delta into a named, content-addressed changeset. */
-export function buildChangeset(opts: { name: string; world: string; base: string; actions: ChangesetAction[]; verifiers?: ChangesetVerifier[]; createdAt?: string; message?: string; cut?: Record<string, HistoryReference> }): Changeset {
+export function buildChangeset(opts: { name: string; world: string; base: string; actions: ChangesetAction[]; verifiers?: ChangesetVerifier[]; createdAt?: string; message?: string; cut?: Record<string, HistoryReference>; cutBy?: string; owner?: string }): Changeset {
   assertSafeChangesetName(opts.name);
   const verifiers = assertValidVerifiers(opts.verifiers ?? []);
   const core = { id: `chg_${opts.name}`, world: opts.world, base: opts.base, actions: opts.actions, verifiers, ...(opts.cut === undefined ? {} : { cut: opts.cut }) };
@@ -468,6 +477,8 @@ export function buildChangeset(opts: { name: string; world: string; base: string
     applied: null,
     narration: narrateActions(opts.actions),
     ...(opts.message === undefined ? {} : { message: opts.message }),
+    ...(opts.cutBy === undefined ? {} : { cutBy: opts.cutBy }),
+    ...(opts.owner === undefined ? {} : { owner: opts.owner }),
     contentHash: changesetContentHash(core),
   };
 }
@@ -509,6 +520,9 @@ function renderVerificationLines(changeset: Changeset): string[] {
       lines.push(`    FAIL ${result.id}: ${renderAssert(result)} — actual ${result.actual === undefined ? 'undefined' : JSON.stringify(result.actual)}`);
     }
   }
+  // who: cut by, owned by, pushed by (each only when recorded)
+  const who = [changeset.cutBy ? `cut by ${changeset.cutBy}` : null, changeset.owner ? `owned by ${changeset.owner}` : null, changeset.pushedBy ? `pushed by ${changeset.pushedBy}` : null].filter(Boolean);
+  if (who.length) lines.push(`  ${who.join(' · ')}`);
   if (changeset.approvals.length === 0) {
     lines.push('  approvals: none');
   } else {
@@ -790,6 +804,9 @@ export type ChangesetReadiness = {
   contentHash: string;
   /** stored hash matches the body */
   hashOk: boolean;
+  /** the different people whose approvals bind to the current hash, and how many this World requires */
+  approvers: number;
+  required: number;
   /** a verification exists, binds to the current hash, and every verifier passed */
   verified: boolean;
   verification: ChangesetVerification | null;
@@ -802,7 +819,14 @@ export type ChangesetReadiness = {
   reasons: string[];
 };
 
-export function changesetReadiness(changeset: Changeset): ChangesetReadiness {
+/** Ready to apply: hashed as authored, verified against its current contents, and approved for them by `rules.approvals`
+ *  different people (the World's changeset rules; one when it names none). */
+/** Whom an approval counts for: the person a key acts for (`key:<name> for:<person>`), else the principal itself. */
+export function approverOf(principal: string): string {
+  const at = principal.indexOf(' for:');
+  return principal.startsWith('key:') && at > 0 ? principal.slice(at + ' for:'.length) : principal;
+}
+export function changesetReadiness(changeset: Changeset, rules: { approvals?: number } = {}): ChangesetReadiness {
   const bodyHash = changesetContentHash(changeset);
   const hashOk = changeset.contentHash === bodyHash;
   const verification = changeset.verification;
@@ -820,8 +844,13 @@ export function changesetReadiness(changeset: Changeset): ChangesetReadiness {
     const failed = verification.results.filter((result) => !result.passed);
     reasons.push(`verification FAILED: ${failed.map((result) => result.id).join(', ')} (${failed.length} of ${verification.results.length})`);
   }
-  if (binding.length === 0) {
-    reasons.push(changeset.approvals.length ? 'no approval binds to the current body hash' : 'no approvals — run `changeset approve --as <principal>`');
+  const required = rules.approvals ?? 1;
+  // different people: a key's approval (`key:<name> for:<person>`) is its person's, so a person and their agent are one
+  const approvers = new Set(binding.map((approval) => approverOf(approval.principal))).size;
+  if (approvers < required) {
+    reasons.push(binding.length === 0
+      ? (changeset.approvals.length ? 'no approval binds to the current body hash' : 'no approvals — run `changeset approve --as <principal>`')
+      : `${approvers} of the ${required} approvals this World requires`);
   }
 
   const verified = Boolean(hashOk && verification && verification.contentHash === changeset.contentHash && verification.passed);
@@ -830,6 +859,8 @@ export function changesetReadiness(changeset: Changeset): ChangesetReadiness {
     world: changeset.world,
     contentHash: changeset.contentHash,
     hashOk,
+    approvers,
+    required,
     verified,
     verification,
     approvals: changeset.approvals.length,

package/src/index.ts

@@ -237,6 +237,7 @@ export {
   changesetContentHash,
   changesetHashMatches,
   changesetReadiness,
+  approverOf,
   CHANGESET_KIND,
   diffLedgers,
   formatApplication,