@tiangong-lca/foundry 0.1.9 → 0.1.10

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 (83) hide show
  1. package/README.md +10 -8
  2. package/docs/architecture.md +9 -7
  3. package/docs/foundry-task-contracts.md +10 -4
  4. package/docs/import-profiles/bafu/constraints.md +1 -1
  5. package/docs/import-profiles/bafu/profile.md +1 -1
  6. package/docs/import-profiles/worldsteel/constraints.md +3 -3
  7. package/docs/import-profiles/worldsteel/import-coverage.md +3 -3
  8. package/docs/import-profiles/worldsteel/import-plan.md +4 -4
  9. package/docs/import-profiles/worldsteel/profile.md +3 -3
  10. package/docs/package-distribution-contract.md +9 -9
  11. package/docs/public-runtime-contract.md +17 -7
  12. package/docs/runtime-context-contract.md +5 -5
  13. package/docs/task-authorization-contract.md +3 -3
  14. package/package-dist/assets/foundry-package-descriptor.json +218 -128
  15. package/package-dist/scripts/foundry-facade.js +71 -0
  16. package/package-dist/scripts/foundry-runtime.d.ts +12 -2
  17. package/package-dist/scripts/lib/finalize-owners/commit-handoff.js +3 -3
  18. package/package-dist/scripts/lib/finalize-owners/{native-insert-closeout.d.ts → native-draft-closeout.d.ts} +1 -1
  19. package/package-dist/scripts/lib/finalize-owners/{native-insert-closeout.js → native-draft-closeout.js} +10 -6
  20. package/package-dist/scripts/lib/finalize-owners/{native-insert-handoff.d.ts → native-draft-handoff.d.ts} +7 -5
  21. package/package-dist/scripts/lib/finalize-owners/{native-insert-handoff.js → native-draft-handoff.js} +30 -11
  22. package/package-dist/scripts/lib/finalize-owners/post-write-closeout.js +2 -2
  23. package/package-dist/scripts/lib/foundry-authorization-input.d.ts +10 -1
  24. package/package-dist/scripts/lib/foundry-authorization-input.js +27 -3
  25. package/package-dist/scripts/lib/foundry-command-metadata.js +25 -2
  26. package/package-dist/scripts/lib/foundry-command-registry.d.ts +4 -4
  27. package/package-dist/scripts/lib/foundry-command-registry.js +3 -0
  28. package/package-dist/scripts/lib/foundry-execution-admission.js +3 -3
  29. package/package-dist/scripts/lib/foundry-facade-store.js +56 -6
  30. package/package-dist/scripts/lib/foundry-owner-execution-store.d.ts +33 -16
  31. package/package-dist/scripts/lib/foundry-owner-execution-store.js +32 -3
  32. package/package-dist/scripts/lib/foundry-owner-readback.d.ts +3 -0
  33. package/package-dist/scripts/lib/foundry-owner-readback.js +101 -27
  34. package/package-dist/scripts/lib/foundry-package-contract.d.ts +2 -2
  35. package/package-dist/scripts/lib/foundry-package-contract.js +2 -2
  36. package/package-dist/scripts/lib/foundry-repair-execution.d.ts +11 -0
  37. package/package-dist/scripts/lib/foundry-repair-execution.js +70 -0
  38. package/package-dist/scripts/lib/foundry-repair-handoff.d.ts +16 -0
  39. package/package-dist/scripts/lib/foundry-repair-handoff.js +108 -0
  40. package/package-dist/scripts/lib/foundry-repair-preflight.d.ts +96 -0
  41. package/package-dist/scripts/lib/foundry-repair-preflight.js +313 -0
  42. package/package-dist/scripts/lib/foundry-repair-reference-binding.d.ts +26 -0
  43. package/package-dist/scripts/lib/foundry-repair-reference-binding.js +120 -0
  44. package/package-dist/scripts/lib/foundry-repair-reference-proof.d.ts +63 -0
  45. package/package-dist/scripts/lib/foundry-repair-reference-proof.js +329 -0
  46. package/package-dist/scripts/lib/foundry-repair-scope.d.ts +76 -0
  47. package/package-dist/scripts/lib/foundry-repair-scope.js +304 -0
  48. package/package-dist/scripts/lib/foundry-runtime-command-policy.js +1 -0
  49. package/package-dist/scripts/lib/foundry-runtime-qualification.js +2 -2
  50. package/package-dist/scripts/lib/foundry-runtime-utils.d.ts +3 -0
  51. package/package-dist/scripts/lib/foundry-runtime-utils.js +6 -1
  52. package/package-dist/scripts/lib/foundry-successor-predecessor.d.ts +36 -0
  53. package/package-dist/scripts/lib/foundry-successor-predecessor.js +399 -0
  54. package/package-dist/scripts/lib/foundry-task-registration.js +64 -3
  55. package/package-dist/scripts/lib/foundry-task-start-spec.d.ts +3 -0
  56. package/package-dist/scripts/lib/foundry-task-start-spec.js +24 -1
  57. package/package-dist/scripts/lib/foundry-task-store.d.ts +13 -1
  58. package/package-dist/scripts/lib/foundry-task-store.js +23 -12
  59. package/package-dist/scripts/lib/foundry-task-types.d.ts +22 -1
  60. package/package-dist/scripts/lib/foundry-tidas-source.d.ts +15 -0
  61. package/package-dist/scripts/lib/foundry-tidas-source.js +90 -0
  62. package/package-dist/scripts/lib/foundry-workflow-authorization.d.ts +2 -1
  63. package/package-dist/scripts/lib/foundry-workflow-authorization.js +194 -26
  64. package/package-dist/scripts/lib/foundry-workflow-context.js +4 -0
  65. package/package-dist/scripts/lib/foundry-workflow-execution.js +6 -1
  66. package/package-dist/scripts/lib/foundry-workflow-repair.d.ts +36 -0
  67. package/package-dist/scripts/lib/foundry-workflow-repair.js +580 -0
  68. package/package-dist/scripts/lib/foundry-workflow-state.js +66 -18
  69. package/package-dist/scripts/lib/import-curation/curation-cleanup.js +39 -8
  70. package/package-dist/scripts/lib/import-curation/internal/context-inputs.js +1 -1
  71. package/package-dist/scripts/lib/import-curation/internal/prewrite-cleanup.d.ts +13 -2
  72. package/package-dist/scripts/lib/import-curation/internal/prewrite-cleanup.js +100 -29
  73. package/package-dist/scripts/lib/import-curation/internal/workflow-authoring-tasks.js +1 -2
  74. package/package-dist/scripts/lib/import-curation/internal/workflow-patch-collect.js +2 -3
  75. package/package-dist/scripts/lib/import-curation/internal/workflow-queue-context.js +8 -8
  76. package/package-dist/scripts/lib/import-curation/internal/workflow-semantic-actions.js +12 -2
  77. package/package.json +2 -2
  78. package/specs/import-profiles.json +1 -1
  79. package/specs/schemas/foundry-authorization-input.schema.json +45 -2
  80. package/specs/schemas/foundry-managed-runtime.schema.json +1 -1
  81. package/specs/schemas/foundry-package-descriptor.schema.json +2 -2
  82. package/specs/schemas/foundry-task-start.schema.json +200 -19
  83. package/specs/schemas/runtime-qualification.schema.json +1 -1
@@ -1,3 +1,4 @@
1
+ import { assertFoundryRepairExecution } from "./lib/foundry-repair-execution.js";
1
2
  import { createHash } from "node:crypto";
2
3
  import fs from "node:fs";
3
4
  import path from "node:path";
@@ -24,6 +25,7 @@ import { inspectFoundryReferences, verifyFoundryReferences, } from "./lib/foundr
24
25
  import { selectFoundrySemanticInput } from "./lib/foundry-semantic-input.js";
25
26
  import { runFoundryWorkflowIdentity } from "./lib/foundry-workflow-identity.js";
26
27
  import { finalizeFoundryWorkflow } from "./lib/foundry-workflow-finalize.js";
28
+ import { prepareFoundryRepair, readFoundryRepairPreparation, } from "./lib/foundry-workflow-repair.js";
27
29
  import { selectFoundryReferenceInput, recordFoundryReferenceInput, } from "./lib/foundry-reference-input.js";
28
30
  import { selectFoundryAuthorizationInput, snapshotFoundryAuthorizationContract, } from "./lib/foundry-authorization-input.js";
29
31
  import { authorizeFoundryWorkflow } from "./lib/foundry-workflow-authorization.js";
@@ -440,6 +442,66 @@ function taskProjection(operation, context, record, inspected, identity) {
440
442
  });
441
443
  }
442
444
  const workflow = currentWorkflowState(context, inspected.artifacts);
445
+ if (record.spec.repair && execution.verified.size) {
446
+ if (execution.requests.length !== 1 || execution.verified.size !== 1)
447
+ throw new FoundryContextError("repair_execution_mismatch", "A repair task must retain one exact verified execution scope.");
448
+ const requested = execution.requests[0];
449
+ const repair = assertFoundryRepairExecution(context, inspected.artifacts, requested.request);
450
+ const verified = execution.verified.get(requested.request.scope_id);
451
+ const proof = verified?.value.readback;
452
+ const bound = proof?.repair_preparation;
453
+ if (!repair ||
454
+ !verified ||
455
+ bound?.sha256 !== repair.preparation.entry.sha256 ||
456
+ bound?.bytes !== repair.preparation.entry.bytes ||
457
+ proof?.publication_ready !== false)
458
+ throw new FoundryContextError("repair_execution_mismatch", "Repair completion requires the same prepared scope and independent native receipt/readback proof.");
459
+ return createFoundryOperationResult({
460
+ operation,
461
+ status: "completed",
462
+ taskId: record.task_id,
463
+ artifacts,
464
+ blockers: [],
465
+ nextActions: [],
466
+ runtimeIdentity: identity,
467
+ permissions: noPermission(),
468
+ });
469
+ }
470
+ if (record.spec.repair && !workflow.authorization && !execution.completed.size) {
471
+ const found = readFoundryRepairPreparation(context, inspected.artifacts);
472
+ const noChange = found?.value.status === "no_change_verified";
473
+ const preparedRepair = found?.value.status === "prepared";
474
+ if (noChange && execution.requests.length)
475
+ throw new FoundryContextError("repair_noop_attempt_conflict", "No-write completion cannot replace an owner execution request.");
476
+ return createFoundryOperationResult({
477
+ operation,
478
+ status: noChange ? "completed" : found ? "needs_input" : "ready",
479
+ taskId: record.task_id,
480
+ artifacts,
481
+ blockers: noChange || !found
482
+ ? []
483
+ : [
484
+ {
485
+ code: preparedRepair ? "repair_authorization_required" : "repair_preflight_blocked",
486
+ message: preparedRepair
487
+ ? "The exact draft repair is prepared. Current task approval is required before any write."
488
+ : "Review the registered repair preflight findings; a resume may repeat only the read-only preparation.",
489
+ scope: record.task_id,
490
+ },
491
+ ],
492
+ nextActions: noChange
493
+ ? []
494
+ : preparedRepair
495
+ ? [
496
+ human("authorize_repair", `Review the content-bound repair evidence ${found.file} before authorizing its exact owner-draft scope.`),
497
+ ]
498
+ : [resumeCommand(context, record)],
499
+ runtimeIdentity: identity,
500
+ permissions: preparedRepair
501
+ ? { state: "required", requested_actions: [], approval_reference: null }
502
+ : noPermission(),
503
+ });
504
+ }
443
505
  const references = inspectFoundryReferences(context, inspected.artifacts);
444
506
  const scopeComplete = workflow.rows &&
445
507
  (workflow.rows.value.sets.length > 0 || references.scope) &&
@@ -952,6 +1014,7 @@ export function createFoundryFacade(options) {
952
1014
  profileId: selectedSpec.spec.profile_id,
953
1015
  targetEntities: [...selectedSpec.spec.target_entities],
954
1016
  seed: selectedSeed,
1017
+ ...(selectedSpec.spec.repair ? { repair: selectedSpec.spec.repair } : {}),
955
1018
  });
956
1019
  return {
957
1020
  created_at_utc: task.job.created_at_utc,
@@ -1026,6 +1089,8 @@ export function createFoundryFacade(options) {
1026
1089
  const qualified = qualification(context, options.runtimeSelection);
1027
1090
  const runtime = createFoundryRuntime(context, qualified);
1028
1091
  const before = await runtime.inspectTask();
1092
+ if (record.spec.repair && (input.semanticInputFile || input.referenceInputFile))
1093
+ throw new FoundryContextError("repair_revision_required", "A repair keeps its before, candidate and contract immutable; changed inputs require an explicit revision.");
1029
1094
  assertNotInterrupted(options.signal);
1030
1095
  loadFoundryFacadeTaskRecord(current, record.task_id, record.spec.actor_id);
1031
1096
  const existing = taskProjection("task.resume", context, record, before, runtimeIdentity(context, qualified));
@@ -1127,6 +1192,12 @@ export function createFoundryFacade(options) {
1127
1192
  }
1128
1193
  const preparation = record.spec.preparation;
1129
1194
  const workflow = currentWorkflowState(context, before.artifacts);
1195
+ if (record.spec.repair && !workflow.authorization && !execution.completed.size) {
1196
+ if (!qualified)
1197
+ throw new FoundryContextError("runtime_qualification_required", "Repair preflight requires the qualified installed owners.");
1198
+ await prepareFoundryRepair(context, qualified, before.artifacts, options.authentication ?? { mode: "oauth" });
1199
+ return taskProjection("task.resume", context, record, await runtime.inspectTask(), runtimeIdentity(context, qualified));
1200
+ }
1130
1201
  const references = inspectFoundryReferences(context, before.artifacts);
1131
1202
  if (!preparation && workflow.finalization && references.scope && !references.verified) {
1132
1203
  if (!qualified)
@@ -46,6 +46,16 @@ export declare function createFoundryRuntime(context: FoundryRuntimeContext, qua
46
46
  remote_state_code: 0;
47
47
  };
48
48
  created_at_utc: string;
49
+ repair?: Readonly<{
50
+ kind: string;
51
+ contract: string;
52
+ before: string;
53
+ candidate: string;
54
+ predecessor: Readonly<{
55
+ task_id: string;
56
+ receipt_sha256: string;
57
+ }> | null;
58
+ }>;
49
59
  }>;
50
60
  job_sha256: string;
51
61
  sources: readonly Readonly<{
@@ -171,9 +181,9 @@ export declare function createFoundryRuntime(context: FoundryRuntimeContext, qua
171
181
  command_policy: {
172
182
  total: number;
173
183
  public_operations: readonly ["workspace.init", "doctor", "task.start", "task.status", "task.resume", "workspace.migrate"];
174
- public_facade: ("acceptance-check" | "capabilities-list" | "dataset-authoring-patch-collect" | "dataset-authoring-plan" | "dataset-authoring-task-build" | "dataset-bafu-authoring-patches-autofill" | "dataset-bafu-batch-import-run" | "dataset-bafu-identity-decisions-autofill" | "dataset-bafu-leaf-classification-category-map-project" | "dataset-bafu-leaf-classification-tasks-prepare" | "dataset-bafu-process-scope-e2e" | "dataset-bafu-universe-coverage-report" | "dataset-bundle-sample-rows" | "dataset-canonical-support-mappings-autofill" | "dataset-classification-decision-task-build" | "dataset-classification-decisions-apply" | "dataset-commit-handoff-plan" | "dataset-curation-cleanup" | "dataset-curation-gate" | "dataset-curation-queue-build" | "dataset-identity-decision-task-build" | "dataset-identity-decisions-apply" | "dataset-identity-preflight-index-merge" | "dataset-identity-preflight-query-audit" | "dataset-identity-preflight-requests-build" | "dataset-identity-preflight-run" | "dataset-identity-reference-rewrites-apply" | "dataset-import-completion-report" | "dataset-import-ledger-report" | "dataset-incremental-change-set-compose" | "dataset-library-authoring-plan" | "dataset-library-classification-decisions-project" | "dataset-library-decisions-apply" | "dataset-library-identity-decisions-from-preflight" | "dataset-library-index-build" | "dataset-location-decision-task-build" | "dataset-location-decisions-apply" | "dataset-location-decisions-suggest" | "dataset-mutation-manifest" | "dataset-patch-apply" | "dataset-post-authoring-finalize" | "dataset-post-write-closeout" | "dataset-process-scope-run" | "dataset-support-cache-refresh" | "dataset-tidas-import" | "dataset-tidas-validate" | "dataset-topology-convergence-compose" | "dataset-uslci-batch-import-run" | "dataset-worldsteel-batch-import-run" | "doctor" | "env-check" | "execution-capsule-admit" | "init" | "profiles-list" | "route-task" | "storage-check" | "surface-audit" | "task-complete" | "tasks-check" | "tasks-list" | "tidas-handshake" | "workflow-check" | "workspace-map")[];
184
+ public_facade: ("acceptance-check" | "capabilities-list" | "dataset-authoring-patch-collect" | "dataset-authoring-plan" | "dataset-authoring-task-build" | "dataset-bafu-authoring-patches-autofill" | "dataset-bafu-batch-import-run" | "dataset-bafu-identity-decisions-autofill" | "dataset-bafu-leaf-classification-category-map-project" | "dataset-bafu-leaf-classification-tasks-prepare" | "dataset-bafu-process-scope-e2e" | "dataset-bafu-universe-coverage-report" | "dataset-bundle-sample-rows" | "dataset-canonical-support-mappings-autofill" | "dataset-classification-decision-task-build" | "dataset-classification-decisions-apply" | "dataset-commit-handoff-plan" | "dataset-curation-cleanup" | "dataset-curation-gate" | "dataset-curation-queue-build" | "dataset-identity-decision-task-build" | "dataset-identity-decisions-apply" | "dataset-identity-preflight-index-merge" | "dataset-identity-preflight-query-audit" | "dataset-identity-preflight-requests-build" | "dataset-identity-preflight-run" | "dataset-identity-reference-rewrites-apply" | "dataset-import-completion-report" | "dataset-import-ledger-report" | "dataset-incremental-change-set-compose" | "dataset-library-authoring-plan" | "dataset-library-classification-decisions-project" | "dataset-library-decisions-apply" | "dataset-library-identity-decisions-from-preflight" | "dataset-library-index-build" | "dataset-location-decision-task-build" | "dataset-location-decisions-apply" | "dataset-location-decisions-suggest" | "dataset-mutation-manifest" | "dataset-patch-apply" | "dataset-post-authoring-finalize" | "dataset-post-write-closeout" | "dataset-process-scope-run" | "dataset-support-cache-refresh" | "dataset-tidas-import" | "dataset-tidas-validate" | "dataset-topology-convergence-compose" | "dataset-uslci-batch-import-run" | "dataset-worldsteel-batch-import-run" | "doctor" | "env-check" | "execution-capsule-admit" | "final-delivery-promote" | "init" | "profiles-list" | "route-task" | "storage-check" | "surface-audit" | "task-complete" | "tasks-check" | "tasks-list" | "tidas-handshake" | "workflow-check" | "workspace-map")[];
175
185
  internal_only: number;
176
- excluded: ("acceptance-check" | "capabilities-list" | "dataset-authoring-patch-collect" | "dataset-authoring-plan" | "dataset-authoring-task-build" | "dataset-bafu-authoring-patches-autofill" | "dataset-bafu-batch-import-run" | "dataset-bafu-identity-decisions-autofill" | "dataset-bafu-leaf-classification-category-map-project" | "dataset-bafu-leaf-classification-tasks-prepare" | "dataset-bafu-process-scope-e2e" | "dataset-bafu-universe-coverage-report" | "dataset-bundle-sample-rows" | "dataset-canonical-support-mappings-autofill" | "dataset-classification-decision-task-build" | "dataset-classification-decisions-apply" | "dataset-commit-handoff-plan" | "dataset-curation-cleanup" | "dataset-curation-gate" | "dataset-curation-queue-build" | "dataset-identity-decision-task-build" | "dataset-identity-decisions-apply" | "dataset-identity-preflight-index-merge" | "dataset-identity-preflight-query-audit" | "dataset-identity-preflight-requests-build" | "dataset-identity-preflight-run" | "dataset-identity-reference-rewrites-apply" | "dataset-import-completion-report" | "dataset-import-ledger-report" | "dataset-incremental-change-set-compose" | "dataset-library-authoring-plan" | "dataset-library-classification-decisions-project" | "dataset-library-decisions-apply" | "dataset-library-identity-decisions-from-preflight" | "dataset-library-index-build" | "dataset-location-decision-task-build" | "dataset-location-decisions-apply" | "dataset-location-decisions-suggest" | "dataset-mutation-manifest" | "dataset-patch-apply" | "dataset-post-authoring-finalize" | "dataset-post-write-closeout" | "dataset-process-scope-run" | "dataset-support-cache-refresh" | "dataset-tidas-import" | "dataset-tidas-validate" | "dataset-topology-convergence-compose" | "dataset-uslci-batch-import-run" | "dataset-worldsteel-batch-import-run" | "doctor" | "env-check" | "execution-capsule-admit" | "init" | "profiles-list" | "route-task" | "storage-check" | "surface-audit" | "task-complete" | "tasks-check" | "tasks-list" | "tidas-handshake" | "workflow-check" | "workspace-map")[];
186
+ excluded: ("acceptance-check" | "capabilities-list" | "dataset-authoring-patch-collect" | "dataset-authoring-plan" | "dataset-authoring-task-build" | "dataset-bafu-authoring-patches-autofill" | "dataset-bafu-batch-import-run" | "dataset-bafu-identity-decisions-autofill" | "dataset-bafu-leaf-classification-category-map-project" | "dataset-bafu-leaf-classification-tasks-prepare" | "dataset-bafu-process-scope-e2e" | "dataset-bafu-universe-coverage-report" | "dataset-bundle-sample-rows" | "dataset-canonical-support-mappings-autofill" | "dataset-classification-decision-task-build" | "dataset-classification-decisions-apply" | "dataset-commit-handoff-plan" | "dataset-curation-cleanup" | "dataset-curation-gate" | "dataset-curation-queue-build" | "dataset-identity-decision-task-build" | "dataset-identity-decisions-apply" | "dataset-identity-preflight-index-merge" | "dataset-identity-preflight-query-audit" | "dataset-identity-preflight-requests-build" | "dataset-identity-preflight-run" | "dataset-identity-reference-rewrites-apply" | "dataset-import-completion-report" | "dataset-import-ledger-report" | "dataset-incremental-change-set-compose" | "dataset-library-authoring-plan" | "dataset-library-classification-decisions-project" | "dataset-library-decisions-apply" | "dataset-library-identity-decisions-from-preflight" | "dataset-library-index-build" | "dataset-location-decision-task-build" | "dataset-location-decisions-apply" | "dataset-location-decisions-suggest" | "dataset-mutation-manifest" | "dataset-patch-apply" | "dataset-post-authoring-finalize" | "dataset-post-write-closeout" | "dataset-process-scope-run" | "dataset-support-cache-refresh" | "dataset-tidas-import" | "dataset-tidas-validate" | "dataset-topology-convergence-compose" | "dataset-uslci-batch-import-run" | "dataset-worldsteel-batch-import-run" | "doctor" | "env-check" | "execution-capsule-admit" | "final-delivery-promote" | "init" | "profiles-list" | "route-task" | "storage-check" | "surface-audit" | "task-complete" | "tasks-check" | "tasks-list" | "tidas-handshake" | "workflow-check" | "workspace-map")[];
177
187
  };
178
188
  };
179
189
  cleanup(request: FoundryCleanupRequest): Promise<import("./lib/foundry-task-types.ts").JsonRecord>;
@@ -7,7 +7,7 @@ import { taskAuthorizationAllows, taskAuthorizationMatches, taskAuthorizationWai
7
7
  import { datasetIdentity, detectDatasetType } from "../import-curation/internal/dataset-payload.js";
8
8
  import { readRows } from "../import-curation/internal/runtime-io.js";
9
9
  import { flowPrewriteIdentityBlockers } from "../import-curation/internal/workflow-identity-preflight.js";
10
- import { assertExecutionContractSelection, readNativeInsertHandoff, reserveNativeHandoffDirectory, nativeInsertCommitArguments, } from "./native-insert-handoff.js";
10
+ import { assertExecutionContractSelection, readNativeDraftHandoff, reserveNativeHandoffDirectory, nativeDraftCommitArguments, } from "./native-draft-handoff.js";
11
11
  function commitCommandForDatasetType(datasetType, rowsFile, outDir, { appendOption, resolveTiangongLcaCliBin, resolveTiangongLcaCliCommand, targetUserId = null, allowAccountLocalSupportAndElementary = false, } = {}) {
12
12
  const cliPrefix = () => {
13
13
  if (resolveTiangongLcaCliCommand) {
@@ -218,7 +218,7 @@ export function createCommitHandoffCommands({ executionEnvironment = process.env
218
218
  if (contractFile && fileExists(outDir))
219
219
  throw new Error("--execution-contract-file requires a fresh handoff output directory.");
220
220
  const native = contractFile && finalRowsFile
221
- ? readNativeInsertHandoff({
221
+ ? readNativeDraftHandoff({
222
222
  contractFile,
223
223
  rowsFile: finalRowsFile,
224
224
  datasetType,
@@ -390,7 +390,7 @@ export function createCommitHandoffCommands({ executionEnvironment = process.env
390
390
  })()
391
391
  : [resolveTiangongLcaCliBin()];
392
392
  const commitArgs = native && finalRowsFile && contractFile
393
- ? nativeInsertCommitArguments(cliPrefix, datasetType, finalRowsFile, outDir, contractFile)
393
+ ? nativeDraftCommitArguments(cliPrefix, datasetType, finalRowsFile, outDir, contractFile)
394
394
  : legacyCommitArgs;
395
395
  const verifyArgs = finalRowsFile
396
396
  ? [
@@ -1,5 +1,5 @@
1
1
  type JsonRecord = Record<string, unknown>;
2
- export declare function validateNativeInsertCloseout(input: {
2
+ export declare function validateNativeDraftCloseout(input: {
3
3
  handoff: JsonRecord;
4
4
  report: JsonRecord;
5
5
  rowsFile: string;
@@ -1,16 +1,16 @@
1
1
  import path from "node:path";
2
2
  import { parseFoundryCommandSpec } from "../foundry-command-spec.js";
3
3
  import { sha256Json } from "../identity-preflight-proof.js";
4
- import { readNativeInsertHandoff } from "./native-insert-handoff.js";
4
+ import { readNativeDraftHandoff } from "./native-draft-handoff.js";
5
5
  function requireEvidence(condition) {
6
6
  if (!condition)
7
- throw new Error("Native insert completion evidence is missing or inconsistent.");
7
+ throw new Error("Native draft completion evidence is missing or inconsistent.");
8
8
  }
9
9
  function object(value) {
10
10
  requireEvidence(value && typeof value === "object" && !Array.isArray(value));
11
11
  return value;
12
12
  }
13
- export function validateNativeInsertCloseout(input) {
13
+ export function validateNativeDraftCloseout(input) {
14
14
  const resolveFile = (value) => {
15
15
  const file = input.resolveFile(value);
16
16
  return file ? path.resolve(file) : null;
@@ -22,8 +22,8 @@ export function validateNativeInsertCloseout(input) {
22
22
  const binding = object(input.handoff.execution_contract);
23
23
  const artifact = object(binding.artifact);
24
24
  const contractFile = resolveFile(artifact.path);
25
- requireEvidence(contractFile && binding.operation === "insert");
26
- const native = readNativeInsertHandoff({
25
+ requireEvidence(contractFile);
26
+ const native = readNativeDraftHandoff({
27
27
  contractFile,
28
28
  rowsFile: input.rowsFile,
29
29
  datasetType: input.datasetType,
@@ -33,6 +33,7 @@ export function validateNativeInsertCloseout(input) {
33
33
  relativePath: input.relativePath,
34
34
  });
35
35
  requireEvidence(sha256Json(artifact) === sha256Json(native.artifact) &&
36
+ binding.operation === native.metadata.operation &&
36
37
  binding.canonical_sha256 === native.canonical_sha256 &&
37
38
  binding.execution_id === native.contract.execution_id &&
38
39
  binding.project_ref === native.contract.project_ref);
@@ -82,6 +83,8 @@ export function validateNativeInsertCloseout(input) {
82
83
  report.rows.length === actions.length);
83
84
  for (const [index, action] of actions.entries()) {
84
85
  const row = object(report.rows[index]);
86
+ // A recovered row is a consumed attempt whose exact desired state was proven by readback, so
87
+ // it must satisfy every other check unchanged. Nothing else may substitute for it.
85
88
  requireEvidence(row.index === index &&
86
89
  row.type === input.datasetType &&
87
90
  row.table === action.table &&
@@ -90,7 +93,8 @@ export function validateNativeInsertCloseout(input) {
90
93
  row.action_id === action.action_id &&
91
94
  row.desired_sha256 === action.desired_sha256 &&
92
95
  row.status === "executed" &&
93
- row.operation === "insert" &&
96
+ (row.operation === action.expected_operation ||
97
+ row.operation === "recovered_exact_readback") &&
94
98
  row.attempt_consumed === true &&
95
99
  row.replayed === false &&
96
100
  row.readback === "desired_exact");
@@ -1,7 +1,9 @@
1
1
  type JsonRecord = Record<string, unknown>;
2
+ export type NativeDraftOperation = "insert" | "save_draft";
3
+ export type NativeDraftContractOperation = NativeDraftOperation | "mixed";
2
4
  export declare function assertExecutionContractSelection(options: JsonRecord): void;
3
5
  /** Consumer admission only; CLI owns parsing at execution, attempts and readback. */
4
- export declare function readNativeInsertHandoff(input: {
6
+ export declare function readNativeDraftHandoff(input: {
5
7
  contractFile: string;
6
8
  rowsFile: string;
7
9
  datasetType: string;
@@ -24,11 +26,11 @@ export declare function readNativeInsertHandoff(input: {
24
26
  actions: {
25
27
  action_id: string;
26
28
  desired_sha256: string;
27
- expected_operation: "insert";
29
+ expected_operation: NativeDraftOperation;
28
30
  table: string;
29
31
  id: string;
30
32
  version: string;
31
- before_sha256: null;
33
+ before_sha256: string | null;
32
34
  dependency_action_ids: string[];
33
35
  }[];
34
36
  };
@@ -38,10 +40,10 @@ export declare function readNativeInsertHandoff(input: {
38
40
  canonical_sha256: string;
39
41
  execution_id: string;
40
42
  project_ref: string;
41
- operation: string;
43
+ operation: NativeDraftContractOperation;
42
44
  };
43
45
  rows_sha256: string;
44
46
  };
45
47
  export declare function reserveNativeHandoffDirectory(directory: string): void;
46
- export declare function nativeInsertCommitArguments(prefix: readonly string[], datasetType: string, rowsFile: string, outDir: string, contractFile: string): string[];
48
+ export declare function nativeDraftCommitArguments(prefix: readonly string[], datasetType: string, rowsFile: string, outDir: string, contractFile: string): string[];
47
49
  export {};
@@ -4,6 +4,7 @@ import { createFileArtifactFact } from "../foundry-command-spec.js";
4
4
  import { sha256Json, sha256Text } from "../identity-preflight-proof.js";
5
5
  import { datasetIdentity } from "../import-curation/internal/dataset-payload.js";
6
6
  import { readRows } from "../import-curation/internal/runtime-io.js";
7
+ const BEFORE_SHA256_PATTERN = /^[0-9a-f]{64}$/u;
7
8
  function fail(message) {
8
9
  throw new Error(`--execution-contract-file: ${message}`);
9
10
  }
@@ -17,6 +18,20 @@ function token(value) {
17
18
  return fail("Contract identity fields must be non-empty strings.");
18
19
  return value.trim();
19
20
  }
21
+ /**
22
+ * One action binds exactly one draft operation: an absent row inserts, an existing owner draft
23
+ * updates in place with its complete before hash. The CLI execution contract applies the same
24
+ * rule, so a contract that contradicts itself never reaches admission.
25
+ */
26
+ function draftOperationBinding(operation, beforeSha256) {
27
+ if (operation === "insert" && beforeSha256 === null)
28
+ return { expected_operation: "insert", before_sha256: null };
29
+ if (operation === "save_draft" &&
30
+ typeof beforeSha256 === "string" &&
31
+ BEFORE_SHA256_PATTERN.test(beforeSha256))
32
+ return { expected_operation: "save_draft", before_sha256: beforeSha256 };
33
+ return null;
34
+ }
20
35
  export function assertExecutionContractSelection(options) {
21
36
  if (Object.keys(options).some((key) => key.startsWith("executionContract") && key !== "executionContractFile") ||
22
37
  (Object.hasOwn(options, "executionContractFile") &&
@@ -25,10 +40,10 @@ export function assertExecutionContractSelection(options) {
25
40
  fail("Use one non-empty string selection; unsupported options or repeated values are invalid.");
26
41
  }
27
42
  /** Consumer admission only; CLI owns parsing at execution, attempts and readback. */
28
- export function readNativeInsertHandoff(input) {
43
+ export function readNativeDraftHandoff(input) {
29
44
  const tables = { flow: "flows", process: "processes", source: "sources" };
30
45
  if (!Object.hasOwn(tables, input.datasetType) || input.stateCode !== "0")
31
- fail("Native insert handoffs support only Flow, Process and Source owner drafts.");
46
+ fail("Native draft handoffs support only Flow, Process and Source owner drafts.");
32
47
  if (!fs.lstatSync(input.contractFile).isFile())
33
48
  fail("Select a regular contract file.");
34
49
  const bytes = fs.readFileSync(input.contractFile, "utf8");
@@ -58,17 +73,17 @@ export function readNativeInsertHandoff(input) {
58
73
  const id = token(info["common:UUID"]);
59
74
  const version = token(publication["common:dataSetVersion"]);
60
75
  const target = JSON.stringify([id, version]);
76
+ const operation = draftOperationBinding(action.expected_operation, action.before_sha256);
61
77
  if (actionIds.has(actionId) ||
62
78
  targets.has(target) ||
63
- action.expected_operation !== "insert" ||
64
- action.before_sha256 !== null ||
79
+ !operation ||
65
80
  action.table !== tables[input.datasetType] ||
66
81
  token(action.id) !== id ||
67
82
  token(action.version) !== version ||
68
83
  identity.id !== id ||
69
84
  identity.version !== version ||
70
85
  action.desired_sha256 !== sha256Json(identity.payload))
71
- fail("Contract insert action does not bind the exact final payload and identity.");
86
+ fail("Contract action does not bind the exact final payload, identity and draft operation.");
72
87
  if (!Array.isArray(action.dependency_action_ids))
73
88
  fail("Action dependencies must be explicit.");
74
89
  const dependencies = action.dependency_action_ids.map(token);
@@ -77,19 +92,23 @@ export function readNativeInsertHandoff(input) {
77
92
  fail("Dependencies must identify unique earlier contract actions.");
78
93
  actionIds.add(actionId);
79
94
  targets.add(target);
95
+ // Project the native owner's normalized wire fields for its report digest. The action keeps
96
+ // the CLI execution contract's exact eight keys so both sides hash the same object shape.
80
97
  return {
81
98
  action_id: actionId,
82
99
  desired_sha256: action.desired_sha256,
83
- expected_operation: "insert",
100
+ expected_operation: operation.expected_operation,
84
101
  table: tables[input.datasetType],
85
102
  id,
86
103
  version,
87
- before_sha256: null,
104
+ before_sha256: operation.before_sha256,
88
105
  dependency_action_ids: dependencies,
89
106
  };
90
107
  });
91
- // Project the native owner's normalized wire fields for its report digest.
92
- // Raw file bytes are bound separately, so ignored metadata cannot drift.
108
+ // Raw file bytes are bound separately, so ignored metadata cannot drift. The operation label is
109
+ // derived from the hashed actions only: one operation keeps its name, both become "mixed".
110
+ const operations = [...new Set(actions.map((action) => action.expected_operation))];
111
+ const operation = operations.length === 1 ? operations[0] : "mixed";
93
112
  const contract = {
94
113
  schema_version: "dataset-save-draft-execution-contract.v1",
95
114
  execution_id: token(raw.execution_id),
@@ -118,7 +137,7 @@ export function readNativeInsertHandoff(input) {
118
137
  canonical_sha256: sha256Json(contract),
119
138
  execution_id: contract.execution_id,
120
139
  project_ref: contract.project_ref,
121
- operation: "insert",
140
+ operation,
122
141
  },
123
142
  rows_sha256: sha256Text(rowsText),
124
143
  };
@@ -127,7 +146,7 @@ export function reserveNativeHandoffDirectory(directory) {
127
146
  fs.mkdirSync(path.dirname(directory), { recursive: true });
128
147
  fs.mkdirSync(directory);
129
148
  }
130
- export function nativeInsertCommitArguments(prefix, datasetType, rowsFile, outDir, contractFile) {
149
+ export function nativeDraftCommitArguments(prefix, datasetType, rowsFile, outDir, contractFile) {
131
150
  return [
132
151
  ...prefix,
133
152
  "dataset",
@@ -2,7 +2,7 @@ import path from "node:path";
2
2
  import { createFileArtifactFact } from "../foundry-command-spec.js";
3
3
  import { normalizeAllowedTraceHashDifference } from "../remote-verification-accepted-diff.js";
4
4
  import { canonicalPayloadSha256, validateUniqueRootReadbacks } from "../post-write-root-proof.js";
5
- import { validateNativeInsertCloseout } from "./native-insert-closeout.js";
5
+ import { validateNativeDraftCloseout } from "./native-draft-closeout.js";
6
6
  import { validateReferenceIntentReadback } from "./reference-intent-closeout.js";
7
7
  function isJsonRecord(value) {
8
8
  return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -10,7 +10,7 @@ function isJsonRecord(value) {
10
10
  export function createPostWriteCloseoutCommands({ executionEnvironment = process.env, asText, countJsonLinesFile, countRowsFile, datasetIdentity, ensureArray, fileExists, fullContextProofCheck, nowIso, readJsonArtifactOption, readJsonLines, readRowsFile, repoRelativeMaybe, repoRelativePath, reportInputPath, resolveRepoPath, sameResolvedPath, validateTraceQueueCoverageForRows, writeCloseoutImportLedger, writeJson, }) {
11
11
  function validateCommitReportForCloseout({ commitReport, commitReportPath, datasetType, finalRowsFile, expectedRows, blockers, handoffPlan, targetUserId, expectedStateCode, }) {
12
12
  try {
13
- if (validateNativeInsertCloseout({
13
+ if (validateNativeDraftCloseout({
14
14
  handoff: handoffPlan ?? {},
15
15
  report: commitReport,
16
16
  rowsFile: finalRowsFile,
@@ -7,13 +7,21 @@ export interface FoundryAuthorizationInput {
7
7
  actor_id: string;
8
8
  finalization_sha256: string;
9
9
  dataset_type: string;
10
- input_kind: "current_rows" | "final_rows";
10
+ /**
11
+ * `repair_rows` is the existing-owner-draft repair scope: its authority is the registered repair
12
+ * preparation report, never a finalization report, and it always carries the native contract.
13
+ */
14
+ input_kind: "current_rows" | "final_rows" | "repair_rows";
11
15
  input_sha256: string;
12
16
  expected_previous_sha256: string | null;
13
17
  execution_contract?: {
14
18
  file: string;
15
19
  sha256: string;
16
20
  };
21
+ repair_preparation?: {
22
+ file: string;
23
+ sha256: string;
24
+ };
17
25
  grant: {
18
26
  file: string;
19
27
  sha256: string;
@@ -32,6 +40,7 @@ export interface SelectedAuthorizationInput {
32
40
  readonly evidence: readonly FoundryInputFact[];
33
41
  readonly executionContract?: FoundryInputFact;
34
42
  readonly executionContractSource?: FoundryInputFact;
43
+ readonly repairPreparation?: FoundryInputFact;
35
44
  }
36
45
  export declare function parseFoundryAuthorizationInput(value: unknown): FoundryAuthorizationInput;
37
46
  export declare function selectFoundryAuthorizationInput(context: FoundryRuntimeContext, file: string): SelectedAuthorizationInput;
@@ -40,6 +40,7 @@ export function parseFoundryAuthorizationInput(value) {
40
40
  "grant",
41
41
  "evidence",
42
42
  ...(Object.hasOwn(data, "execution_contract") ? ["execution_contract"] : []),
43
+ ...(Object.hasOwn(data, "repair_preparation") ? ["repair_preparation"] : []),
43
44
  ]);
44
45
  if (data.schema !== FOUNDRY_AUTHORIZATION_INPUT_SCHEMA ||
45
46
  typeof data.task_id !== "string" ||
@@ -60,7 +61,9 @@ export function parseFoundryAuthorizationInput(value) {
60
61
  "flowproperty",
61
62
  "lifecyclemodel",
62
63
  ].includes(data.dataset_type) ||
63
- (data.input_kind !== "current_rows" && data.input_kind !== "final_rows") ||
64
+ (data.input_kind !== "current_rows" &&
65
+ data.input_kind !== "final_rows" &&
66
+ data.input_kind !== "repair_rows") ||
64
67
  (data.expected_previous_sha256 !== null &&
65
68
  (typeof data.expected_previous_sha256 !== "string" ||
66
69
  !sha.test(data.expected_previous_sha256))) ||
@@ -72,13 +75,29 @@ export function parseFoundryAuthorizationInput(value) {
72
75
  exact(grant, ["file", "sha256"]);
73
76
  let executionContract;
74
77
  if (Object.hasOwn(data, "execution_contract")) {
75
- if (data.input_kind !== "final_rows" ||
78
+ if (!["final_rows", "repair_rows"].includes(String(data.input_kind)) ||
76
79
  !["flow", "process", "source"].includes(data.dataset_type))
77
- invalid("Native insert contracts require finalized Flow, Process or Source rows.");
80
+ invalid("Native draft contracts require finalized Flow, Process or Source rows.");
78
81
  const selected = workflowObject(data.execution_contract);
79
82
  exact(selected, ["file", "sha256"]);
80
83
  executionContract = Object.freeze(fileReference(selected));
81
84
  }
85
+ let repairPreparation;
86
+ if (Object.hasOwn(data, "repair_preparation")) {
87
+ const selected = workflowObject(data.repair_preparation);
88
+ exact(selected, ["file", "sha256"]);
89
+ repairPreparation = Object.freeze(fileReference(selected));
90
+ }
91
+ if ((data.input_kind === "repair_rows") !== Boolean(repairPreparation))
92
+ invalid("A repair scope is exactly the repair_rows input kind carrying its registered preparation report.");
93
+ if (repairPreparation) {
94
+ if (data.dataset_type !== "process")
95
+ invalid("A repair scope admits only Process owner drafts.");
96
+ if (!executionContract)
97
+ invalid("A repair scope always carries the selected native execution contract.");
98
+ if (data.finalization_sha256 !== repairPreparation.sha256)
99
+ invalid("A repair scope authority is the registered preparation report digest; a finalization digest is not accepted.");
100
+ }
82
101
  const evidence = data.evidence.map((raw) => {
83
102
  const item = workflowObject(raw);
84
103
  exact(item, ["id", "kind", "file", "sha256"]);
@@ -103,6 +122,7 @@ export function parseFoundryAuthorizationInput(value) {
103
122
  grant: Object.freeze(fileReference(grant)),
104
123
  evidence: Object.freeze(evidence),
105
124
  ...(executionContract ? { execution_contract: executionContract } : {}),
125
+ ...(repairPreparation ? { repair_preparation: repairPreparation } : {}),
106
126
  });
107
127
  }
108
128
  export function selectFoundryAuthorizationInput(context, file) {
@@ -149,12 +169,16 @@ export function selectFoundryAuthorizationInput(context, file) {
149
169
  const executionContract = spec.execution_contract ? select(spec.execution_contract.file) : null;
150
170
  if (executionContract && executionContract.sha256 !== spec.execution_contract.sha256)
151
171
  invalid("Native execution contract bytes differ from the selected digest.");
172
+ const repairPreparation = spec.repair_preparation ? select(spec.repair_preparation.file) : null;
173
+ if (repairPreparation && repairPreparation.sha256 !== spec.repair_preparation.sha256)
174
+ invalid("Repair preparation bytes differ from the selected digest.");
152
175
  const result = Object.freeze({
153
176
  spec,
154
177
  descriptor,
155
178
  grant: selected[0],
156
179
  evidence: Object.freeze(selected.slice(1)),
157
180
  ...(executionContract ? { executionContract } : {}),
181
+ ...(repairPreparation ? { repairPreparation } : {}),
158
182
  });
159
183
  selections.add(result);
160
184
  return result;
@@ -238,6 +238,26 @@ export const commandMetadata = {
238
238
  nodeTest("test/unit/execution-capsule-attempt-state.test.mts", "attempt dispositions distinguish unattempted, recovered success, and unknown no-replay states"),
239
239
  ],
240
240
  }),
241
+ "final-delivery-promote": metadata({
242
+ category: "workflow-internal",
243
+ ownerModule: "scripts/commands/final-delivery-promotion.ts",
244
+ ownerExport: "createFinalDeliveryPromotionCommands().runFinalDeliveryPromote",
245
+ inputs: [
246
+ "foundry-final-delivery-manifest.v1",
247
+ "content-bound local delivery artifacts",
248
+ "declarative algebra and workbook policies",
249
+ "independent reviewer reports",
250
+ ],
251
+ outputs: [
252
+ "final-delivery-manifest-snapshot.json",
253
+ "final-delivery-promotion-ledger.jsonl",
254
+ "final-delivery-promotion-report.json",
255
+ "final-delivery-promotion-seal.json when all checks pass",
256
+ ],
257
+ keyTests: [
258
+ nodeTest("test/commands/final-delivery-promotion.test.mts", "final delivery promotion validates exact content, rows, algebra, workbook, redaction, review, and immutable seal behavior"),
259
+ ],
260
+ }),
241
261
  "dataset-incremental-change-set-compose": metadata({
242
262
  category: "workflow-internal",
243
263
  ownerModule: "scripts/commands/incremental-change-set.ts",
@@ -529,7 +549,7 @@ export const commandMetadata = {
529
549
  "blocked_invalid_datetime_metadata: ordered blockers, null cleaned rows, and every pre-existing stale output preserved",
530
550
  ],
531
551
  keyTests: [
532
- nodeTest("test/scenarios/curation-cleanup-quality-gates.test.mts", "curation cleanup fills placeholder annual supply with searchable sentinel"),
552
+ nodeTest("test/scenarios/curation-cleanup-quality-gates.test.mts", "curation cleanup normalizes placeholder annual supply to the supported unknown array"),
533
553
  nodeTest("test/scenarios/curation-cleanup-quality-gates.test.mts", "curation cleanup CLI exits nonzero and emits only blocker evidence for an impossible datetime"),
534
554
  nodeTest("test/unit/curation-cleanup-runner-contract.test.mts", "impossible datetime blocks the whole cleanup before partial transforms or cleaned-row output"),
535
555
  importCurationEntryContract,
@@ -929,7 +949,7 @@ export const commandMetadata = {
929
949
  "finalize report",
930
950
  "location audit evidence",
931
951
  "current task authorization for restricted final rows or QA exceptions",
932
- "optional explicit native insert execution-contract file for Flow, Process or Source",
952
+ "optional explicit native draft execution-contract file (insert or save_draft) for Flow, Process or Source",
933
953
  ],
934
954
  outputs: [
935
955
  "commit handoff plan JSON report",
@@ -941,6 +961,8 @@ export const commandMetadata = {
941
961
  keyTests: [
942
962
  nodeTest("test/scenarios/handoff-reference-intent.test.mts", "handoff automatically retains the passing reference intent and all evidence in both command specs"),
943
963
  nodeTest("test/scenarios/native-insert-closeout.test.mts", "native closeout rejects a completed report from a different contract despite exact root readback"),
964
+ nodeTest("test/unit/handoff-identity-task-command-factories.test.mts", "explicit native draft handoff binds a save_draft update and preserves the exact CLI action projection"),
965
+ nodeTest("test/scenarios/foundry-public-native-draft.test.mts", "public native draft repair accepts a bound save_draft contract without extra dispatch"),
944
966
  nodeTest("test/unit/handoff-identity-task-command-factories.test.mts", "mixed support handoff rechecks exact task actions against actual final rows"),
945
967
  nodeTest("test/unit/foundry-command-spec.test.mts", "CommandSpec blocks artifact byte drift before spawn and never executes display"),
946
968
  nodeTest("test/scenarios/full-context-completion-closeout.test.mts", "commit handoff blocks nonzero location audit blockers"),
@@ -961,6 +983,7 @@ export const commandMetadata = {
961
983
  outputs: ["post-write-closeout-report.json"],
962
984
  keyTests: [
963
985
  nodeTest("test/scenarios/native-insert-closeout.test.mts", "native closeout accepts exact consumed insert/readback evidence and still requires unique roots"),
986
+ nodeTest("test/unit/handoff-identity-task-command-factories.test.mts", "native draft closeout rejects forged, incomplete or wrong-operation recovered rows"),
964
987
  nodeTest("test/scenarios/full-context-completion-closeout.test.mts", "post-write closeout requires common:other trace queues to match final rows"),
965
988
  ],
966
989
  }),