@cassiomc1/forgeloop 1.14.0 → 2.0.0-rc.4

package/src/core/ledger-event-collection.js

@@ -0,0 +1,189 @@
+/**
+ * Explicit immutable-source event sequence. This is not an Array or a Proxy.
+ * Readers decode on demand; historical views share only source position identity.
+ * The source owner must hold one immutable snapshot for the sequence's lifetime.
+ * Array-returning filter/map operations deliberately materialize selected proofs;
+ * they do not establish bounded memory for arbitrarily large relation state.
+ */
+const collections = new WeakSet();
+const viewToken = Symbol("ledger-source-view");
+
+function sourceError(message) {
+  return Object.assign(new Error(message), { code: "E_LEDGER_SOURCE_INVALID" });
+}
+
+function integer(value) {
+  const number = Number(value);
+  return Number.isNaN(number) ? 0 : Math.trunc(number);
+}
+
+function bound(value, length) {
+  const index = integer(value);
+  return index < 0 ? Math.max(length + index, 0) : Math.min(index, length);
+}
+
+export class LedgerEventCollection {
+  #source;
+  #start;
+  #end;
+
+  constructor({ length, readAt, iterateRange = null, iterateTypes = null }, view = null, token = null) {
+    if (view) {
+      if (token !== viewToken) throw sourceError("Ledger views must come from their source collection");
+      this.#source = view.source;
+      this.#start = view.start;
+      this.#end = view.end;
+    } else {
+      if (!Number.isSafeInteger(length) || length < 0 || typeof readAt !== "function"
+        || (iterateRange !== null && typeof iterateRange !== "function")
+        || (iterateTypes !== null && typeof iterateTypes !== "function")) {
+        throw sourceError("Ledger source requires a finite length and synchronous readers");
+      }
+      this.#source = { length, readAt, iterateRange, iterateTypes, positions: new WeakMap() };
+      this.#start = 0;
+      this.#end = length;
+    }
+    collections.add(this);
+    Object.freeze(this);
+  }
+
+  get length() { return this.#end - this.#start; }
+
+  #observe(event, index) {
+    if (!event || typeof event !== "object" || Array.isArray(event)) {
+      throw sourceError("Ledger source returned a non-object event");
+    }
+    const known = this.#source.positions.get(event);
+    if (known !== undefined && known !== index) {
+      throw sourceError("Ledger source reused one event object at distinct positions");
+    }
+    this.#source.positions.set(event, index);
+    return event;
+  }
+
+  at(index) {
+    const position = integer(index);
+    const local = position < 0 ? this.length + position : position;
+    if (local < 0 || local >= this.length) return undefined;
+    const absolute = this.#start + local;
+    return this.#observe(this.#source.readAt(absolute), absolute);
+  }
+
+  *values() {
+    if (!this.#source.iterateRange) {
+      for (let index = 0; index < this.length; index += 1) yield this.at(index);
+      return;
+    }
+    let index = this.#start;
+    for (const event of this.#source.iterateRange(this.#start, this.#end)) {
+      if (index >= this.#end) throw sourceError("Ledger source exceeded its declared range");
+      yield this.#observe(event, index);
+      index += 1;
+    }
+    if (index !== this.#end) throw sourceError("Ledger source truncated its declared range");
+  }
+
+  [Symbol.iterator]() { return this.values(); }
+
+  *entries() {
+    let index = 0;
+    for (const event of this) { yield [index, event]; index += 1; }
+  }
+
+  *entriesOfTypes(types) {
+    const selected = new Set(types);
+    if (!this.#source.iterateTypes) {
+      for (const [index, event] of this.entries()) if (selected.has(event.event)) yield [index, event];
+      return;
+    }
+    let previous = this.#start - 1;
+    for (const { index, event } of this.#source.iterateTypes(this.#start, this.#end, [...selected])) {
+      if (!Number.isSafeInteger(index) || index <= previous || index < this.#start || index >= this.#end || !selected.has(event?.event)) {
+        throw sourceError("Ledger typed source returned an invalid position or event type");
+      }
+      previous = index;
+      yield [index - this.#start, this.#observe(event, index)];
+    }
+  }
+
+  slice(start = 0, end = this.length) {
+    const first = bound(start, this.length);
+    const last = Math.max(first, bound(end, this.length));
+    return new LedgerEventCollection({}, { source: this.#source, start: this.#start + first, end: this.#start + last }, viewToken);
+  }
+
+  indexOf(event) {
+    const absolute = event && typeof event === "object" ? this.#source.positions.get(event) : undefined;
+    return absolute === undefined || absolute < this.#start || absolute >= this.#end ? -1 : absolute - this.#start;
+  }
+
+  findIndex(predicate) {
+    for (const [index, event] of this.entries()) if (predicate(event, index, this)) return index;
+    return -1;
+  }
+
+  find(predicate) {
+    for (const [index, event] of this.entries()) if (predicate(event, index, this)) return event;
+    return undefined;
+  }
+
+  findLast(predicate) {
+    for (let index = this.length - 1; index >= 0; index -= 1) {
+      const event = this.at(index);
+      if (predicate(event, index, this)) return event;
+    }
+    return undefined;
+  }
+
+  some(predicate) { return this.findIndex(predicate) !== -1; }
+  every(predicate) { return this.findIndex((event, index) => !predicate(event, index, this)) === -1; }
+
+  filter(predicate) {
+    const selected = [];
+    for (const [index, event] of this.entries()) if (predicate(event, index, this)) selected.push(event);
+    return selected;
+  }
+
+  map(project) {
+    const values = [];
+    for (const [index, event] of this.entries()) values.push(project(event, index, this));
+    return values;
+  }
+}
+
+export function isLedgerEventCollection(events) {
+  return Array.isArray(events) || collections.has(events);
+}
+
+export function ledgerEventAt(events, index) {
+  return Array.isArray(events) ? events[index] : (Number.isSafeInteger(index) && index >= 0 ? events.at(index) : undefined);
+}
+
+/** Preserve strict Array identity; decoded collections prove private source position. */
+export function ledgerEventAtIs(events, index, event) {
+  if (Array.isArray(events)) return events[index] === event;
+  return Number.isSafeInteger(index) && index >= 0 && index < events.length && events.indexOf(event) === index;
+}
+
+/** Typed selection preserves canonical source positions without retaining selected payload arrays. */
+export function* ledgerEntriesOfTypes(events, types) {
+  if (!Array.isArray(events)) { yield* events.entriesOfTypes(types); return; }
+  const selected = new Set(types);
+  for (const [index, event] of events.entries()) if (selected.has(event.event)) yield [index, event];
+}
+
+export function* ledgerEventsOfTypes(events, types) {
+  for (const [, event] of ledgerEntriesOfTypes(events, types)) yield event;
+}
+
+export function ledgerTypeSummary(events, type) {
+  let count = 0;
+  let first;
+  let latest;
+  for (const event of ledgerEventsOfTypes(events, [type])) {
+    if (!count) first = event;
+    latest = event;
+    count += 1;
+  }
+  return { count, first, latest };
+}

package/src/core/ledger-relations.js

@@ -0,0 +1,23 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+const owners = new AsyncLocalStorage();
+
+/** Storage supplies an owned scratch backing; pure/array callers retain native collections. */
+export function withLedgerRelationOwner(owner, callback) { return owners.run(owner, callback); }
+export function ledgerRelationMap() { return owners.getStore()?.map() ?? new Map(); }
+export function ledgerRelationSet() { return owners.getStore()?.set() ?? new Set(); }
+
+
+/** Primitive grouped membership; storage may index groups without nested resident Sets. */
+export function ledgerGroupedSet() {
+  const owner = owners.getStore();
+  if (owner?.groupedSet) return owner.groupedSet();
+  const groups = new Map();
+  return {
+    add(group, value) {
+      if (!groups.has(group)) groups.set(group, new Set());
+      groups.get(group).add(value);
+    },
+    *values(group) { yield* groups.get(group) ?? []; },
+  };
+}

package/src/core/native-storage.js

@@ -0,0 +1,12 @@
+import { needsExistingProjectScope, withExistingProjectScope } from "../storage/existing-project-scope.js";
+import { getOperationalStore } from "../storage/operational-context.js";
+
+export async function withNativeReadScope(target, callback) {
+  return (await needsExistingProjectScope(target)) ? withExistingProjectScope(target, callback, { readOnly: true }) : callback();
+}
+
+export function requireNativeStore(target, errorFactory, refusalMessage) {
+  const store = getOperationalStore(target);
+  if (!store) throw errorFactory("E_STORAGE_MIGRATION_REQUIRED", refusalMessage);
+  return store;
+}

package/src/core/next-action-continuity.js

@@ -1,15 +1,31 @@
 import { ARTIFACT_PATHS } from "./artifacts.js";
 import { reconcileContinuity } from "./continuity-reconciliation.js";
-import { NEXT_ACTIONS, result } from "./next-action-model.js";
+import { directCommandSpec, NEXT_ACTIONS, result } from "./next-action-model.js";
+import { taskArtifactPath } from "./task-paths.js";
 
-const REQUIRED_ARTIFACTS = Object.freeze([ARTIFACT_PATHS.state, ARTIFACT_PATHS.continuity]);
+const SINGLETON_REQUIRED_ARTIFACTS = Object.freeze([ARTIFACT_PATHS.state, ARTIFACT_PATHS.continuity]);
 
-function reason(code, message, artifacts = REQUIRED_ARTIFACTS) {
+function reason(code, message, artifacts = SINGLETON_REQUIRED_ARTIFACTS) {
   return { code, message, artifacts };
 }
 
+function continuityArtifacts(taskId) {
+  if (!taskId) {
+    return {
+      continuity: ARTIFACT_PATHS.continuity,
+      required: SINGLETON_REQUIRED_ARTIFACTS,
+    };
+  }
+  return {
+    continuity: taskArtifactPath(taskId, "continuity"),
+    required: [taskArtifactPath(taskId, "state"), taskArtifactPath(taskId, "continuity")],
+  };
+}
+
 export function nextActionForContinuity({ context, continuity } = {}) {
   if (!continuity || ["ABSENT", "NOT_APPLICABLE"].includes(continuity.classification)) return null;
+  const taskId = context?.taskId ?? null;
+  const artifacts = continuityArtifacts(taskId);
 
   if (continuity.classification === "FRESH") {
     const remaining = continuity.continuity?.remainingWork ?? [];
@@ -20,22 +36,27 @@ export function nextActionForContinuity({ context, continuity } = {}) {
       reasons: [reason(
         "CONTINUITY_REMAINING_WORK",
         `Execution continuity records ${remaining.length} remaining implementation item${remaining.length === 1 ? "" : "s"}.`,
-        [ARTIFACT_PATHS.continuity],
+        [artifacts.continuity],
       )],
-      requiredArtifacts: REQUIRED_ARTIFACTS,
+      requiredArtifacts: artifacts.required,
     });
   }
 
   if (continuity.classification === "RECONCILIATION_REQUIRED") {
+    const command = taskId
+      ? `forgeloop reconcile-continuity --task ${taskId}`
+      : "forgeloop reconcile-continuity";
     return result({
       ...context,
       nextAction: NEXT_ACTIONS.RESOLVE_BLOCKER,
-      commands: ["forgeloop reconcile-continuity"],
+      commands: [command],
+      ...(taskId ? { commandSpecs: [directCommandSpec("reconcile-continuity", taskId)] } : {}),
       reasons: [reason(
         "E_CONTINUITY_RECONCILIATION_REQUIRED",
         "Execution continuity no longer matches canonical state or the current checkout; reconcile it before advancing verification.",
+        artifacts.required,
       )],
-      requiredArtifacts: REQUIRED_ARTIFACTS,
+      requiredArtifacts: artifacts.required,
     });
   }
 
@@ -49,8 +70,9 @@ export function nextActionForContinuity({ context, continuity } = {}) {
       reasons: codes.map((code, index) => reason(
         code,
         continuity.reasons?.[index] ?? `Execution continuity is ${continuity.classification.toLowerCase()}.`,
+        artifacts.required,
       )),
-      requiredArtifacts: REQUIRED_ARTIFACTS,
+      requiredArtifacts: artifacts.required,
     });
   }
 
@@ -60,6 +82,6 @@ export function nextActionForContinuity({ context, continuity } = {}) {
 export async function evaluateContinuityNextAction({ target, packageRoot, context } = {}) {
   return nextActionForContinuity({
     context,
-    continuity: await reconcileContinuity({ target, packageRoot }),
+    continuity: await reconcileContinuity({ target, packageRoot, taskId: context?.taskId ?? null }),
   });
 }

package/src/core/next-action-phases.js

@@ -311,7 +311,7 @@ export async function resolveNextActionPhase({
   const preflightArtifacts = [...requiredArtifacts, preflightRel];
   const persistedPreflightErrors = phaseNeedsChronology
     ? []
-    : validatePersistedPreflight(preflightArtifact.value?.value, preflight);
+    : validatePersistedPreflight(preflightArtifact.value?.value, preflight, preflightArtifact.error);
 
   if (["ROUTED", "DESIGNING", "PLANNED"].includes(state.phase) && missingGates.length > 0) {
     const missingGatePaths = missingGates.map((gate) => taskGatePath(state.taskId, gate));

package/src/core/next-action-review-phase.js

@@ -1,5 +1,5 @@
 import { readJsonArtifact } from "./artifacts.js";
-import { evaluateCompletion } from "./completion.js";
+import { evaluateCompletion, receiptReadFailure } from "./completion.js";
 import { validateReceipt } from "./receipt.js";
 import { completionRelationshipErrors } from "./completion-relationships.js";
 import { evaluateRequiredEvidence, classifyRequirement, terminalRequirementsForContract } from "./evidence-readiness.js";
@@ -82,7 +82,7 @@ export async function resolveReviewingPhase({ state, context, requiredArtifacts,
         return decision(
           context,
           NEXT_ACTIONS.RESOLVE_BLOCKER,
-          artifactError("E_RECEIPT_INVALID", `Repair or remove the invalid execution receipt before continuing: ${receipt.error.message}`, [receiptRel]),
+          receiptReadFailure(receipt.error, receiptRel),
           [...requiredArtifacts, receiptRel],
         );
       }

package/src/core/next-action-verification-phase.js

@@ -1,3 +1,4 @@
+import { receiptReadFailure } from "./completion.js";
 import { readJsonArtifact } from "./artifacts.js";
 import { taskArtifactPath, taskStructuralQualityDirectory } from "./task-paths.js";
 import { validateReceipt } from "./receipt.js";
@@ -100,7 +101,7 @@ export async function resolveVerifyingPhase({ target, packageRoot, explicitTaskI
       return decision(
         context,
         NEXT_ACTIONS.RESOLVE_BLOCKER,
-        artifactError("E_RECEIPT_INVALID", `Repair or remove the invalid execution receipt before continuing: ${receipt.error.message}`, [receiptRel]),
+        receiptReadFailure(receipt.error, receiptRel),
         [...requiredArtifacts, receiptRel],
       );
     }

package/src/core/next-action.js

@@ -15,6 +15,9 @@ import { resolveNextActionPhase } from "./next-action-phases.js";
 import { criterionForDecision } from "./settlement-model.js";
 import { validateApprovalForAction } from "./approvals.js";
 import { evaluateActionCapability } from "./capability-policy.js";
+import { resolveTaskContext, TASK_SELECTION_MODES } from "./task-context.js";
+import { getOperationalStore } from "../storage/operational-context.js";
+import { withProjectReadSnapshot } from "../storage/project-read-snapshot.js";
 
 export { NEXT_ACTIONS } from "./next-action-model.js";
 
@@ -355,9 +358,25 @@ async function computeNextAction(targetOrOptions = {}, packageRootOption) {
 }
 
 export async function getNextAction(targetOrOptions = {}, packageRootOption) {
-  const res = await computeNextAction(targetOrOptions, packageRootOption);
+  const target = typeof targetOrOptions === "string" ? targetOrOptions : targetOrOptions?.target;
+  const read = () => getSelectedNextAction(targetOrOptions, packageRootOption);
+  return target ? withProjectReadSnapshot(target, read) : read();
+}
+
+async function getSelectedNextAction(targetOrOptions, packageRootOption) {
+  let normalized = typeof targetOrOptions === "string"
+    ? { target: targetOrOptions, packageRoot: packageRootOption }
+    : { ...targetOrOptions };
+  if (getOperationalStore(normalized.target)) {
+    const context = await resolveTaskContext(normalized.target, {
+      taskId: normalized.taskId,
+      packageRoot: normalized.packageRoot,
+      selectionMode: TASK_SELECTION_MODES.READ,
+    });
+    if (context) normalized = { ...normalized, taskId: context.taskId };
+  }
+  const res = await computeNextAction(normalized);
   if (res && res.reasons && res.reasons.some((r) => r.code === "E_CONTRACT_UNRESOLVED_DECISION" || r.code === "E_UNRESOLVED_DECISION")) {
-    const normalized = typeof targetOrOptions === "string" ? { target: targetOrOptions, packageRoot: packageRootOption } : targetOrOptions;
     const { target, packageRoot, taskId } = normalized ?? {};
     try {
       const explicitTaskId = taskId ?? null;