@ifc-lite/cli 0.38.2 → 0.39.1

package/README.md

@@ -100,3 +100,5 @@ Determinism: the same model plus the same op sequence yields byte-identical rewa
 ## License
 
 MPL-2.0
+
+Semantic datasets use the same shared profile and provider engine as the viewer. Run `ifc-lite semantic --help` for `validate`, `query`, `assets`, and authenticated HTTPS `serve`; see the [headless semantic guide](https://ifclite.dev/docs/guide/semantic-headless/).

package/dist/commands/flow-ai.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The CLI's AI service for `ai.*` Flow nodes (#6923).
+ *
+ * Opt-in through the environment, never through the graph:
+ *
+ *   IFC_LITE_AI_MODEL     model id sent to the provider (required)
+ *   IFC_LITE_AI_API_KEY   bearer key (required; never logged, never in a checkpoint)
+ *   IFC_LITE_AI_BASE_URL  OpenAI-compatible endpoint, default https://openrouter.ai/api/v1
+ *
+ * Without both required variables the host does not list the `ai` feature,
+ * so a graph with AI nodes fails availability before anything runs. Every
+ * request goes through the shared `@ifc-lite/ai` core against ONE root budget
+ * for the whole run, restored from the checkpoint on resume so a pause never
+ * resets what was spent.
+ */
+import { type RootBudget } from '@ifc-lite/ai';
+import { type FlowAiConfig } from '@ifc-lite/ai/chat-completions';
+import { type FlowAiService } from '@ifc-lite/flow-nodes/ai';
+export declare function createCliAiService(config: FlowAiConfig, budget?: RootBudget, transport?: import("@ifc-lite/ai").AiTransport<string>): FlowAiService;
+//# sourceMappingURL=flow-ai.d.ts.map

package/dist/commands/flow-ai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-ai.d.ts","sourceRoot":"","sources":["../../src/commands/flow-ai.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAqC,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAClF,OAAO,EAA4B,KAAK,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAC5F,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAK7E,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,GAAE,UAA6C,EAAE,SAAS,6CAAmC,GAAG,aAAa,CAU3K"}

package/dist/commands/flow-ai.js

@@ -0,0 +1,35 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+/**
+ * The CLI's AI service for `ai.*` Flow nodes (#6923).
+ *
+ * Opt-in through the environment, never through the graph:
+ *
+ *   IFC_LITE_AI_MODEL     model id sent to the provider (required)
+ *   IFC_LITE_AI_API_KEY   bearer key (required; never logged, never in a checkpoint)
+ *   IFC_LITE_AI_BASE_URL  OpenAI-compatible endpoint, default https://openrouter.ai/api/v1
+ *
+ * Without both required variables the host does not list the `ai` feature,
+ * so a graph with AI nodes fails availability before anything runs. Every
+ * request goes through the shared `@ifc-lite/ai` core against ONE root budget
+ * for the whole run, restored from the checkpoint on resume so a pause never
+ * resets what was spent.
+ */
+import { createRootBudget, runModelRequest } from '@ifc-lite/ai';
+import { chatCompletionsTransport } from '@ifc-lite/ai/chat-completions';
+import { FLOW_AI_BUDGET } from '@ifc-lite/flow-nodes/ai';
+const ROUTE_CEILING = 8_192;
+const TIMEOUT_MS = 120_000;
+export function createCliAiService(config, budget = createRootBudget(FLOW_AI_BUDGET), transport = chatCompletionsTransport(config)) {
+    return {
+        model: config.model,
+        request: (call) => runModelRequest({
+            model: config.model, route: 'cli', transport, budget, routeCeiling: ROUTE_CEILING, timeoutMs: TIMEOUT_MS,
+            prepareInput: () => JSON.stringify({ messages: [call.prompt], system: call.system, outputSchema: call.outputSchema }),
+            messages: [call.prompt], system: call.system, promptVersion: call.promptVersion, maxOutputTokens: call.maxOutputTokens, signal: call.signal,
+            outputSchema: call.outputSchema,
+        }),
+    };
+}
+//# sourceMappingURL=flow-ai.js.map

package/dist/commands/flow-ai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-ai.js","sourceRoot":"","sources":["../../src/commands/flow-ai.ts"],"names":[],"mappings":"AAAA;;+DAE+D;AAE/D;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAmB,MAAM,cAAc,CAAC;AAClF,OAAO,EAAE,wBAAwB,EAAqB,MAAM,+BAA+B,CAAC;AAC5F,OAAO,EAAE,cAAc,EAAsB,MAAM,yBAAyB,CAAC;AAE7E,MAAM,aAAa,GAAG,KAAK,CAAC;AAC5B,MAAM,UAAU,GAAG,OAAO,CAAC;AAE3B,MAAM,UAAU,kBAAkB,CAAC,MAAoB,EAAE,SAAqB,gBAAgB,CAAC,cAAc,CAAC,EAAE,SAAS,GAAG,wBAAwB,CAAC,MAAM,CAAC;IAC1J,OAAO;QACL,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,eAAe,CAAC;YACjC,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,UAAU;YACxG,YAAY,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC;YACrH,QAAQ,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,eAAe,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM;YAC3I,YAAY,EAAE,IAAI,CAAC,YAAY;SAChC,CAAC;KACH,CAAC;AACJ,CAAC"}

package/dist/commands/flow-host.d.ts

@@ -9,6 +9,7 @@
  */
 import type { Capability } from '@ifc-lite/extensions';
 import type { FlowHost } from '@ifc-lite/flow-nodes';
+import type { FlowAiService } from '@ifc-lite/flow-nodes/ai';
 import type { IfcDataStore } from '@ifc-lite/parser';
 import { type BimContext } from '@ifc-lite/sdk';
 import { HeadlessBackend } from '../headless-backend.js';
@@ -22,5 +23,5 @@ export interface CliFlowSession {
     /** The model the graph is working on now: the command-line one, or the last one it opened. */
     active(): HeadlessModel;
 }
-export declare function createCliFlowSession(initial: HeadlessModel, networkGrants: readonly Capability[]): CliFlowSession;
+export declare function createCliFlowSession(initial: HeadlessModel, networkGrants: readonly Capability[], ai?: FlowAiService): CliFlowSession;
 //# sourceMappingURL=flow-host.d.ts.map

package/dist/commands/flow-host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flow-host.d.ts","sourceRoot":"","sources":["../../src/commands/flow-host.ts"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAGzD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,8FAA8F;IAC9F,MAAM,IAAI,aAAa,CAAC;CACzB;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,SAAS,UAAU,EAAE,GAAG,cAAc,CAqBjH"}
+{"version":3,"file":"flow-host.d.ts","sourceRoot":"","sources":["../../src/commands/flow-host.ts"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAGzD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,8FAA8F;IAC9F,MAAM,IAAI,aAAa,CAAC;CACzB;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,SAAS,UAAU,EAAE,EAAE,EAAE,CAAC,EAAE,aAAa,GAAG,cAAc,CA0BrI"}

package/dist/commands/flow-host.js

@@ -1,13 +1,16 @@
 /* This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+import { createDataAccessor } from '@ifc-lite/ids/bridge';
 import { createBimContext } from '@ifc-lite/sdk';
 import { HeadlessBackend } from '../headless-backend.js';
 import { parseIfcBytes } from '../loader.js';
-export function createCliFlowSession(initial, networkGrants) {
+export function createCliFlowSession(initial, networkGrants, ai) {
     let active = initial;
     const host = {
         get bim() { return active.bim; },
+        // Present only when the environment names a provider (`flow-ai.ts`).
+        ...(ai ? { ai } : {}),
         // `networkGrants` is always the graph's own declared capabilities: a
         // trusted local run is still not trusted to reach a host the graph never
         // declared (see `FlowHost.networkGrants`).
@@ -17,6 +20,9 @@ export function createCliFlowSession(initial, networkGrants) {
         // csv-match.ts index builder, which needs the raw entity table + mutation
         // view rather than per-ref BimContext accessors (see host.ts's TableAccess).
         tables: (modelId) => active.backend.tableAccess(modelId),
+        // `ids.validate` reads through the same mutation view, so it sees what an
+        // earlier node in the run wrote.
+        idsAccessor: () => createDataAccessor(active.store, undefined, active.backend.tableAccess().mutationView),
         async openModel(bytes, name) {
             const store = await parseIfcBytes(bytes, name);
             const backend = new HeadlessBackend(store, name);

package/dist/commands/flow-host.js.map

@@ -1 +1 @@
-{"version":3,"file":"flow-host.js","sourceRoot":"","sources":["../../src/commands/flow-host.ts"],"names":[],"mappings":"AAAA;;+DAE+D;AAe/D,OAAO,EAAE,gBAAgB,EAAmB,MAAM,eAAe,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAc7C,MAAM,UAAU,oBAAoB,CAAC,OAAsB,EAAE,aAAoC;IAC/F,IAAI,MAAM,GAAG,OAAO,CAAC;IACrB,MAAM,IAAI,GAAa;QACrB,IAAI,GAAG,KAAK,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QAChC,qEAAqE;QACrE,yEAAyE;QACzE,2CAA2C;QAC3C,aAAa;QACb,IAAI,cAAc,KAAK,OAAO,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,SAAS,CAAC,CAAC,CAAC;QACzE,2EAA2E;QAC3E,0EAA0E;QAC1E,6EAA6E;QAC7E,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC;QACxD,KAAK,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI;YACzB,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YAC/C,MAAM,OAAO,GAAG,IAAI,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YACjD,MAAM,GAAG,EAAE,GAAG,EAAE,gBAAgB,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;YAChE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,IAAI,EAAE,CAAC;QAC1D,CAAC;KACF,CAAC;IACF,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC;AACxC,CAAC"}
+{"version":3,"file":"flow-host.js","sourceRoot":"","sources":["../../src/commands/flow-host.ts"],"names":[],"mappings":"AAAA;;+DAE+D;AAgB/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAmB,MAAM,eAAe,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAc7C,MAAM,UAAU,oBAAoB,CAAC,OAAsB,EAAE,aAAoC,EAAE,EAAkB;IACnH,IAAI,MAAM,GAAG,OAAO,CAAC;IACrB,MAAM,IAAI,GAAa;QACrB,IAAI,GAAG,KAAK,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QAChC,qEAAqE;QACrE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrB,qEAAqE;QACrE,yEAAyE;QACzE,2CAA2C;QAC3C,aAAa;QACb,IAAI,cAAc,KAAK,OAAO,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,SAAS,CAAC,CAAC,CAAC;QACzE,2EAA2E;QAC3E,0EAA0E;QAC1E,6EAA6E;QAC7E,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC;QACxD,0EAA0E;QAC1E,iCAAiC;QACjC,WAAW,EAAE,GAAG,EAAE,CAAC,kBAAkB,CAAC,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,YAAY,CAAC;QACzG,KAAK,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI;YACzB,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YAC/C,MAAM,OAAO,GAAG,IAAI,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YACjD,MAAM,GAAG,EAAE,GAAG,EAAE,gBAAgB,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;YAChE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,IAAI,EAAE,CAAC;QAC1D,CAAC;KACF,CAAC;IACF,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC;AACxC,CAAC"}

package/dist/commands/flow-review.d.ts

@@ -0,0 +1,28 @@
+import { type FlowDocument, type RunResult } from '@ifc-lite/flow';
+import { createCheckpoint, graphDigest, type FlowCheckpoint } from '@ifc-lite/flow/checkpoint';
+import { FileCheckpointStore } from '@ifc-lite/flow/checkpoint-file';
+/** Exit code of a run that stopped at a review checkpoint: not a failure, not done. */
+export declare const PAUSED_FOR_REVIEW = 3;
+/** Build the exact portable proposal before persisting model or tracking effects. */
+export declare function preparePause(input: Parameters<typeof createCheckpoint>[0], redaction: ReadonlyMap<string, string>): FlowCheckpoint;
+/** Refuse an existing destination before a resume consumes its approval. */
+export declare function checkPauseDestination(path: string): Promise<void>;
+/** Save the already-validated exact proposal, with atomic collision refusal. */
+export declare function savePause(path: string, checkpoint: FlowCheckpoint): Promise<FlowCheckpoint>;
+export declare function reportPause(checkpoint: FlowCheckpoint, path: string): void;
+export declare function reviewCommand(args: string[], path: string | undefined, json: boolean, approve: string | undefined): Promise<void>;
+/** Ids of the nodes a checkpoint restores. */
+export declare function checkpointNodes(path: string): Promise<string[]>;
+export interface Resume {
+    readonly store: FileCheckpointStore;
+    readonly checkpoint: FlowCheckpoint;
+    readonly owner: string;
+}
+/** Claim a reviewed checkpoint for this process, after recovering an abandoned claim. */
+export declare function claimForResume(path: string, doc: FlowDocument, inputs: Record<string, unknown>, sourceDigest: string, registry: NonNullable<Parameters<typeof graphDigest>[2]>, requiresAiBudget?: boolean): Promise<Resume>;
+export declare function finishResume(resume: Resume, result: RunResult): Promise<FlowCheckpoint>;
+/** A failed persistence step must not turn a consumed claim into completed. */
+export declare function failResume(resume: Resume, message: string): Promise<FlowCheckpoint>;
+/** #7039: checkpoint writes must not alias model outputs or another journal. */
+export declare function checkDistinctDestinations(paths: readonly string[]): Promise<void>;
+//# sourceMappingURL=flow-review.d.ts.map

package/dist/commands/flow-review.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-review.d.ts","sourceRoot":"","sources":["../../src/commands/flow-review.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AACnE,OAAO,EACmD,gBAAgB,EAAoB,WAAW,EAChD,KAAK,cAAc,EAC3E,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAErE,uFAAuF;AACvF,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAcnC,qFAAqF;AACrF,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,cAAc,CAMlI;AAED,4EAA4E;AAC5E,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEvE;AAED,gFAAgF;AAChF,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAIjG;AAED,wBAAgB,WAAW,CAAC,UAAU,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAG1E;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBvI;AAED,8CAA8C;AAC9C,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAMrE;AAED,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,yFAAyF;AACzF,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,CAAC,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,gBAAgB,UAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAehO;AAED,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,cAAc,CAAC,CAM7F;AAED,+EAA+E;AAC/E,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAEzF;AAED,gFAAgF;AAChF,wBAAsB,yBAAyB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBvF"}

package/dist/commands/flow-review.js

@@ -0,0 +1,154 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+/**
+ * `ifc-lite flow` review checkpoints (#6923): pause, review, resume.
+ *
+ *   flow run    <graph> <model> --checkpoint cp.json [--out paused.ifc]   exits 3 when it paused for review
+ *   flow review <cp.json> [--approve <proposal digest> | --reject] [--json]
+ *   flow resume <graph> <model> --checkpoint cp.json [--out done.ifc] [--next-checkpoint cp2.json]
+ *
+ * The approval names the proposal digest the reviewer was shown, so an
+ * approval cannot apply to a proposal it did not see. A resume claims the
+ * checkpoint once (compare-and-swap on the file), checks that the graph,
+ * Player inputs and the model it starts from are the ones the pause
+ * recorded, runs only what was paused (completed nodes are restored, never
+ * re-executed), and records completed or partially committed.
+ */
+import { randomUUID } from 'node:crypto';
+import { restoreRootBudget } from '@ifc-lite/ai';
+import { realpath, stat } from 'node:fs/promises';
+import { dirname, basename, join, resolve } from 'node:path';
+import { approveCheckpoint, checkpointProposal, claimCheckpoint, createCheckpoint, finishCheckpoint, graphDigest, recoverCheckpoint, rejectCheckpoint, updateCheckpoint } from '@ifc-lite/flow/checkpoint';
+import { redactDeep } from '@ifc-lite/flow-nodes';
+import { fatal, printJson } from '../output.js';
+import { FileCheckpointStore } from '@ifc-lite/flow/checkpoint-file';
+/** Exit code of a run that stopped at a review checkpoint: not a failure, not done. */
+export const PAUSED_FOR_REVIEW = 3;
+const LEASE_MS = 10 * 60_000;
+function describe(checkpoint) {
+    const lines = [`checkpoint ${checkpoint.id} (${checkpoint.state}) for "${checkpoint.graphName}"`, `  proposal digest ${checkpoint.proposalDigest}`];
+    for (const [nodeId, ports] of checkpointProposal(checkpoint)) {
+        for (const [port, data] of ports) {
+            const value = data.kind === 'item' ? data.value : data.kind === 'list' ? data.items : Object.fromEntries(data.branches);
+            lines.push(`  ${nodeId}.${port}: ${JSON.stringify(value)}`);
+        }
+    }
+    return lines;
+}
+/** Build the exact portable proposal before persisting model or tracking effects. */
+export function preparePause(input, redaction) {
+    const checkpoint = createCheckpoint(input);
+    if (JSON.stringify(checkpoint.outputs) !== JSON.stringify(redactDeep(checkpoint.outputs, redaction))) {
+        throw new Error('the paused outputs contain a secret; no checkpoint can be saved or displayed');
+    }
+    return checkpoint;
+}
+/** Refuse an existing destination before a resume consumes its approval. */
+export async function checkPauseDestination(path) {
+    if (await stat(path).then(() => true, () => false))
+        throw new Error(`${path} already exists; a checkpoint is never overwritten`);
+}
+/** Save the already-validated exact proposal, with atomic collision refusal. */
+export async function savePause(path, checkpoint) {
+    await checkPauseDestination(path);
+    if (!(await new FileCheckpointStore(path).write(checkpoint, null)))
+        throw new Error(`${path} is being written by another process`);
+    return checkpoint;
+}
+export function reportPause(checkpoint, path) {
+    for (const line of describe(checkpoint))
+        process.stdout.write(`${line}\n`);
+    process.stdout.write(`paused for review: approve with\n  ifc-lite flow review ${path} --approve ${checkpoint.proposalDigest}\n`);
+}
+export async function reviewCommand(args, path, json, approve) {
+    if (!path)
+        fatal('Usage: ifc-lite flow review <checkpoint.json> [--approve <proposal digest> | --reject] [--json]');
+    const store = new FileCheckpointStore(path);
+    const { checkpoint } = await store.load();
+    const reject = args.includes('--reject');
+    if (approve !== undefined && reject)
+        fatal('pass either --approve or --reject');
+    let next = checkpoint;
+    try {
+        if (approve !== undefined)
+            next = await updateCheckpoint(store, checkpoint.id, (c) => approveCheckpoint(c, approve));
+        else if (reject)
+            next = await updateCheckpoint(store, checkpoint.id, (c) => rejectCheckpoint(c));
+    }
+    catch (error) {
+        fatal(error.message);
+    }
+    if (json)
+        return printJson({ id: next.id, state: next.state, proposalDigest: next.proposalDigest, reviewNodes: next.reviewNodes,
+            proposal: Object.fromEntries([...checkpointProposal(next).keys()].map(node => [node, next.outputs[node]])) });
+    for (const line of describe(next))
+        process.stdout.write(`${line}\n`);
+}
+/** Ids of the nodes a checkpoint restores. */
+export async function checkpointNodes(path) {
+    try {
+        return Object.keys((await new FileCheckpointStore(path).load()).checkpoint.outputs);
+    }
+    catch (error) {
+        fatal(`cannot read checkpoint ${path}: ${error.message}`);
+    }
+}
+/** Claim a reviewed checkpoint for this process, after recovering an abandoned claim. */
+export async function claimForResume(path, doc, inputs, sourceDigest, registry, requiresAiBudget = false) {
+    const store = new FileCheckpointStore(path);
+    const owner = `cli:${process.pid}:${randomUUID()}`;
+    try {
+        const { checkpoint } = await store.load();
+        if (checkpoint.graphId !== doc.id)
+            fatal(`${path} belongs to graph "${checkpoint.graphId}", not "${doc.id}"`);
+        if (recoverCheckpoint(checkpoint))
+            await updateCheckpoint(store, checkpoint.id, (c) => recoverCheckpoint(c) ?? c);
+        const claimed = await updateCheckpoint(store, checkpoint.id, (c) => {
+            if (requiresAiBudget && !restoreRootBudget(c.budget))
+                throw new Error('resuming downstream AI nodes requires the original root budget receipt; no new allowance can be granted');
+            return claimCheckpoint(c, { owner, graphDigest: graphDigest(doc, inputs, registry), sourceDigest, leaseMs: LEASE_MS });
+        });
+        return { store, checkpoint: claimed, owner };
+    }
+    catch (error) {
+        fatal(error.message);
+    }
+}
+export async function finishResume(resume, result) {
+    const failed = result.log.find((l) => l.level === 'error');
+    return updateCheckpoint(resume.store, resume.checkpoint.id, (c) => finishCheckpoint(c, resume.owner, {
+        ok: result.ok,
+        ...(failed ? { message: `${failed.nodeId}: ${failed.message}` } : result.review.length ? { message: `paused again at ${result.review.join(', ')}` } : {}),
+    }));
+}
+/** A failed persistence step must not turn a consumed claim into completed. */
+export async function failResume(resume, message) {
+    return updateCheckpoint(resume.store, resume.checkpoint.id, c => finishCheckpoint(c, resume.owner, { ok: false, message }));
+}
+/** #7039: checkpoint writes must not alias model outputs or another journal. */
+export async function checkDistinctDestinations(paths) {
+    const names = new Set();
+    const files = new Set();
+    for (const path of paths) {
+        const absolute = resolve(path);
+        const canonical = await realpath(absolute).catch(async (error) => {
+            if (error.code !== 'ENOENT')
+                throw error;
+            return join(await realpath(dirname(absolute)), basename(absolute));
+        });
+        const info = await stat(absolute).catch((error) => {
+            if (error.code !== 'ENOENT')
+                throw error;
+            return null;
+        });
+        const identity = info ? `${info.dev}:${info.ino}` : undefined;
+        if (names.has(canonical) || (identity !== undefined && files.has(identity))) {
+            throw new Error('checkpoint, next checkpoint, output and tracking destinations must be distinct');
+        }
+        names.add(canonical);
+        if (identity !== undefined)
+            files.add(identity);
+    }
+}
+//# sourceMappingURL=flow-review.js.map

package/dist/commands/flow-review.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-review.js","sourceRoot":"","sources":["../../src/commands/flow-review.ts"],"names":[],"mappings":"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"}

package/dist/commands/flow-tracking.d.ts

@@ -4,10 +4,14 @@ export declare class FileTrackingStore implements TrackingStore {
     readonly pinnedTo: string;
     private sets;
     private dirty;
+    private exists;
+    private writePath;
     /** Pin recorded in the file that was loaded, when any. */
     loadedPin: string | undefined;
     constructor(path: string, pinnedTo: string);
     static open(path: string, pinnedTo: string): Promise<FileTrackingStore>;
+    /** Bind review to the effective sidecar and its canonical destination, including planned writes. */
+    fingerprint(): string;
     load(trackingKey: string): TrackedSet | undefined;
     save(set: TrackedSet): void;
     keys(): readonly string[];

package/dist/commands/flow-tracking.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flow-tracking.d.ts","sourceRoot":"","sources":["../../src/commands/flow-tracking.ts"],"names":[],"mappings":"AAiBA,OAAO,EAA6C,KAAK,UAAU,EAAwB,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEtI,qBAAa,iBAAkB,YAAW,aAAa;IAMzC,QAAQ,CAAC,IAAI,EAAE,MAAM;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM;IAL5D,OAAO,CAAC,IAAI,CAAkC;IAC9C,OAAO,CAAC,KAAK,CAAS;IACtB,0DAA0D;IAC1D,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;gBAET,IAAI,EAAE,MAAM,EAAW,QAAQ,EAAE,MAAM;WAE/C,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAwB7E,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAIjD,IAAI,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI;IAK3B,IAAI,IAAI,SAAS,MAAM,EAAE;IAIzB,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAMjC,4EAA4E;IACtE,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC;CAOhC;AAED,2EAA2E;AAC3E,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE7D"}
+{"version":3,"file":"flow-tracking.d.ts","sourceRoot":"","sources":["../../src/commands/flow-tracking.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAqD,KAAK,UAAU,EAAwB,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE9I,qBAAa,iBAAkB,YAAW,aAAa;IAQzC,QAAQ,CAAC,IAAI,EAAE,MAAM;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM;IAP5D,OAAO,CAAC,IAAI,CAAkC;IAC9C,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAS;IAC1B,0DAA0D;IAC1D,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;gBAET,IAAI,EAAE,MAAM,EAAW,QAAQ,EAAE,MAAM;WAE/C,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA6B7E,oGAAoG;IACpG,WAAW,IAAI,MAAM;IAMrB,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAIjD,IAAI,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI;IAK3B,IAAI,IAAI,SAAS,MAAM,EAAE;IAIzB,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAMjC,4EAA4E;IACtE,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC;CAShC;AAED,2EAA2E;AAC3E,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE7D"}

package/dist/commands/flow-tracking.js

@@ -12,30 +12,43 @@
  * and a tracked element that is gone is re-created with a warning. The
  * viewer, which keeps one model loaded, applies the strict pin check.
  */
-import { readFile, writeFile } from 'node:fs/promises';
-import { TRACKING_SIDECAR_VERSION, trackedSetsFrom } from '@ifc-lite/flow';
+import { readFile, writeFile, realpath } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { digest, TRACKING_SIDECAR_VERSION, trackedSetsFrom } from '@ifc-lite/flow';
 export class FileTrackingStore {
     path;
     pinnedTo;
     sets = {};
     dirty = false;
+    exists = false;
+    writePath;
     /** Pin recorded in the file that was loaded, when any. */
     loadedPin;
     constructor(path, pinnedTo) {
         this.path = path;
         this.pinnedTo = pinnedTo;
+        this.writePath = resolve(path);
     }
     static async open(path, pinnedTo) {
         const store = new FileTrackingStore(path, pinnedTo);
+        try {
+            store.writePath = await realpath(store.writePath);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            store.writePath = join(await realpath(dirname(store.writePath)), basename(store.writePath));
+        }
         let text;
         try {
-            text = await readFile(path, 'utf-8');
+            text = await readFile(store.writePath, 'utf-8');
         }
         catch (err) {
             if (err.code !== 'ENOENT')
                 throw err;
         }
         if (text !== undefined) {
+            store.exists = true;
             const parsed = JSON.parse(text);
             if (parsed.version !== TRACKING_SIDECAR_VERSION)
                 throw new Error(`${path}: unsupported tracking sidecar version ${String(parsed.version)}`);
@@ -53,6 +66,12 @@ export class FileTrackingStore {
         }
         return store;
     }
+    /** Bind review to the effective sidecar and its canonical destination, including planned writes. */
+    fingerprint() {
+        const sidecar = !this.exists && !this.dirty ? null : { version: TRACKING_SIDECAR_VERSION,
+            pinnedTo: this.dirty ? this.pinnedTo : this.loadedPin ?? this.pinnedTo, sets: this.sets };
+        return digest({ path: this.writePath, sidecar });
+    }
     load(trackingKey) {
         return this.sets[trackingKey];
     }
@@ -74,8 +93,10 @@ export class FileTrackingStore {
         if (!this.dirty)
             return false;
         const sidecar = { version: TRACKING_SIDECAR_VERSION, pinnedTo: this.pinnedTo, sets: this.sets };
-        await writeFile(this.path, `${JSON.stringify(sidecar, null, 2)}\n`, 'utf-8');
+        await writeFile(this.writePath, `${JSON.stringify(sidecar, null, 2)}\n`, 'utf-8');
         this.dirty = false;
+        this.exists = true;
+        this.loadedPin = this.pinnedTo;
         return true;
     }
 }

package/dist/commands/flow-tracking.js.map

@@ -1 +1 @@
-{"version":3,"file":"flow-tracking.js","sourceRoot":"","sources":["../../src/commands/flow-tracking.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"flow-tracking.js","sourceRoot":"","sources":["../../src/commands/flow-tracking.ts"],"names":[],"mappings":"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"}

package/dist/commands/flow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flow.d.ts","sourceRoot":"","sources":["../../src/commands/flow.ts"],"names":[],"mappings":"AAqJA,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAsI/D"}
+{"version":3,"file":"flow.d.ts","sourceRoot":"","sources":["../../src/commands/flow.ts"],"names":[],"mappings":"AA6KA,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAoL/D"}