@sema-agent/core 7.61.0 → 7.62.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (176) hide show
  1. package/CHANGELOG.md +312 -0
  2. package/dist/agents/cascade.d.ts +11 -3
  3. package/dist/agents/cascade.js +1 -1
  4. package/dist/agents/peer-held-queue.d.ts +27 -4
  5. package/dist/agents/peer-held-queue.js +81 -36
  6. package/dist/agents/peer-session-drain.js +13 -3
  7. package/dist/agents/subagent.d.ts +6 -1
  8. package/dist/agents/subagent.js +66 -12
  9. package/dist/agents/suspend-guard.d.ts +38 -16
  10. package/dist/agents/suspend-guard.js +9 -4
  11. package/dist/agents/verify.js +4 -3
  12. package/dist/core/checkpoint-features.d.ts +722 -0
  13. package/dist/core/checkpoint-features.js +98 -0
  14. package/dist/core/checkpoint-requirements.d.ts +9 -2
  15. package/dist/core/checkpoint-requirements.js +9 -4
  16. package/dist/core/checkpoint-row-verdict.d.ts +99 -0
  17. package/dist/core/checkpoint-row-verdict.js +225 -0
  18. package/dist/core/checkpoint-store.d.ts +55 -745
  19. package/dist/core/checkpoint-store.js +39 -141
  20. package/dist/core/engine-notice.d.ts +19 -3
  21. package/dist/core/engine-notice.js +9 -2
  22. package/dist/core/gate-fold.js +2 -2
  23. package/dist/core/governance-codes.d.ts +3 -1
  24. package/dist/core/governance-codes.js +3 -0
  25. package/dist/core/hooks.d.ts +13 -0
  26. package/dist/core/human-input-projection.d.ts +1 -0
  27. package/dist/core/human-input-projection.js +3 -0
  28. package/dist/core/image-admission.d.ts +1 -1
  29. package/dist/core/locked-config.d.ts +2 -2
  30. package/dist/core/mcp-host-seat.js +6 -1
  31. package/dist/core/memory-engine/consolidation-driver.d.ts +1 -1
  32. package/dist/core/memory-vector.d.ts +1 -1
  33. package/dist/core/memory.d.ts +10 -10
  34. package/dist/core/mode-policy.js +1 -1
  35. package/dist/core/mods/classic-events.d.ts +9 -1
  36. package/dist/core/mods/dollar.d.ts +32 -1
  37. package/dist/core/mods/dollar.js +13 -1
  38. package/dist/core/mods/kernel/events.d.ts +11 -3
  39. package/dist/core/mods/kernel/events.js +13 -10
  40. package/dist/core/mods/lifecycle-stations.d.ts +36 -4
  41. package/dist/core/mods/lifecycle-stations.js +44 -9
  42. package/dist/core/mods/session-append.d.ts +4 -1
  43. package/dist/core/mods/session-append.js +7 -0
  44. package/dist/core/mods/session-receive.js +12 -15
  45. package/dist/core/mods/stations.d.ts +51 -6
  46. package/dist/core/mods/stations.js +124 -0
  47. package/dist/core/own-property-receipt.d.ts +7 -0
  48. package/dist/core/own-property-receipt.js +3 -0
  49. package/dist/core/read-root-candidate.js +1 -1
  50. package/dist/core/resume-startup-cause.d.ts +5 -4
  51. package/dist/core/runner/compact-session.js +5 -2
  52. package/dist/core/runner/contracts.d.ts +18 -8
  53. package/dist/core/runner/delegation-owner.d.ts +43 -0
  54. package/dist/core/runner/delegation-owner.js +59 -0
  55. package/dist/core/runner/lineage-reroot-view.d.ts +56 -0
  56. package/dist/core/runner/lineage-reroot-view.js +108 -0
  57. package/dist/core/runner/permission-rule-lanes.d.ts +2 -1
  58. package/dist/core/runner/permission-rule-lanes.js +2 -2
  59. package/dist/core/runner/person-path-rows.d.ts +15 -0
  60. package/dist/core/runner/person-path-rows.js +26 -3
  61. package/dist/core/runner/prepare-acquire-reconcile.d.ts +4 -1
  62. package/dist/core/runner/prepare-acquire-reconcile.js +7 -2
  63. package/dist/core/runner/prepare-caps-and-workflow.d.ts +1 -0
  64. package/dist/core/runner/prepare-caps-and-workflow.js +1 -1
  65. package/dist/core/runner/prepare-config-doors.d.ts +6 -6
  66. package/dist/core/runner/prepare-config-doors.js +3 -4
  67. package/dist/core/runner/prepare-hands-readface.d.ts +1 -1
  68. package/dist/core/runner/prepare-hands-readface.js +28 -7
  69. package/dist/core/runner/prepare-inherited-gate.d.ts +2 -0
  70. package/dist/core/runner/prepare-inherited-gate.js +7 -3
  71. package/dist/core/runner/prepare-task.js +10 -7
  72. package/dist/core/runner/resume-admission.d.ts +3 -3
  73. package/dist/core/runner/resume-admission.js +6 -3
  74. package/dist/core/runner/resume-apply.d.ts +4 -0
  75. package/dist/core/runner/resume-apply.js +11 -4
  76. package/dist/core/runner/resume-checkpoint-screen.d.ts +9 -0
  77. package/dist/core/runner/resume-checkpoint-screen.js +4 -84
  78. package/dist/core/runner/run-git-lane.d.ts +2 -0
  79. package/dist/core/runner/run-git-lane.js +4 -1
  80. package/dist/core/runner/run-harness-handlers.d.ts +2 -0
  81. package/dist/core/runner/run-harness-handlers.js +3 -2
  82. package/dist/core/runner/run-leg.js +24 -7
  83. package/dist/core/runner/run-settle-and-teardown.js +3 -2
  84. package/dist/core/runner/run-stop-and-final-verify.js +2 -1
  85. package/dist/core/runner/run-turn-boundary.js +7 -4
  86. package/dist/core/runner/runtask.js +6 -6
  87. package/dist/core/runner/steering-preview.d.ts +9 -0
  88. package/dist/core/runner/steering-preview.js +5 -0
  89. package/dist/core/runner/stream-steer-verb.js +8 -0
  90. package/dist/core/runner/tool-face-overlay.js +2 -0
  91. package/dist/core/runner/turn-attachments.d.ts +5 -0
  92. package/dist/core/runner/turn-attachments.js +1 -1
  93. package/dist/core/runner-deps.d.ts +2 -2
  94. package/dist/core/secret-env.d.ts +8 -5
  95. package/dist/core/secret-env.js +37 -18
  96. package/dist/core/session-store.d.ts +1 -1
  97. package/dist/core/session-store.js +5 -1
  98. package/dist/core/session.d.ts +14 -4
  99. package/dist/core/store-contracts/checkpoint-store-contract.d.ts +6 -0
  100. package/dist/core/store-contracts/checkpoint-store-contract.js +68 -0
  101. package/dist/core/store-contracts/session-store-contract.js +22 -8
  102. package/dist/core/task-event.d.ts +7 -1
  103. package/dist/core/task-notification.js +2 -1
  104. package/dist/core/task-registry-agent.d.ts +27 -7
  105. package/dist/core/task-registry-agent.js +12 -5
  106. package/dist/core/task-registry-shared.d.ts +7 -0
  107. package/dist/core/task-registry-workflow.js +4 -3
  108. package/dist/core/task-registry.d.ts +13 -2
  109. package/dist/core/task-registry.js +11 -4
  110. package/dist/core/task-result.d.ts +5 -5
  111. package/dist/core/task-spec.d.ts +1 -1
  112. package/dist/core/terminal-cause.d.ts +6 -6
  113. package/dist/core/tool-face.d.ts +6 -2
  114. package/dist/core/tool-face.js +1 -1
  115. package/dist/core/tool-policy.d.ts +2 -1
  116. package/dist/core/tool-roster.d.ts +4 -4
  117. package/dist/core/tool-spec.d.ts +4 -0
  118. package/dist/core/types.d.ts +1 -1
  119. package/dist/core/types.js +1 -1
  120. package/dist/engine/execution-env/node-execution-env.d.ts +3 -0
  121. package/dist/engine/execution-env/node-execution-env.js +12 -5
  122. package/dist/engine/harness/types.d.ts +11 -0
  123. package/dist/engine/session/parent-chain-guard.d.ts +3 -3
  124. package/dist/engine/session/parent-chain-guard.js +1 -1
  125. package/dist/engine/session/path-to-root.d.ts +18 -3
  126. package/dist/engine/session/path-to-root.js +15 -1
  127. package/dist/engine/session/repo-utils.d.ts +12 -1
  128. package/dist/engine/session/repo-utils.js +41 -0
  129. package/dist/engine/session/session.js +1 -1
  130. package/dist/engine/session/storage-base.d.ts +20 -0
  131. package/dist/engine/session/storage-base.js +28 -9
  132. package/dist/index.d.ts +9 -8
  133. package/dist/index.js +4 -4
  134. package/dist/internal/harness.d.ts +4 -3
  135. package/dist/internal/harness.js +3 -2
  136. package/dist/orchestration/run-workflow-tool.d.ts +3 -0
  137. package/dist/orchestration/run-workflow-tool.js +27 -11
  138. package/dist/orchestration/workflow-governance.d.ts +1 -1
  139. package/dist/orchestration/workflow.d.ts +3 -0
  140. package/dist/orchestration/workflow.js +2 -7
  141. package/dist/stores/file/checkpoint-store.d.ts +2 -0
  142. package/dist/stores/file/checkpoint-store.js +7 -6
  143. package/dist/stores/file/fs-atomic.d.ts +0 -22
  144. package/dist/stores/file/fs-atomic.js +0 -17
  145. package/dist/stores/file/index.d.ts +2 -9
  146. package/dist/stores/file/index.js +2 -4
  147. package/dist/stores/file/session-store.d.ts +13 -7
  148. package/dist/stores/file/session-store.js +40 -17
  149. package/dist/tools/fs/bash-program-position.d.ts +3 -2
  150. package/dist/tools/fs/bash-program-position.js +7 -7
  151. package/dist/tools/fs/removal-targets.js +2 -2
  152. package/dist/tools/fs/shell-read-argv.d.ts +4 -2
  153. package/dist/tools/fs/shell-read-argv.js +14 -3
  154. package/dist/tools/fs/shell-read-bindings.d.ts +18 -2
  155. package/dist/tools/fs/shell-read-bindings.js +148 -68
  156. package/dist/tools/fs/shell-read-check.js +20 -4
  157. package/dist/tools/fs/shell-read-establish.js +22 -8
  158. package/dist/tools/fs/shell-read-functions.js +2 -2
  159. package/dist/tools/fs/shell-read-object-path.d.ts +59 -0
  160. package/dist/tools/fs/shell-read-object-path.js +119 -0
  161. package/dist/tools/fs/shell-read-plan.d.ts +8 -0
  162. package/dist/tools/fs/shell-read-plan.js +47 -30
  163. package/dist/tools/fs/shell-read-start.d.ts +66 -13
  164. package/dist/tools/fs/shell-read-start.js +89 -17
  165. package/dist/tools/fs/shell-read-workdir.d.ts +29 -8
  166. package/dist/tools/fs/shell-read-workdir.js +31 -8
  167. package/package.json +2 -2
  168. package/test/export-surface.snapshot.json +21 -33
  169. package/wire-changes/core-stores-sql@7.62.0.json +30 -0
  170. package/wire-changes/core@7.62.0.json +2181 -0
  171. package/wire-changes/mods-kernel@7.62.0.json +42 -0
  172. package/wire-changes/primitives@7.62.0.json +30 -0
  173. package/dist/core/consolidate-scope.d.ts +0 -93
  174. package/dist/core/consolidate-scope.js +0 -98
  175. package/dist/core/runner/memory-consolidation.d.ts +0 -109
  176. package/dist/core/runner/memory-consolidation.js +0 -251
@@ -742,6 +742,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
742
742
  ...(opts.placementRoot !== undefined ? { placementRoot: opts.placementRoot } : {}),
743
743
  ...(opts.placementTarget !== undefined ? { placementTarget: opts.placementTarget } : {}),
744
744
  ...(opts.crossBoundaryTree !== undefined ? { crossBoundaryTree: opts.crossBoundaryTree } : {}),
745
+ ...(opts.delegationOwner !== undefined ? { delegationOwner: opts.delegationOwner } : {}),
745
746
  ...(opts.originatingSessionId !== undefined ? { parentSessionId: opts.originatingSessionId } : {}),
746
747
  };
747
748
  const captureFloorSeatsNow = async () => {
@@ -2782,13 +2783,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
2782
2783
  run.error = egressThrownText("same-principal", err);
2783
2784
  closeAbandonedAgents(run.endedAt);
2784
2785
  {
2785
- let thrownCode;
2786
- try {
2787
- thrownCode = err !== null && (typeof err === "object" || typeof err === "function") ? err.code : undefined;
2788
- }
2789
- catch {
2790
- thrownCode = undefined;
2791
- }
2786
+ const thrownCode = readMember(err, "code");
2792
2787
  const firstFailed = run.agents
2793
2788
  .filter((a) => a.status === "failed" && typeof a.errorCode === "string" && a.errorCode !== "")
2794
2789
  .sort((a, b) => (a.endedAt ?? Number.POSITIVE_INFINITY) - (b.endedAt ?? Number.POSITIVE_INFINITY))[0];
@@ -174,6 +174,8 @@ export declare class FileCheckpointStore implements CheckpointStore {
174
174
  private readonly ledger;
175
175
  private closed;
176
176
  private get cps();
177
+ /** The listing's memo of each replayed row object's verdict: a put or a replay holds a new object, so a replaced row is judged again. */
178
+ private readonly rowVerdicts;
177
179
  /** One-shot crash fault (mirrors `InMemoryCheckpointStore.testInjectFault`). */
178
180
  private fault;
179
181
  /** The guarded {@link FileCheckpointStoreOptions.onCorruptRead} seat (the ledger's replay and this store's projection share it). */
@@ -1,10 +1,10 @@
1
1
  import { join } from "node:path";
2
2
  import { assertAdoptionBootGate } from "./adoption/marker.js";
3
- import { optionKeys, receiveOptions } from "../../core/own-property-receipt.js";
3
+ import { memberPresent, optionKeys, receiveOptions } from "../../core/own-property-receipt.js";
4
4
  import { readLedgerTuning } from "./ledger-tuning.js";
5
5
  import { checkpointExecutionRecorded, executionRecordDisposition, ExecutionOutcomeConflictError, } from "../../core/checkpoint-execution-record.js";
6
6
  import { checkpointHolderMatches, checkpointOccMatches, checkpointRevOf } from "../../core/checkpoint-generation.js";
7
- import { appendPendingSteer, CheckpointError, checkpointRowMatches, encodeAtFidelity, summarizeCheckpoint, validatePendingSteer, winnerFromOutcome, } from "../../core/checkpoint-store.js";
7
+ import { appendPendingSteer, CheckpointError, checkpointRowMatches, encodeAtFidelity, summarizeStoredCheckpoint, validatePendingSteer, winnerFromOutcome, } from "../../core/checkpoint-store.js";
8
8
  import { checkpointDeadlinePassed, deleteSessionRowsAtStart, readCheckpointOverdueQuery, readCheckpointSessionQuery, selectOverduePage, selectSessionPage, } from "../../core/checkpoint-queries.js";
9
9
  import { readLedgerSettled, SharedLedgerTable } from "./shared-ledger.js";
10
10
  import { guardCorruptSink } from "./corrupt-read-sink.js";
@@ -27,9 +27,9 @@ function applyCheckpointEvent(cps, ev) {
27
27
  case "resolve":
28
28
  cp.status = "resolved";
29
29
  cp.rev = ev.rev;
30
- if (ev.resolvedOutcome !== undefined)
30
+ if (memberPresent(ev, "resolvedOutcome"))
31
31
  cp.resolvedOutcome = ev.resolvedOutcome;
32
- cp.reopenReason = undefined;
32
+ delete cp.reopenReason;
33
33
  break;
34
34
  case "reopen":
35
35
  cp.status = "pending";
@@ -103,6 +103,7 @@ export class FileCheckpointStore {
103
103
  get cps() {
104
104
  return this.ledger.rows;
105
105
  }
106
+ rowVerdicts = new WeakMap();
106
107
  fault = null;
107
108
  discloseCorrupt;
108
109
  ledgerPath;
@@ -255,7 +256,7 @@ export class FileCheckpointStore {
255
256
  const out = [];
256
257
  for (const cp of this.cps.values()) {
257
258
  if (cp.scope === scope && cp.status === "pending")
258
- out.push(summarizeCheckpoint(cp, disclose));
259
+ out.push(summarizeStoredCheckpoint(cp, this.rowVerdicts, disclose));
259
260
  }
260
261
  return out;
261
262
  }
@@ -272,7 +273,7 @@ export class FileCheckpointStore {
272
273
  }
273
274
  async listOverdue(query) {
274
275
  const disclose = this.listingDisclose();
275
- return selectOverduePage(this.cps.entries(), readCheckpointOverdueQuery(query), (cp) => summarizeCheckpoint(cp, disclose), disclose);
276
+ return selectOverduePage(this.cps.entries(), readCheckpointOverdueQuery(query), (cp) => summarizeStoredCheckpoint(cp, this.rowVerdicts, disclose), disclose);
276
277
  }
277
278
  async listBySession(query) {
278
279
  return selectSessionPage(this.cps.entries(), readCheckpointSessionQuery(query), (cp) => structuredClone(cp), this.listingDisclose());
@@ -374,28 +374,6 @@ export declare function acquireStoreDirLock(dir: string, opts: {
374
374
  label: string;
375
375
  fileName?: string;
376
376
  }): StoreDirLockLease;
377
- /**
378
- * design/84 Seam B (TOC profile) — a per-scope CONSOLIDATION lock factory for the file backend's
379
- * {@link import("../../core/consolidate-scope.js").ConsolidateScopeDeps.acquire} injection point. A single
380
- * machine may run a periodic-consolidation timer AND a task-end inline pass concurrently; this advisory lock
381
- * stops two processes consolidating the SAME scope at once (the in-process model the file backend assumes —
382
- * see {@link BootLock} — does not cover a second OS process with its own timer).
383
- *
384
- * `acquire(scope)` takes a {@link BootLock} over `lockDir/<sanitizedScope>.consolidate.lock`. It returns a
385
- * `release` callback on success, or `undefined` for EVERY refusal that lock knows how to make — a live
386
- * owner (including this process: a second pass here is still a conflict), a takeover in flight, an
387
- * unreadable file — because the caller's whole vocabulary is "busy → skip this pass", a no-op that costs
388
- * one deferred consolidation. A stale lock is reclaimed by the same protocol as any other, which is the
389
- * point of not hand-rolling one: this factory used to prune with a bare `unlink` and re-publish, and two
390
- * passes that had both read the same dead owner would then both prune and both publish — one deleting the
391
- * other's fresh lock, leaving two processes consolidating the SAME scope, which is exactly what the lock
392
- * exists to prevent. The reclaim gate serialises that, the depth cap bounds it, and the identity re-read
393
- * makes sure a reclaim prunes the owner it came for. One lock MECHANISM in this family, not two.
394
- *
395
- * The implementation lives HERE (the deployment shell's persist/exec axis), NOT core — core only DEFINES
396
- * the injection point (the constitutional split: gate-presence in core, mechanism in the profile).
397
- */
398
- export declare function createFileConsolidationLock(lockDir: string): (scope: string) => (() => void) | undefined;
399
377
  /**
400
378
  * A process identity that survives PID REUSE: a pid, WHEN that pid's process started, and the host the
401
379
  * observation was made on.
@@ -717,23 +717,6 @@ export function acquireStoreDirLock(dir, opts) {
717
717
  heldStoreDirLocks.set(key, entry);
718
718
  return lease(entry);
719
719
  }
720
- export function createFileConsolidationLock(lockDir) {
721
- return (scope) => {
722
- ensureDir(lockDir);
723
- const lock = new BootLock(join(lockDir, `${sanitizeScope(scope)}.consolidate.lock`));
724
- try {
725
- lock.acquire();
726
- }
727
- catch (err) {
728
- if (err instanceof FileStoreLockError)
729
- return undefined;
730
- throw err;
731
- }
732
- return () => {
733
- lock.release();
734
- };
735
- };
736
- }
737
720
  function isProcessRunning(pid) {
738
721
  try {
739
722
  process.kill(pid, 0);
@@ -24,7 +24,7 @@ export { FileFileHistoryStore, type FileFileHistoryStoreOptions } from "./file-h
24
24
  export { FileWorkflowJournalStore } from "./workflow-journal-store.js";
25
25
  export { MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult } from "../../core/workflow-journal-store.js";
26
26
  export { FileUsageWindowStore, type FileUsageWindowStoreOptions } from "./usage-window-store.js";
27
- export { resolveDataRoot, sanitizeScope, sanitizePathComponent, createFileConsolidationLock } from "./fs-atomic.js";
27
+ export { resolveDataRoot, sanitizeScope, sanitizePathComponent } from "./fs-atomic.js";
28
28
  export { FileStoreLockError, type FileStoreLockErrorCode } from "./fs-atomic.js";
29
29
  export { atomicWriteFile, writeThenLink, ensureDir, readJsonlRecords, AppendLog } from "./fs-atomic.js";
30
30
  export { processFingerprint, isProcessLive, type ProcessFingerprint } from "./fs-atomic.js";
@@ -34,7 +34,7 @@ export { adoptLocalDataRoot, ackAdoptionConfig, witnessAdoptionConfig, listAdopt
34
34
  * design/80 — the file-backed {@link EngineStorageBackend} for the local (TOC) single-user binary, selected
35
35
  * purely by what the embedder injects into `RunnerDeps` (no engine change). Construct one over a single data
36
36
  * root and pass its members into the `RunnerDeps` seats of the same names (every member of the contract is
37
- * one; the class's extra members — `root`, `memoryStore`, `consolidationLock` — are not seats):
37
+ * one; the class's extra members — `root`, `memoryStore` — are not seats):
38
38
  *
39
39
  * ```ts
40
40
  * const backend = new FileStorageBackend(); // ~/.ai-agent (or $AGENT_DATA_DIR)
@@ -170,13 +170,6 @@ export declare class FileStorageBackend implements EngineStorageBackend {
170
170
  * never edited are structurally out of reach of a restore.
171
171
  */
172
172
  readonly fileHistoryStore: FileHistoryStore;
173
- /**
174
- * design/84 Seam B (TOC) — the per-scope consolidation lock for `consolidateScope`'s `acquire` injection
175
- * point: `consolidateScope(scope, { store: backend.memoryStore, llm, acquire: backend.consolidationLock })`.
176
- * Stops two OS processes sharing this data dir from consolidating the SAME scope at once (a busy scope ⇒
177
- * `undefined` ⇒ the pass is a no-op). The locks live under `root/consolidation-locks/`.
178
- */
179
- readonly consolidationLock: (scope: string) => (() => void) | undefined;
180
173
  private readonly lock;
181
174
  private readonly fileAgentRows;
182
175
  private readonly fileMailbox;
@@ -1,7 +1,7 @@
1
1
  import { join } from "node:path";
2
2
  import { guardedMemoryStore } from "../../core/memory.js";
3
3
  import { STORE_HOOK_KEYS, TtlSessionStore } from "../../core/session-store.js";
4
- import { BootLock, createFileConsolidationLock, resolveDataRoot } from "./fs-atomic.js";
4
+ import { BootLock, resolveDataRoot } from "./fs-atomic.js";
5
5
  import { assertAdoptionBootGate } from "./adoption/marker.js";
6
6
  import { FileCheckpointStore } from "./checkpoint-store.js";
7
7
  import { readLedgerTuning } from "./ledger-tuning.js";
@@ -30,7 +30,7 @@ export { FileFileHistoryStore } from "./file-history-store.js";
30
30
  export { FileWorkflowJournalStore } from "./workflow-journal-store.js";
31
31
  export { MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult } from "../../core/workflow-journal-store.js";
32
32
  export { FileUsageWindowStore } from "./usage-window-store.js";
33
- export { resolveDataRoot, sanitizeScope, sanitizePathComponent, createFileConsolidationLock } from "./fs-atomic.js";
33
+ export { resolveDataRoot, sanitizeScope, sanitizePathComponent } from "./fs-atomic.js";
34
34
  export { FileStoreLockError } from "./fs-atomic.js";
35
35
  export { atomicWriteFile, writeThenLink, ensureDir, readJsonlRecords, AppendLog } from "./fs-atomic.js";
36
36
  export { processFingerprint, isProcessLive } from "./fs-atomic.js";
@@ -53,7 +53,6 @@ export class FileStorageBackend {
53
53
  mailboxStore;
54
54
  rosterStore;
55
55
  fileHistoryStore;
56
- consolidationLock;
57
56
  lock;
58
57
  fileAgentRows;
59
58
  fileMailbox;
@@ -110,7 +109,6 @@ export class FileStorageBackend {
110
109
  this.mailboxStore = this.fileMailbox;
111
110
  this.rosterStore = new FileRosterStore(join(this.root, "roster.json"), corruptRead ?? {});
112
111
  this.fileHistoryStore = new FileFileHistoryStore(this.root, { ...fileHistoryOptions, ...(corruptRead ?? {}) });
113
- this.consolidationLock = createFileConsolidationLock(join(this.root, "consolidation-locks"));
114
112
  }
115
113
  catch (err) {
116
114
  for (const undo of built.reverse()) {
@@ -9,7 +9,8 @@ export interface FileSessionRepoOptions {
9
9
  *
10
10
  * Fires for: an unreadable sessions DIRECTORY (the listing degrades to "no sessions"), a session log
11
11
  * whose header could not be read during a listing (skipped from the result — a listing reads headers,
12
- * it never replays a log), and each corrupt interior JSONL record dropped on replay plus that replay's
12
+ * it never replays a log; a PLACED row whose owner cell alone is unreadable is not skipped — the placed listing lists it — and is
13
+ * disclosed as that), and each corrupt interior JSONL record dropped on replay plus that replay's
13
14
  * tally (turns missing from an otherwise healthy session).
14
15
  *
15
16
  * Never fires on plain ENOENT / `not_found` — that is honest absence, and the torn TAIL stays silent
@@ -41,7 +42,7 @@ export declare class FileSessionRepo implements SessionRepo {
41
42
  * file whose first record is not a meta header → `corrupt_session`, even when every other record is intact
42
43
  * (every write path here lays the header down first and the header alone carries `createdAt` / fork /
43
44
  * placement / owner, so the file is not a session this store wrote, or its header line is damaged);
44
- * otherwise the session, each skipped record disclosed.
45
+ * otherwise the session, each skipped record disclosed, and `loss` = what the replay dropped (absent = nothing).
45
46
  */
46
47
  private read;
47
48
  /**
@@ -51,11 +52,14 @@ export declare class FileSessionRepo implements SessionRepo {
51
52
  * the row). `skipped` words the corrupt-header refusal's reading of the records around it, where the caller has one.
52
53
  */
53
54
  private headerOf;
55
+ /** The header's cells but its owner — what a reader of the row's lane, lineage and occupant needs, each cell through its decoder. */
56
+ private cellsOf;
54
57
  /**
55
58
  * The row's header record, where the log has one: its FIRST record, which must be the meta header every write path lays down. A log whose
56
- * first record is anything else is no row this store wrote — `corrupt_session`, said once here for every reader of the row. The cells
57
- * inside it are each read by their own reader ({@link headerOf} for the whole header, `placementOf` for the placement tuple alone):
58
- * a reader of one cell does not answer for the others.
59
+ * first record is anything else is no row this store wrote — `corrupt_session`, said once here for every reader of the row — and so is one
60
+ * whose placement cell is no placement tuple ({@link readPlacementCell}): the placement is the cell that says which lane the row lives
61
+ * in, so every reader of the row, of any other cell, goes through its judge. The other cells are each read by their own reader
62
+ * ({@link headerOf} for the whole header, `placementOf` for the placement tuple alone): a reader of one cell does not answer for the others.
59
63
  */
60
64
  private metaLineOf;
61
65
  /**
@@ -77,7 +81,8 @@ export declare class FileSessionRepo implements SessionRepo {
77
81
  /**
78
82
  * The row's {@link SessionRow} — its header cells and the newest write it holds, the log's modification time (every write to a row
79
83
  * is an append to its log; the placed listing's age reads the same time) — in one read of the header, never a replay of the log.
80
- * `undefined` = no row; a row whose header cannot be read rejects (`corrupt_session`).
84
+ * `undefined` = no row; a row whose header cannot be read rejects (`corrupt_session`) — except a PLACED row whose only unreadable cell
85
+ * is the owner's, which is {@link OwnerlessPlacedRow}: a listing asks where a row lives and how old it is, not who owns it.
81
86
  */
82
87
  private rowOf;
83
88
  /** The one descriptor a by-id read of the row takes: its size and modification time and its header decoded whole, from one inode (a
@@ -114,7 +119,8 @@ export declare class FileSessionRepo implements SessionRepo {
114
119
  * browse face never throws — but "I could not read the directory" and "there are none" are different facts, and only the sink can
115
120
  * tell them apart (ENOENT is honest absence: the constructor creates the directory, so it was removed underneath us). A session
116
121
  * whose header cannot be read is skipped and disclosed — it exists and is missing from the listing — while a file that vanished
117
- * between the directory read and its own is honest absence.
122
+ * between the directory read and its own is honest absence. A placed row whose owner alone is unreadable is neither skipped nor
123
+ * silent: it is kept (the placed listing lists it) and disclosed, once per listing, in the same sentence whichever listing reads it.
118
124
  */
119
125
  private rows;
120
126
  /**
@@ -1,6 +1,6 @@
1
1
  import { closeSync, existsSync, fstatSync, openSync, readdirSync, rmSync, utimesSync } from "node:fs";
2
2
  import { join } from "node:path";
3
- import { BaseSessionStorage, StoredSession, SessionError, assertForkTarget, compareOccupants, forkRowCells, frozenRow, getEntriesToFork, importRowCells, incarnationCell, leafIdAfterEntry, ownerCell, readIncarnationCell, readOwnerCell, resolveLeafId, rowExpectationMissed, sessionLogMarkOf, sessionRowMatches, uuidv7, validateEntriesForImport, } from "../../internal/harness.js";
3
+ import { BaseSessionStorage, StoredSession, SessionError, assertForkTarget, compareOccupants, forkRowCells, frozenRow, getEntriesToFork, importRowCells, incarnationCell, leafIdAfterEntry, ownerCell, placementCellToWrite, readIncarnationCell, readOwnerCell, readPlacementCell, replayLossText, resolveLeafId, rowExpectationMissed, sessionLogMarkOf, sessionRowMatches, uuidv7, validateEntriesForImport, } from "../../internal/harness.js";
4
4
  import { canonicalStoreKey, AppendLog, atomicWriteFile, ensureDir, firstJsonlRecord, lastJsonlRecord, readJsonlRecords, sanitizePathComponent, writeThenLink } from "./fs-atomic.js";
5
5
  import { guardCorruptSink } from "./corrupt-read-sink.js";
6
6
  import { assertAdoptionBootGate } from "./adoption/marker.js";
@@ -38,8 +38,8 @@ class FileSessionStorage extends BaseSessionStorage {
38
38
  canonicalPath;
39
39
  holders = new Set();
40
40
  occupant;
41
- constructor(log, meta, entries, canonicalPath) {
42
- super(meta, entries);
41
+ constructor(log, meta, entries, canonicalPath, replayLoss) {
42
+ super(meta, entries, undefined, replayLoss !== undefined ? { replayLoss } : undefined);
43
43
  this.log = log;
44
44
  this.canonicalPath = canonicalPath;
45
45
  this.occupant = { incarnation: meta.incarnation };
@@ -104,15 +104,19 @@ export class FileSessionRepo {
104
104
  tally = info;
105
105
  this.onCorruptRead?.({ ...info, sessionId: id });
106
106
  }, SESSION_LINE_JUDGE);
107
- const meta = this.headerOf(id, path, lines[0], () => ` (${tally?.dropped ?? 0} of ${tally?.total ?? lines.length} records skipped as corrupt)`);
107
+ const loss = tally !== undefined ? { dropped: tally.dropped, total: tally.total } : undefined;
108
+ const meta = this.headerOf(id, path, lines[0], () => ` (${replayLossText(loss ?? { dropped: 0, total: lines.length })})`);
108
109
  const entries = [];
109
110
  for (const line of lines)
110
111
  if (line.kind === "entry")
111
112
  entries.push(line.entry);
112
- return { meta, entries };
113
+ return { meta, entries, ...(loss !== undefined ? { loss } : {}) };
113
114
  }
114
115
  headerOf(id, path, first, skipped = () => "") {
115
116
  const head = this.metaLineOf(id, first, skipped);
117
+ return { ...this.cellsOf(id, path, head), owner: readOwnerCell(head.owner, id) };
118
+ }
119
+ cellsOf(id, path, head) {
116
120
  const said = (key) => (detail) => this.disclose(path, `session header ${key}: ${detail}`, id);
117
121
  const incarnation = readIncarnationCell(head.incarnation, said("incarnation"));
118
122
  const forkedFromIncarnation = readIncarnationCell(head.forkedFromIncarnation, said("forkedFromIncarnation"));
@@ -123,13 +127,14 @@ export class FileSessionRepo {
123
127
  ...(head.placement !== undefined ? { placement: head.placement } : {}),
124
128
  ...(incarnation !== undefined ? { incarnation } : {}),
125
129
  ...(forkedFromIncarnation !== undefined ? { forkedFromIncarnation } : {}),
126
- owner: readOwnerCell(head.owner, id),
127
130
  };
128
131
  }
129
132
  metaLineOf(id, first, skipped = () => "") {
130
133
  if (first === undefined || first.kind !== "meta")
131
134
  throw new SessionError("corrupt_session", `Session ${id} is unreadable: its log has no meta header${skipped()}`);
132
- return first;
135
+ const { placement: raw, ...cells } = first;
136
+ const placement = readPlacementCell(raw, id);
137
+ return { ...cells, ...(placement !== undefined ? { placement } : {}) };
133
138
  }
134
139
  async headOf(sessionId) {
135
140
  return this.headNow(sessionId);
@@ -157,7 +162,22 @@ export class FileSessionRepo {
157
162
  return { metadata: meta, head: { owner: meta.owner ?? null, incarnation: meta.incarnation, leafId: resolveLeafId(entries) }, entries };
158
163
  }
159
164
  rowOf(sessionId) {
160
- return this.atRow(sessionId, (_fd, _size, meta, mtimeMs) => ({ ...meta, lastActiveAt: Math.trunc(mtimeMs) }));
165
+ const path = this.pathFor(sessionId);
166
+ return this.atFirstRecord(sessionId, (_fd, _size, first, mtimeMs) => {
167
+ const head = this.metaLineOf(sessionId, first);
168
+ const cells = this.cellsOf(sessionId, path, head);
169
+ const lastActiveAt = Math.trunc(mtimeMs);
170
+ let owner;
171
+ try {
172
+ owner = readOwnerCell(head.owner, sessionId);
173
+ }
174
+ catch (err) {
175
+ if (head.placement === undefined || !(err instanceof SessionError))
176
+ throw err;
177
+ return { id: sessionId, placement: head.placement, lastActiveAt, ownerFault: thrownText(err) };
178
+ }
179
+ return { ...cells, owner, lastActiveAt };
180
+ });
161
181
  }
162
182
  atRow(sessionId, read) {
163
183
  const path = this.pathFor(sessionId);
@@ -181,7 +201,7 @@ export class FileSessionRepo {
181
201
  closeSync(fd);
182
202
  }
183
203
  }
184
- storage(meta, entries) {
204
+ storage(meta, entries, loss) {
185
205
  const { id } = meta;
186
206
  const canonical = canonicalStoreKey(this.pathFor(id));
187
207
  const live = sharedSessionStorages.get(canonical)?.deref();
@@ -193,7 +213,7 @@ export class FileSessionRepo {
193
213
  if (live !== undefined)
194
214
  evictSharedSessionStorage(canonical);
195
215
  const log = new AppendLog(this.pathFor(id));
196
- const created = new FileSessionStorage(log, frozenRow({ ...meta, ...(meta.placement !== undefined ? { placement: { ...meta.placement } } : {}) }), entries, canonical);
216
+ const created = new FileSessionStorage(log, frozenRow({ ...meta, ...(meta.placement !== undefined ? { placement: { ...meta.placement } } : {}) }), entries, canonical, loss);
197
217
  sharedSessionStorages.set(canonical, new WeakRef(created));
198
218
  created.addHolder(this);
199
219
  this.joined.set(canonical, new WeakRef(created));
@@ -218,7 +238,7 @@ export class FileSessionRepo {
218
238
  const path = this.pathFor(id);
219
239
  if (!existsSync(path)) {
220
240
  const owner = ownerCell(options.owner);
221
- const placement = options.placement !== undefined ? { ...options.placement, placedAt: options.placement.placedAt ?? Date.now() } : undefined;
241
+ const placement = placementCellToWrite(options.placement, id, Date.now());
222
242
  const meta = { id, createdAt, ...(placement !== undefined ? { placement } : {}), ...incarnationCell(undefined), ...owner };
223
243
  try {
224
244
  writeThenLink(path, `${JSON.stringify({ kind: "meta", ...meta })}\n`);
@@ -230,12 +250,12 @@ export class FileSessionRepo {
230
250
  }
231
251
  return new StoredSession(this.storage(meta, []));
232
252
  }
233
- const { meta, entries } = this.read(id);
234
- return new StoredSession(this.storage({ ...meta, createdAt: meta.createdAt || createdAt }, entries));
253
+ const { meta, entries, loss } = this.read(id);
254
+ return new StoredSession(this.storage({ ...meta, createdAt: meta.createdAt || createdAt }, entries, loss));
235
255
  }
236
256
  async open(metadata) {
237
- const { meta, entries } = this.read(metadata.id);
238
- return new StoredSession(this.storage(meta, entries));
257
+ const { meta, entries, loss } = this.read(metadata.id);
258
+ return new StoredSession(this.storage(meta, entries, loss));
239
259
  }
240
260
  async touch(sessionId) {
241
261
  const now = new Date();
@@ -277,8 +297,11 @@ export class FileSessionRepo {
277
297
  this.disclose(this.pathFor(id), `session log unreadable (${thrownText(err)}) — skipped from ${listing}`, id);
278
298
  continue;
279
299
  }
280
- if (row !== undefined)
281
- out.push(row);
300
+ if (row === undefined)
301
+ continue;
302
+ if ("ownerFault" in row)
303
+ this.disclose(this.pathFor(id), `session log is a placed row whose owner cell is unreadable (${row.ownerFault}) — the placed listing lists it, the host listing never does`, id);
304
+ out.push(row);
282
305
  }
283
306
  return out;
284
307
  }
@@ -106,8 +106,9 @@ export interface ProgramPosition {
106
106
  readonly refusal: ProgramPositionRefusal | undefined;
107
107
  /** A launcher of the chain moves the directory or the root the program runs in, or where its word is looked up
108
108
  * (`env -C <dir>`, `sudo -R <dir>`, `env -P <dirs>`): the program is still the word it names, but where its path
109
- * operands resolve is not the command line's working directory — each consumer reads that as it must. */
110
- readonly launcherMovesBase: boolean;
109
+ * operands resolve is not the command line's working directory — each consumer reads that as it must. The argv index of
110
+ * each such option word the walk stepped, in order (its value is that word's rest or the next word); empty: none moves. */
111
+ readonly baseMovedAt: readonly number[];
111
112
  }
112
113
  /**
113
114
  * Read the program position of one segment's argv words.
@@ -49,7 +49,7 @@ function pastLauncherOptions(launcher, folded, i, moved, queried, ended) {
49
49
  if (step === 2 && folded[i + 1] === undefined)
50
50
  return i;
51
51
  if (launcherOptionMovesBase(row, tok))
52
- moved?.();
52
+ moved?.(i);
53
53
  if (launcherOptionQueries(row, tok))
54
54
  queried?.();
55
55
  i += step;
@@ -72,7 +72,7 @@ export function readProgramPosition(words) {
72
72
  controlWords.push(i);
73
73
  i = pastLauncherOptions(controlWord, folded, i + 1);
74
74
  }
75
- const none = (written, assignments, refusal) => ({ controlWords, written, assignments, launchers: [], argvFromStdin: false, runsDefaultProgram: false, program: undefined, refusal, launcherMovesBase: false });
75
+ const none = (written, assignments, refusal) => ({ controlWords, written, assignments, launchers: [], argvFromStdin: false, runsDefaultProgram: false, program: undefined, refusal, baseMovedAt: [] });
76
76
  const globProgramRefusal = (idx) => {
77
77
  let glob = false;
78
78
  for (const p of words[idx].pieces) {
@@ -110,26 +110,26 @@ export function readProgramPosition(words) {
110
110
  const glob = globProgramRefusal(i);
111
111
  if (glob !== undefined)
112
112
  return none(written, assignments, glob);
113
- return { controlWords, written, assignments, launchers: [], argvFromStdin: false, runsDefaultProgram: false, program: { index: i, name: head, basename }, refusal: undefined, launcherMovesBase: false };
113
+ return { controlWords, written, assignments, launchers: [], argvFromStdin: false, runsDefaultProgram: false, program: { index: i, name: head, basename }, refusal: undefined, baseMovedAt: [] };
114
114
  }
115
115
  const launchers = [{ index: i, name: basename }];
116
116
  const owner = head;
117
117
  const shellRefusal = (launcher, from) => ({ kind: "control_syntax_at_program_position", owner, word: "sh", runsShell: { launcher, from } });
118
118
  let lastRow = launcherRowOf(basename)?.launcher;
119
119
  let owedOperands = lastRow?.requiredOperands ?? 0;
120
- const chain0 = (program, refusal) => ({ controlWords, written, assignments, launchers, argvFromStdin: false, runsDefaultProgram: false, program, refusal, launcherMovesBase: false });
120
+ const chain0 = (program, refusal) => ({ controlWords, written, assignments, launchers, argvFromStdin: false, runsDefaultProgram: false, program, refusal, baseMovedAt: [] });
121
121
  if (launcherRunsShell(launcherRowOf(basename), folded.slice(i + 1)))
122
122
  return chain0(undefined, shellRefusal(i, i + 1));
123
123
  let argvFromStdin = feedsArgvFromStdin(basename);
124
124
  let lastReentry = argvFromStdin ? i : -1;
125
125
  let reentryDefault = argvFromStdin ? streamDefaultProgram(basename) : undefined;
126
- let launcherMovesBase = false;
127
- const moved = () => { launcherMovesBase = true; };
126
+ const baseMovedAt = [];
127
+ const moved = (at) => { baseMovedAt.push(at); };
128
128
  let looksUp = false;
129
129
  const queried = () => { looksUp = true; };
130
130
  const chain = (program, refusal) => {
131
131
  const runsDefaultProgram = lastReentry === folded.length - 1;
132
- return { controlWords, written, assignments, launchers, argvFromStdin, runsDefaultProgram, ...(runsDefaultProgram && reentryDefault !== undefined ? { defaultProgram: reentryDefault } : {}), program, refusal, launcherMovesBase };
132
+ return { controlWords, written, assignments, launchers, argvFromStdin, runsDefaultProgram, ...(runsDefaultProgram && reentryDefault !== undefined ? { defaultProgram: reentryDefault } : {}), program, refusal, baseMovedAt };
133
133
  };
134
134
  const selectsShell = (l, end) => selectedOptions(launcherRowOf(l.name), folded.slice(l.index + 1, end)).some((o) => o.mode === "interactive");
135
135
  const first = pastLauncherOptions(basename, folded, i + 1, moved, queried, endsOptions(basename));
@@ -108,7 +108,7 @@ export function removalFindingsOf(established, seat, safeRoots = KNOWN_SAFE_ROOT
108
108
  const rm = removal.program === "rm" || !named ? { recursive: selectsOptions(row, spelled, received.shellChooses, TRAVERSAL) } : undefined;
109
109
  if (forced && segment.reentry === "argv")
110
110
  out.push({ guard: "unverifiable_delete", program: removal.program, operand: segment.text.trim(), source: "stream" });
111
- const relocated = enclosingRelocated || readProgramPosition(segment.argv).launcherMovesBase;
111
+ const relocated = enclosingRelocated || readProgramPosition(segment.argv).baseMovedAt.length > 0;
112
112
  for (const read of established.reads.get(segment) ?? []) {
113
113
  if ((named && read.candidate.face !== "write") || read.candidate.provenance === "program_path" || options.has(read.candidate.raw))
114
114
  continue;
@@ -133,7 +133,7 @@ export function removalFindingsOf(established, seat, safeRoots = KNOWN_SAFE_ROOT
133
133
  out.push({ guard: "unverifiable_shell_text", program, text: script, source: "produced" });
134
134
  if (programUnread(segment))
135
135
  out.push({ guard: "unverifiable_shell_text", program: segment.launcherChain[0] ?? segment.text.trim(), text: segment.text.trim(), source: "position" });
136
- const handedRelocated = enclosingRelocated || readProgramPosition(segment.argv).launcherMovesBase;
136
+ const handedRelocated = enclosingRelocated || readProgramPosition(segment.argv).baseMovedAt.length > 0;
137
137
  for (const nested of segment.nested) {
138
138
  if (unreadPlan(nested)) {
139
139
  out.push({ guard: "unverifiable_shell_text", program: program ?? segment.text.trim(), text: segment.text.trim(), source: "unread" });
@@ -10,10 +10,12 @@ import { type Read } from "./shell-read-word.js";
10
10
  import { type BindingTable, type FloorValue } from "./shell-read-bindings.js";
11
11
  import { subcommandOf, type ArgRole, type ProgramRow } from "./program-read-model.js";
12
12
  import type { ReadCandidate, ReadCandidateProvenance } from "./shell-read-plan.js";
13
+ import { type ObjectPathRepository } from "./shell-read-object-path.js";
13
14
  /** A candidate before the threading fills its bases. `floors`: the spellings its word's names left for the deny judge
14
- * alone (a word whose names are unknown here). */
15
+ * alone (a word whose names are unknown here); `repository`: an object path's, what the program's options say of it. */
15
16
  export type Bare = Omit<ReadCandidate, "bases"> & {
16
17
  readonly floors?: readonly FloorValue[];
18
+ readonly repository?: ObjectPathRepository;
17
19
  };
18
20
  /** What reading a segment's words found beside its candidates. */
19
21
  export interface WordContext {
@@ -61,7 +63,7 @@ export declare function roleReads(r: Read, provenance: ReadCandidateProvenance,
61
63
  * NAME makes it the whole value, so it is a candidate too. A value that is a substitution is the nested plan
62
64
  * its body already is, never a candidate of its own text (its placeholder is not a path).
63
65
  */
64
- export declare function pushAssignment(reads: Bare[], w: LexedWord, provenance: ReadCandidateProvenance): void;
66
+ export declare function pushAssignment(reads: Bare[], w: LexedWord, provenance: ReadCandidateProvenance, bound?: boolean): void;
65
67
  /** Every word of a segment whose program's grammar this parser does not model, from `from` onward: option
66
68
  * payloads and path-shaped option words included, the launcher chain's own words excluded, a program declared
67
69
  * to open no path operand handing only the environment words in front of it. A program with NO row is read the
@@ -1,8 +1,15 @@
1
1
  import { literalTildeSpelling } from "../../shell/lex.js";
2
2
  import { expandsOf, partPattern, readOfText, rewritten } from "./shell-read-word.js";
3
- import { arithmeticSubstitutions } from "./shell-read-bindings.js";
3
+ import { arithmeticSubstitutions, bindsArrayElement } from "./shell-read-bindings.js";
4
4
  import { argvProgramOf, attachedOptionPayloads, isPathShapedToken } from "./bash-readonly-classifier.js";
5
5
  import { assignmentArgumentsAreNotPaths, deliversOperands, evaluatesOperands, messageWords, moduleTailOf, objectPathsOf, opensNoOperand, programRow, programTextMayOpen, programTextOpensOf, readArgs, readOptionSlot, selectsContentsTraversal, slotValueCandidates, subcommandOf, valuesAreLiteral, walksCwdWithoutOperand, wordsReadBySomeImplementations, } from "./program-read-model.js";
6
+ import { objectPathRepositoryOf } from "./shell-read-object-path.js";
7
+ function inRepository(reads, from, row, globals) {
8
+ let repository;
9
+ for (let i = from; i < reads.length; i++)
10
+ if (reads[i].provenance === "object_path")
11
+ reads[i] = { ...reads[i], repository: (repository ??= objectPathRepositoryOf(row, globals)) };
12
+ }
6
13
  export function pathSubcommandOf(row, args) {
7
14
  const sub = subcommandOf(row, args);
8
15
  return sub !== undefined && (sub.row.operands !== undefined || sub.row.traversal !== undefined) ? sub : undefined;
@@ -162,9 +169,9 @@ function programTextReads(r, provenance, text, language, ctx) {
162
169
  ctx.programText ??= programTextSentence(language);
163
170
  return [{ ...bare(r, provenance, text), denyOnly: true }];
164
171
  }
165
- export function pushAssignment(reads, w, provenance) {
172
+ export function pushAssignment(reads, w, provenance, bound = false) {
166
173
  const a = w.assignment;
167
- if (a === undefined || a.form === "compound")
174
+ if (a === undefined || a.form === "compound" || (bound && bindsArrayElement(a)))
168
175
  return;
169
176
  const expandsTilde = a.value.expansions.some((p) => p.expansion?.kind === "tilde");
170
177
  const value = expandsTilde ? a.value.folded : literalTildeSpelling(a.value.folded);
@@ -300,7 +307,9 @@ export function unlistedWords(reads, toks, from, launcherIndices, provenance, ct
300
307
  gathered.restart();
301
308
  base = new OperandBase();
302
309
  unsettledAt.length = 0;
310
+ const subFrom = reads.length;
303
311
  walk(sub.row, walkFrom, toks.length, true);
312
+ inRepository(reads, subFrom, slotRow, toks.slice(argvStart + 1, argvStart + 1 + sub.at));
304
313
  }
305
314
  else
306
315
  walk(slotRow, argvStart + 1, toks.length, "program-text");
@@ -413,7 +422,9 @@ export function listedVerbCandidates(name, argReads, reads, ctx) {
413
422
  const tail = moduleTailOf(row, args);
414
423
  if (sub !== undefined) {
415
424
  walkListed(row, argReads, 0, sub.at, expanding, reads, ctx, false);
425
+ const from = reads.length;
416
426
  walkListed(sub.row, argReads, sub.at + 1, argReads.length, expanding, reads, ctx, sub.relocated);
427
+ inRepository(reads, from, row, argReads.slice(0, sub.at));
417
428
  }
418
429
  else
419
430
  walkListed(row, argReads, 0, tail !== undefined ? tail.from : argReads.length, expanding, reads, ctx, false);
@@ -27,6 +27,7 @@
27
27
  * The shell's own variables (the ones bash sets, holds read-only or evaluates itself) are never bound from text.
28
28
  */
29
29
  import { type LexedRedirect, type LexedSegment, type LexedToken, type LexedWord } from "../../shell/lex.js";
30
+ import { readProgramPosition } from "./bash-program-position.js";
30
31
  import { type DeclaredAttribute } from "./program-read-model.js";
31
32
  import { type BuiltinState } from "./shell-read-builtins.js";
32
33
  /** A value a name may hold — the text the program receives ({@link spelled}: what a shell re-parsing it reads), literal
@@ -181,14 +182,16 @@ export interface SegmentShape {
181
182
  }
182
183
  /** The argv projection of a lexed segment: structure that names nothing that runs here is dropped — a subshell
183
184
  * parenthesis, a bare `{` / `}`, a function definition's head (`NAME ()`, and `function NAME [()]` with a name of
184
- * any spelling, {@link dropDefinitionHeads}), a `case` arm's pattern ({@link dropCasePattern}), and the block words
185
+ * any spelling, {@link dropDefinitionHeads}), a `case` command's own words ({@link caseWordsOf}), and the block words
185
186
  * at the head. */
186
187
  export interface ProjectedSegment extends SegmentShape {
187
188
  readonly argv: readonly LexedWord[];
188
189
  readonly redirects: readonly LexedRedirect[];
189
190
  readonly grouped: boolean;
190
191
  }
191
- export declare function projectSegment(segment: LexedSegment): ProjectedSegment;
192
+ /** The argv projection of every segment of one text ({@link projectSegment}): a `case` command's own words are read across
193
+ * the segments ({@link caseWordsOf}). */
194
+ export declare function projectSegments(segments: readonly LexedSegment[]): ProjectedSegment[];
192
195
  /** A function definition's head names nothing that runs here and is dropped from a segment's tokens, in place:
193
196
  * `NAME ( )` ({@link isDefinitionName}), and `function NAME [( )]` — a bare `function` at command position, a name of any
194
197
  * spelling. The lexer puts the body's compound command back at command position after the head, so a definition
@@ -240,6 +243,16 @@ export declare function loopListHeadAt(argv: readonly LexedWord[]): number | und
240
243
  * ({@link BuiltinState}) — `disabled`: the word finds no command and binds nothing, `maybe`: as a function that may stand.
241
244
  */
242
245
  export declare function bindingEffectOf(segment: LexedSegment, argv: readonly LexedWord[], shape: SegmentShape, readValue: ValueReader, shadow?: "named" | "maybe", availability?: (builtin: string) => BuiltinState): BindingEffect;
246
+ /** Does this assignment store ARRAY ELEMENTS — a compound value `(…)`, or a subscripted name `a[k]=v`? Bash never exports
247
+ * an array (an element assigned to an exported scalar makes it an array, gone from every child's environment): what it
248
+ * stores reaches a program only through a word that reads an element — the element floor it leaves here ({@link
249
+ * arrayElementFloor}) — never through an environment. One predicate for both spellings. Where the shell may NOT bind the
250
+ * word (a prefix, a launcher's or a declaration builtin's operand) it is handed on as written: the read plan keeps that
251
+ * word's text a candidate. */
252
+ export declare function bindsArrayElement(a: Pick<NonNullable<LexedWord["assignment"]>, "form" | "subscript">): boolean;
253
+ /** Do a segment's leading assignment words stand alone — the shell itself binds them — rather than prefix a command whose
254
+ * environment they are? The binding rule and the read plan's environment candidates ask the same question. */
255
+ export declare function assignsAsStatement(pos: ReturnType<typeof readProgramPosition>): boolean;
243
256
  /**
244
257
  * The names an ARITHMETIC text may assign: every identifier in a text that carries an assignment operator (`=` that is no
245
258
  * comparison, `+=` and its kin, `++`, `--`) — read whole, not parsed: a name only compared there is made unknown too.
@@ -425,6 +438,9 @@ export declare class BindingThread {
425
438
  * scope, so it can). What a reader in ANOTHER body loses ({@link unreadableBy}); a call to the body changes it unless a
426
439
  * declaration the body certainly ran covers the name ({@link functionBound}). */
427
440
  private bodyBinding;
441
+ /** Does what segment `at` does to this shell — a binding it makes where it stands, a move of the working directory —
442
+ * reach a reader at segment `j` (`j` absent: the text's end)? The one visibility rule ({@link visible}). */
443
+ reaches(at: number, j?: number): boolean;
428
444
  /** Does segment `at` stand in a function body (it runs at a call, not here)? */
429
445
  inFunctionBody(at: number): boolean;
430
446
  /** Does segment `at` run in a subshell (a `( … )` group, a pipeline member that is not the last, a background job) or a