@tiangong-lca/foundry 0.1.2
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.
- package/LICENSE +21 -0
- package/README.md +532 -0
- package/docs/architecture.md +450 -0
- package/docs/foundry-task-contracts.md +147 -0
- package/docs/import-profiles/bafu/constraints.md +343 -0
- package/docs/import-profiles/bafu/leaf-process-classification-authoring.md +153 -0
- package/docs/import-profiles/bafu/profile.md +183 -0
- package/docs/import-profiles/uslci/constraints.md +29 -0
- package/docs/import-profiles/uslci/profile.md +43 -0
- package/docs/import-profiles/worldsteel/constraints.md +77 -0
- package/docs/import-profiles/worldsteel/import-coverage.md +93 -0
- package/docs/import-profiles/worldsteel/import-plan.md +375 -0
- package/docs/import-profiles/worldsteel/profile.md +78 -0
- package/docs/package-distribution-contract.md +287 -0
- package/docs/public-runtime-contract.md +218 -0
- package/docs/runtime-context-contract.md +138 -0
- package/docs/safety-policy.md +164 -0
- package/docs/task-authorization-contract.md +131 -0
- package/docs/uslci-import-runbook.md +336 -0
- package/docs/workspace-migration-contract.md +127 -0
- package/package-dist/assets/foundry-package-descriptor.json +1661 -0
- package/package-dist/scripts/foundry-facade.d.ts +78 -0
- package/package-dist/scripts/foundry-facade.js +1317 -0
- package/package-dist/scripts/foundry-runtime.d.ts +180 -0
- package/package-dist/scripts/foundry-runtime.js +190 -0
- package/package-dist/scripts/lib/batch-orchestration/scope-attempt-ledger.d.ts +27 -0
- package/package-dist/scripts/lib/batch-orchestration/scope-attempt-ledger.js +85 -0
- package/package-dist/scripts/lib/batch-orchestration/scope-resume-contract.d.ts +38 -0
- package/package-dist/scripts/lib/batch-orchestration/scope-resume-contract.js +90 -0
- package/package-dist/scripts/lib/bundle-row-types.d.ts +44 -0
- package/package-dist/scripts/lib/bundle-row-types.js +46 -0
- package/package-dist/scripts/lib/bundle-sample-utils.d.ts +183 -0
- package/package-dist/scripts/lib/bundle-sample-utils.js +526 -0
- package/package-dist/scripts/lib/bundle-source-context.d.ts +31 -0
- package/package-dist/scripts/lib/bundle-source-context.js +142 -0
- package/package-dist/scripts/lib/canonical-description.d.ts +12 -0
- package/package-dist/scripts/lib/canonical-description.js +72 -0
- package/package-dist/scripts/lib/canonical-support-rewrites.d.ts +127 -0
- package/package-dist/scripts/lib/canonical-support-rewrites.js +527 -0
- package/package-dist/scripts/lib/decision-owners/classification.d.ts +245 -0
- package/package-dist/scripts/lib/decision-owners/classification.js +754 -0
- package/package-dist/scripts/lib/decision-owners/identity-preflight.d.ts +333 -0
- package/package-dist/scripts/lib/decision-owners/identity-preflight.js +1353 -0
- package/package-dist/scripts/lib/decision-owners/identity-task.d.ts +130 -0
- package/package-dist/scripts/lib/decision-owners/identity-task.js +494 -0
- package/package-dist/scripts/lib/decision-owners/identity.d.ts +74 -0
- package/package-dist/scripts/lib/decision-owners/identity.js +443 -0
- package/package-dist/scripts/lib/decision-owners/location.d.ts +239 -0
- package/package-dist/scripts/lib/decision-owners/location.js +704 -0
- package/package-dist/scripts/lib/decision-task-utils.d.ts +484 -0
- package/package-dist/scripts/lib/decision-task-utils.js +735 -0
- package/package-dist/scripts/lib/finalize-owners/cli-wrappers.d.ts +52 -0
- package/package-dist/scripts/lib/finalize-owners/cli-wrappers.js +146 -0
- package/package-dist/scripts/lib/finalize-owners/commit-handoff.d.ts +79 -0
- package/package-dist/scripts/lib/finalize-owners/commit-handoff.js +515 -0
- package/package-dist/scripts/lib/finalize-owners/post-authoring.d.ts +234 -0
- package/package-dist/scripts/lib/finalize-owners/post-authoring.js +1720 -0
- package/package-dist/scripts/lib/finalize-owners/post-write-closeout.d.ts +140 -0
- package/package-dist/scripts/lib/finalize-owners/post-write-closeout.js +656 -0
- package/package-dist/scripts/lib/foundry-args.d.ts +7 -0
- package/package-dist/scripts/lib/foundry-args.js +38 -0
- package/package-dist/scripts/lib/foundry-authentication-environment.d.ts +17 -0
- package/package-dist/scripts/lib/foundry-authentication-environment.js +55 -0
- package/package-dist/scripts/lib/foundry-authorization-input.d.ts +31 -0
- package/package-dist/scripts/lib/foundry-authorization-input.js +151 -0
- package/package-dist/scripts/lib/foundry-command-metadata.d.ts +32 -0
- package/package-dist/scripts/lib/foundry-command-metadata.js +1012 -0
- package/package-dist/scripts/lib/foundry-command-registry.d.ts +34 -0
- package/package-dist/scripts/lib/foundry-command-registry.js +241 -0
- package/package-dist/scripts/lib/foundry-command-spec.d.ts +1 -0
- package/package-dist/scripts/lib/foundry-command-spec.js +1 -0
- package/package-dist/scripts/lib/foundry-decision-owners.d.ts +17 -0
- package/package-dist/scripts/lib/foundry-decision-owners.js +68 -0
- package/package-dist/scripts/lib/foundry-decision-routing.d.ts +3 -0
- package/package-dist/scripts/lib/foundry-decision-routing.js +38 -0
- package/package-dist/scripts/lib/foundry-execution-admission.d.ts +33 -0
- package/package-dist/scripts/lib/foundry-execution-admission.js +225 -0
- package/package-dist/scripts/lib/foundry-execution-attempt.d.ts +11 -0
- package/package-dist/scripts/lib/foundry-execution-attempt.js +33 -0
- package/package-dist/scripts/lib/foundry-execution-context-format.d.ts +18 -0
- package/package-dist/scripts/lib/foundry-execution-context-format.js +83 -0
- package/package-dist/scripts/lib/foundry-facade-store.d.ts +25 -0
- package/package-dist/scripts/lib/foundry-facade-store.js +449 -0
- package/package-dist/scripts/lib/foundry-finalize-owners.d.ts +21 -0
- package/package-dist/scripts/lib/foundry-finalize-owners.js +203 -0
- package/package-dist/scripts/lib/foundry-identity-owners.d.ts +13 -0
- package/package-dist/scripts/lib/foundry-identity-owners.js +58 -0
- package/package-dist/scripts/lib/foundry-managed-host.d.ts +7 -0
- package/package-dist/scripts/lib/foundry-managed-host.js +173 -0
- package/package-dist/scripts/lib/foundry-migration-adoption-plan.d.ts +39 -0
- package/package-dist/scripts/lib/foundry-migration-adoption-plan.js +467 -0
- package/package-dist/scripts/lib/foundry-migration-adoption.d.ts +31 -0
- package/package-dist/scripts/lib/foundry-migration-adoption.js +187 -0
- package/package-dist/scripts/lib/foundry-migration-authority.d.ts +42 -0
- package/package-dist/scripts/lib/foundry-migration-authority.js +280 -0
- package/package-dist/scripts/lib/foundry-migration-inventory.d.ts +31 -0
- package/package-dist/scripts/lib/foundry-migration-inventory.js +148 -0
- package/package-dist/scripts/lib/foundry-migration-plan.d.ts +48 -0
- package/package-dist/scripts/lib/foundry-migration-plan.js +234 -0
- package/package-dist/scripts/lib/foundry-migration-replay.d.ts +3 -0
- package/package-dist/scripts/lib/foundry-migration-replay.js +134 -0
- package/package-dist/scripts/lib/foundry-migration-stage.d.ts +15 -0
- package/package-dist/scripts/lib/foundry-migration-stage.js +152 -0
- package/package-dist/scripts/lib/foundry-migration-transfer-io.d.ts +13 -0
- package/package-dist/scripts/lib/foundry-migration-transfer-io.js +226 -0
- package/package-dist/scripts/lib/foundry-migration-transfer.d.ts +36 -0
- package/package-dist/scripts/lib/foundry-migration-transfer.js +350 -0
- package/package-dist/scripts/lib/foundry-operation-result.d.ts +71 -0
- package/package-dist/scripts/lib/foundry-operation-result.js +264 -0
- package/package-dist/scripts/lib/foundry-owner-execution-store.d.ts +319 -0
- package/package-dist/scripts/lib/foundry-owner-execution-store.js +293 -0
- package/package-dist/scripts/lib/foundry-owner-readback.d.ts +22 -0
- package/package-dist/scripts/lib/foundry-owner-readback.js +189 -0
- package/package-dist/scripts/lib/foundry-owner-trace-acceptance.d.ts +15 -0
- package/package-dist/scripts/lib/foundry-owner-trace-acceptance.js +68 -0
- package/package-dist/scripts/lib/foundry-package-contract.d.ts +56 -0
- package/package-dist/scripts/lib/foundry-package-contract.js +392 -0
- package/package-dist/scripts/lib/foundry-private-path.d.ts +2 -0
- package/package-dist/scripts/lib/foundry-private-path.js +20 -0
- package/package-dist/scripts/lib/foundry-runtime-cache.d.ts +3 -0
- package/package-dist/scripts/lib/foundry-runtime-cache.js +25 -0
- package/package-dist/scripts/lib/foundry-runtime-command-policy.d.ts +20 -0
- package/package-dist/scripts/lib/foundry-runtime-command-policy.js +173 -0
- package/package-dist/scripts/lib/foundry-runtime-context-types.d.ts +59 -0
- package/package-dist/scripts/lib/foundry-runtime-context-types.js +1 -0
- package/package-dist/scripts/lib/foundry-runtime-context.d.ts +27 -0
- package/package-dist/scripts/lib/foundry-runtime-context.js +668 -0
- package/package-dist/scripts/lib/foundry-runtime-environment.d.ts +9 -0
- package/package-dist/scripts/lib/foundry-runtime-environment.js +90 -0
- package/package-dist/scripts/lib/foundry-runtime-error.d.ts +4 -0
- package/package-dist/scripts/lib/foundry-runtime-error.js +8 -0
- package/package-dist/scripts/lib/foundry-runtime-identity.d.ts +18 -0
- package/package-dist/scripts/lib/foundry-runtime-identity.js +127 -0
- package/package-dist/scripts/lib/foundry-runtime-paths.d.ts +16 -0
- package/package-dist/scripts/lib/foundry-runtime-paths.js +159 -0
- package/package-dist/scripts/lib/foundry-runtime-qualification.d.ts +66 -0
- package/package-dist/scripts/lib/foundry-runtime-qualification.js +223 -0
- package/package-dist/scripts/lib/foundry-runtime-selection-record.d.ts +16 -0
- package/package-dist/scripts/lib/foundry-runtime-selection-record.js +32 -0
- package/package-dist/scripts/lib/foundry-runtime-selection.d.ts +14 -0
- package/package-dist/scripts/lib/foundry-runtime-selection.js +123 -0
- package/package-dist/scripts/lib/foundry-runtime-utils.d.ts +178 -0
- package/package-dist/scripts/lib/foundry-runtime-utils.js +603 -0
- package/package-dist/scripts/lib/foundry-semantic-input.d.ts +30 -0
- package/package-dist/scripts/lib/foundry-semantic-input.js +132 -0
- package/package-dist/scripts/lib/foundry-task-authorization.d.ts +68 -0
- package/package-dist/scripts/lib/foundry-task-authorization.js +350 -0
- package/package-dist/scripts/lib/foundry-task-io.d.ts +18 -0
- package/package-dist/scripts/lib/foundry-task-io.js +92 -0
- package/package-dist/scripts/lib/foundry-task-registration.d.ts +6 -0
- package/package-dist/scripts/lib/foundry-task-registration.js +384 -0
- package/package-dist/scripts/lib/foundry-task-start-spec.d.ts +34 -0
- package/package-dist/scripts/lib/foundry-task-start-spec.js +161 -0
- package/package-dist/scripts/lib/foundry-task-store.d.ts +18 -0
- package/package-dist/scripts/lib/foundry-task-store.js +466 -0
- package/package-dist/scripts/lib/foundry-task-types.d.ts +99 -0
- package/package-dist/scripts/lib/foundry-task-types.js +1 -0
- package/package-dist/scripts/lib/foundry-workflow-approval-continuation.d.ts +6 -0
- package/package-dist/scripts/lib/foundry-workflow-approval-continuation.js +136 -0
- package/package-dist/scripts/lib/foundry-workflow-assessment.d.ts +3 -0
- package/package-dist/scripts/lib/foundry-workflow-assessment.js +231 -0
- package/package-dist/scripts/lib/foundry-workflow-authorization.d.ts +22 -0
- package/package-dist/scripts/lib/foundry-workflow-authorization.js +174 -0
- package/package-dist/scripts/lib/foundry-workflow-context.d.ts +3 -0
- package/package-dist/scripts/lib/foundry-workflow-context.js +99 -0
- package/package-dist/scripts/lib/foundry-workflow-decisions.d.ts +18 -0
- package/package-dist/scripts/lib/foundry-workflow-decisions.js +123 -0
- package/package-dist/scripts/lib/foundry-workflow-execution.d.ts +8 -0
- package/package-dist/scripts/lib/foundry-workflow-execution.js +248 -0
- package/package-dist/scripts/lib/foundry-workflow-finalize.d.ts +13 -0
- package/package-dist/scripts/lib/foundry-workflow-finalize.js +264 -0
- package/package-dist/scripts/lib/foundry-workflow-identity-apply.d.ts +14 -0
- package/package-dist/scripts/lib/foundry-workflow-identity-apply.js +159 -0
- package/package-dist/scripts/lib/foundry-workflow-identity.d.ts +6 -0
- package/package-dist/scripts/lib/foundry-workflow-identity.js +153 -0
- package/package-dist/scripts/lib/foundry-workflow-import.d.ts +4 -0
- package/package-dist/scripts/lib/foundry-workflow-import.js +70 -0
- package/package-dist/scripts/lib/foundry-workflow-io.d.ts +11 -0
- package/package-dist/scripts/lib/foundry-workflow-io.js +77 -0
- package/package-dist/scripts/lib/foundry-workflow-reference-verify.d.ts +41 -0
- package/package-dist/scripts/lib/foundry-workflow-reference-verify.js +266 -0
- package/package-dist/scripts/lib/foundry-workflow-rows.d.ts +2 -0
- package/package-dist/scripts/lib/foundry-workflow-rows.js +47 -0
- package/package-dist/scripts/lib/foundry-workflow-semantic.d.ts +5 -0
- package/package-dist/scripts/lib/foundry-workflow-semantic.js +367 -0
- package/package-dist/scripts/lib/foundry-workflow-state.d.ts +37 -0
- package/package-dist/scripts/lib/foundry-workflow-state.js +158 -0
- package/package-dist/scripts/lib/full-context-proof.d.ts +51 -0
- package/package-dist/scripts/lib/full-context-proof.js +932 -0
- package/package-dist/scripts/lib/identity-preflight-artifacts.d.ts +184 -0
- package/package-dist/scripts/lib/identity-preflight-artifacts.js +573 -0
- package/package-dist/scripts/lib/identity-preflight-proof.d.ts +117 -0
- package/package-dist/scripts/lib/identity-preflight-proof.js +341 -0
- package/package-dist/scripts/lib/identity-reference-rewrite-utils.d.ts +147 -0
- package/package-dist/scripts/lib/identity-reference-rewrite-utils.js +817 -0
- package/package-dist/scripts/lib/import-curation/authoring-packages.d.ts +28 -0
- package/package-dist/scripts/lib/import-curation/authoring-packages.js +92 -0
- package/package-dist/scripts/lib/import-curation/curation-cleanup.d.ts +32 -0
- package/package-dist/scripts/lib/import-curation/curation-cleanup.js +203 -0
- package/package-dist/scripts/lib/import-curation/curation-gate.d.ts +47 -0
- package/package-dist/scripts/lib/import-curation/curation-gate.js +528 -0
- package/package-dist/scripts/lib/import-curation/internal/artifact-inputs.d.ts +24 -0
- package/package-dist/scripts/lib/import-curation/internal/artifact-inputs.js +152 -0
- package/package-dist/scripts/lib/import-curation/internal/authoring-patch-workflow.d.ts +3 -0
- package/package-dist/scripts/lib/import-curation/internal/authoring-patch-workflow.js +3 -0
- package/package-dist/scripts/lib/import-curation/internal/authoring-task-workflow.d.ts +1 -0
- package/package-dist/scripts/lib/import-curation/internal/authoring-task-workflow.js +1 -0
- package/package-dist/scripts/lib/import-curation/internal/context-inputs.d.ts +56 -0
- package/package-dist/scripts/lib/import-curation/internal/context-inputs.js +206 -0
- package/package-dist/scripts/lib/import-curation/internal/curation-gate-workflow.d.ts +14 -0
- package/package-dist/scripts/lib/import-curation/internal/curation-gate-workflow.js +14 -0
- package/package-dist/scripts/lib/import-curation/internal/dataset-payload.d.ts +70 -0
- package/package-dist/scripts/lib/import-curation/internal/dataset-payload.js +141 -0
- package/package-dist/scripts/lib/import-curation/internal/dataset-types.d.ts +25 -0
- package/package-dist/scripts/lib/import-curation/internal/dataset-types.js +45 -0
- package/package-dist/scripts/lib/import-curation/internal/full-context-proof.d.ts +129 -0
- package/package-dist/scripts/lib/import-curation/internal/full-context-proof.js +552 -0
- package/package-dist/scripts/lib/import-curation/internal/hash-utils.d.ts +2 -0
- package/package-dist/scripts/lib/import-curation/internal/hash-utils.js +10 -0
- package/package-dist/scripts/lib/import-curation/internal/mutation-manifest-workflow.d.ts +15 -0
- package/package-dist/scripts/lib/import-curation/internal/mutation-manifest-workflow.js +15 -0
- package/package-dist/scripts/lib/import-curation/internal/prewrite-cleanup.d.ts +31 -0
- package/package-dist/scripts/lib/import-curation/internal/prewrite-cleanup.js +467 -0
- package/package-dist/scripts/lib/import-curation/internal/profiles-config.d.ts +47 -0
- package/package-dist/scripts/lib/import-curation/internal/profiles-config.js +88 -0
- package/package-dist/scripts/lib/import-curation/internal/runtime-io.d.ts +23 -0
- package/package-dist/scripts/lib/import-curation/internal/runtime-io.js +132 -0
- package/package-dist/scripts/lib/import-curation/internal/trace-summary.d.ts +53 -0
- package/package-dist/scripts/lib/import-curation/internal/trace-summary.js +114 -0
- package/package-dist/scripts/lib/import-curation/internal/workflow-authoring-tasks.d.ts +141 -0
- package/package-dist/scripts/lib/import-curation/internal/workflow-authoring-tasks.js +854 -0
- package/package-dist/scripts/lib/import-curation/internal/workflow-decision-apply-context.d.ts +20 -0
- package/package-dist/scripts/lib/import-curation/internal/workflow-decision-apply-context.js +46 -0
- package/package-dist/scripts/lib/import-curation/internal/workflow-decision-full-context.d.ts +110 -0
- package/package-dist/scripts/lib/import-curation/internal/workflow-decision-full-context.js +782 -0
- package/package-dist/scripts/lib/import-curation/internal/workflow-dry-run-context.d.ts +24 -0
- package/package-dist/scripts/lib/import-curation/internal/workflow-dry-run-context.js +191 -0
- package/package-dist/scripts/lib/import-curation/internal/workflow-evidence-scope.d.ts +80 -0
- package/package-dist/scripts/lib/import-curation/internal/workflow-evidence-scope.js +359 -0
- package/package-dist/scripts/lib/import-curation/internal/workflow-identity-decision-context.d.ts +146 -0
- package/package-dist/scripts/lib/import-curation/internal/workflow-identity-decision-context.js +381 -0
- package/package-dist/scripts/lib/import-curation/internal/workflow-identity-preflight.d.ts +223 -0
- package/package-dist/scripts/lib/import-curation/internal/workflow-identity-preflight.js +1079 -0
- package/package-dist/scripts/lib/import-curation/internal/workflow-patch-collect.d.ts +41 -0
- package/package-dist/scripts/lib/import-curation/internal/workflow-patch-collect.js +412 -0
- package/package-dist/scripts/lib/import-curation/internal/workflow-patch-evidence-context.d.ts +117 -0
- package/package-dist/scripts/lib/import-curation/internal/workflow-patch-evidence-context.js +278 -0
- package/package-dist/scripts/lib/import-curation/internal/workflow-patch-evidence.d.ts +59 -0
- package/package-dist/scripts/lib/import-curation/internal/workflow-patch-evidence.js +593 -0
- package/package-dist/scripts/lib/import-curation/internal/workflow-queue-context.d.ts +58 -0
- package/package-dist/scripts/lib/import-curation/internal/workflow-queue-context.js +263 -0
- package/package-dist/scripts/lib/import-curation/internal/workflow-reference-closure.d.ts +177 -0
- package/package-dist/scripts/lib/import-curation/internal/workflow-reference-closure.js +812 -0
- package/package-dist/scripts/lib/import-curation/internal/workflow-row-transform-context.d.ts +159 -0
- package/package-dist/scripts/lib/import-curation/internal/workflow-row-transform-context.js +466 -0
- package/package-dist/scripts/lib/import-curation/internal/workflow-semantic-actions.d.ts +152 -0
- package/package-dist/scripts/lib/import-curation/internal/workflow-semantic-actions.js +1377 -0
- package/package-dist/scripts/lib/import-curation/internal/workflow-source-reference-context.d.ts +38 -0
- package/package-dist/scripts/lib/import-curation/internal/workflow-source-reference-context.js +116 -0
- package/package-dist/scripts/lib/import-curation/mutation-manifest.d.ts +51 -0
- package/package-dist/scripts/lib/import-curation/mutation-manifest.js +542 -0
- package/package-dist/scripts/lib/import-curation/patch-collect.d.ts +18 -0
- package/package-dist/scripts/lib/import-curation/patch-collect.js +172 -0
- package/package-dist/scripts/lib/import-curation/profiles.d.ts +1 -0
- package/package-dist/scripts/lib/import-curation/profiles.js +1 -0
- package/package-dist/scripts/lib/import-curation/trace-summary.d.ts +1 -0
- package/package-dist/scripts/lib/import-curation/trace-summary.js +1 -0
- package/package-dist/scripts/lib/oauth-session-reference.d.ts +1 -0
- package/package-dist/scripts/lib/oauth-session-reference.js +20 -0
- package/package-dist/scripts/lib/post-authoring-finalize-utils.d.ts +95 -0
- package/package-dist/scripts/lib/post-authoring-finalize-utils.js +548 -0
- package/package-dist/scripts/lib/post-write-root-proof.d.ts +44 -0
- package/package-dist/scripts/lib/post-write-root-proof.js +169 -0
- package/package-dist/scripts/lib/reference-description-text.d.ts +2 -0
- package/package-dist/scripts/lib/reference-description-text.js +12 -0
- package/package-dist/scripts/lib/remote-verification-accepted-diff.d.ts +42 -0
- package/package-dist/scripts/lib/remote-verification-accepted-diff.js +424 -0
- package/package-dist/scripts/lib/same-identity-commit-recovery.d.ts +8 -0
- package/package-dist/scripts/lib/same-identity-commit-recovery.js +52 -0
- package/package-dist/scripts/lib/source-semantics.d.ts +255 -0
- package/package-dist/scripts/lib/source-semantics.js +888 -0
- package/package-dist/scripts/lib/stage-contract.d.ts +36 -0
- package/package-dist/scripts/lib/stage-contract.js +25 -0
- package/package-dist/scripts/lib/task-authorization.d.ts +84 -0
- package/package-dist/scripts/lib/task-authorization.js +210 -0
- package/package-dist/scripts/lib/tidas-adapter.d.ts +113 -0
- package/package-dist/scripts/lib/tidas-adapter.js +525 -0
- package/package-dist/scripts/lib/tidas-language-utils.d.ts +8 -0
- package/package-dist/scripts/lib/tidas-language-utils.js +206 -0
- package/package-dist/scripts/lib/tidas-row-utils.d.ts +70 -0
- package/package-dist/scripts/lib/tidas-row-utils.js +225 -0
- package/package-dist/scripts/lib/trace-coverage.d.ts +53 -0
- package/package-dist/scripts/lib/trace-coverage.js +178 -0
- package/package-dist/scripts/package-entry.d.ts +2 -0
- package/package-dist/scripts/package-entry.js +4 -0
- package/package-dist/scripts/public-api.d.ts +80 -0
- package/package-dist/scripts/public-api.js +28 -0
- package/package-dist/scripts/runtime-entry.d.ts +23 -0
- package/package-dist/scripts/runtime-entry.js +424 -0
- package/package.json +93 -0
- package/specs/canonical-support/flow-properties-unit-groups.json +2692 -0
- package/specs/import-profiles.json +118 -0
- package/specs/prewrite-content-policy.json +105 -0
- package/specs/schemas/authorization-derivation.schema.json +34 -0
- package/specs/schemas/execution-context.schema.json +68 -0
- package/specs/schemas/foundry-authorization-input.schema.json +120 -0
- package/specs/schemas/foundry-facade-request-index.schema.json +78 -0
- package/specs/schemas/foundry-managed-runtime.schema.json +122 -0
- package/specs/schemas/foundry-migration-activation.schema.json +213 -0
- package/specs/schemas/foundry-migration-adoption-plan.schema.json +548 -0
- package/specs/schemas/foundry-migration-transfer-receipt.schema.json +93 -0
- package/specs/schemas/foundry-operation-result.schema.json +147 -0
- package/specs/schemas/foundry-package-descriptor.schema.json +134 -0
- package/specs/schemas/foundry-runtime-selection.schema.json +59 -0
- package/specs/schemas/foundry-semantic-input.schema.json +36 -0
- package/specs/schemas/foundry-task-start.schema.json +123 -0
- package/specs/schemas/foundry-workspace-migration-pending.schema.json +17 -0
- package/specs/schemas/foundry-workspace-migration-plan.schema.json +59 -0
- package/specs/schemas/foundry-workspace-migration-transfer-plan.schema.json +357 -0
- package/specs/schemas/foundry-workspace-v2.schema.json +70 -0
- package/specs/schemas/runtime-qualification.schema.json +63 -0
- package/specs/schemas/task-authorization.schema.json +154 -0
- package/specs/schemas/tidas-runtime-expectation.schema.json +54 -0
|
@@ -0,0 +1,218 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Foundry Public Runtime Protocol v1
|
|
3
|
+
docType: contract
|
|
4
|
+
scope: repo
|
|
5
|
+
status: active
|
|
6
|
+
authoritative: true
|
|
7
|
+
owner: tiangong-lca-data-foundry
|
|
8
|
+
language: en
|
|
9
|
+
whenToUse:
|
|
10
|
+
- when implementing the Foundry facade or consuming its next actions
|
|
11
|
+
whenToUpdate:
|
|
12
|
+
- when public command names, result envelopes or exit semantics change
|
|
13
|
+
checkPaths:
|
|
14
|
+
- scripts/runtime-entry.ts
|
|
15
|
+
- scripts/foundry-runtime.ts
|
|
16
|
+
- scripts/foundry-facade.ts
|
|
17
|
+
- scripts/lib/foundry-operation-result.ts
|
|
18
|
+
- scripts/lib/foundry-task-start-spec.ts
|
|
19
|
+
- scripts/lib/foundry-facade-store.ts
|
|
20
|
+
- scripts/lib/foundry-migration-inventory.ts
|
|
21
|
+
- scripts/lib/foundry-runtime-command-policy.ts
|
|
22
|
+
- scripts/lib/foundry-runtime-qualification.ts
|
|
23
|
+
- scripts/lib/foundry-execution-admission.ts
|
|
24
|
+
- scripts/package-entry.ts
|
|
25
|
+
- scripts/public-api.ts
|
|
26
|
+
- scripts/lib/foundry-package-contract.ts
|
|
27
|
+
- specs/schemas/foundry-operation-result.schema.json
|
|
28
|
+
- specs/schemas/foundry-task-start.schema.json
|
|
29
|
+
- specs/schemas/foundry-facade-request-index.schema.json
|
|
30
|
+
- specs/schemas/foundry-workspace-migration-plan.schema.json
|
|
31
|
+
- test/scenarios/foundry-public-facade.test.mts
|
|
32
|
+
- test/scenarios/foundry-facade-request-store.test.mts
|
|
33
|
+
- test/scenarios/foundry-package-consumer.test.mts
|
|
34
|
+
- docs/public-runtime-contract.md
|
|
35
|
+
lastReviewedAt: 2026-09-09
|
|
36
|
+
lastReviewedCommit: 21f10ac1643798aade3bd930c99785a0e6eaf0d9
|
|
37
|
+
lastReviewedNote: "Reviewed for Foundry #128: exact version-only 0.1.2 follows qualified main21f10ac via a fresh release event after the prior GitHub run could not restart. Only package identity and review metadata change; CLI0.1.12, TIDAS0.3.0, full source/public qualification, signing, first-identity handoff and final F1 acceptance remain unchanged and required."
|
|
38
|
+
related:
|
|
39
|
+
- docs/runtime-context-contract.md
|
|
40
|
+
- docs/task-authorization-contract.md
|
|
41
|
+
- docs/package-distribution-contract.md
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
# Public runtime protocol
|
|
45
|
+
|
|
46
|
+
This is the implemented v1 facade protocol for `@tiangong-lca/foundry` and its `tiangong-foundry` binary. W05 supplies the six hierarchical operations on top of W04 context/task/qualification owners. W06 adds the public-only compiled entry, typed host API, descriptor-bound file closure and source-free installed-candidate qualification. The candidate is not a registry release or F1 until W08 completes provenance, platform-component and publication gates. Internal flat command names remain repository owner interfaces and the existing developer entry remains behavior-compatible.
|
|
47
|
+
|
|
48
|
+
## Commands
|
|
49
|
+
|
|
50
|
+
| Command | Contract |
|
|
51
|
+
| --- | --- |
|
|
52
|
+
| `tiangong-foundry workspace init --workspace <path> --json` | Atomically initialize/verify the versioned workspace; preserve existing records and reject unversioned state requiring migration. No login or business write. |
|
|
53
|
+
| `tiangong-foundry doctor --workspace <path> [--expected-project-ref <ref> --expected-user-id <uuid> [--session-reference <path>]] --json` | Read-only runtime, asset, workspace and account-readiness diagnostics. It checks only bounded reference metadata, never session contents, repository maintenance, Git, login or download. |
|
|
54
|
+
| `tiangong-foundry task start --workspace <path> --spec <file> --json` | Validate the strict `task-start.v1` spec and independently capture its selected sources/optional seed. A relative spec path resolves from the selected workspace root. Request ID, actor, lane, profile, account intent and preparation live in the reviewed spec. |
|
|
55
|
+
| `tiangong-foundry task status --workspace <path> --task <id> --actor <id> --json` | Reconstruct the exact registered request revision and inspect its current task/index/attempt state. Actor intent is supplied independently on every call. |
|
|
56
|
+
| `tiangong-foundry task resume --workspace <path> --task <id> --actor <id> [--semantic-input <file> | --authorization-input <file>] --json` | Continue registered preparation, accept bound semantic input/approval, or execute and verify a sealed owner scope through the qualified CLI. Consumed/ambiguous mutation state is readback-only and never replayed. |
|
|
57
|
+
| `tiangong-foundry workspace migrate --workspace <path> --dry-run --json` | Inventory old state and produce a content-bound migration plan. Applying that plan is a separately explicit operation defined by W10. |
|
|
58
|
+
|
|
59
|
+
The CLI-owned `tiangong-lca runtime ensure/status` manages qualified components only; it does not initialize a Foundry job or grant data permissions. Skills invoke the Foundry facade and its next actions rather than rebuilding its task state machine.
|
|
60
|
+
|
|
61
|
+
The installed bin calls `runFoundryPublicCommand`; any non-facade name returns `operation=unknown` and cannot enter the developer dispatcher. `runtime-entry.ts` remains the shared implementation adapter. The repository-maintenance `pnpm doctor` and flat `scripts/foundry.ts doctor` command remain a separate source-only developer surface with their existing behavior.
|
|
62
|
+
|
|
63
|
+
For a CLI-managed process, the bin first receives the inherited host context and validates its full manifest, installed entry and inventory-bound Foundry runtime metadata. This completes before any workspace operation. An invalid managed context never falls back to unmanaged execution. Plain installed calls without IPC retain their existing behavior. The package distribution contract owns the metadata shape and read/write/target bindings.
|
|
64
|
+
|
|
65
|
+
Input changes create an explicit new revision with retained history. A new revision, directory, runtime version or request id never resets a consumed mutation. Migration never treats historical locks or profile waivers as current approval.
|
|
66
|
+
|
|
67
|
+
## Task start and request revisions
|
|
68
|
+
|
|
69
|
+
`tiangong-foundry.task-start.v1` contains exact request and actor ids, one of the two lanes, profile, ordered target entity types, selected source paths, optional account intent, an optional selected JSON seed and at most one current local preparation (`dataset-curation-cleanup`). The source-evidence lane requires its seed to be one of the selected sources. Task start performs no authentication and stores no identity receipt.
|
|
70
|
+
|
|
71
|
+
The workspace request index key is the SHA-256 of workspace id plus request id. Task ids are deterministic `task-<complete-request-sha256>-rNNNN` values. A revision fingerprint binds the normalized spec and ordered canonical input path/bytes/SHA facts. Same request plus latest fingerprint is byte-idempotent, including concurrent starts. Any selected path, content, actor/account, lane/profile/entity or preparation change creates a predecessor-bound revision and preserves every earlier task directory and attempt. Interrupted creation recovers the same deterministic task before the index is published; a different spec returns an actionable recovery conflict until the original spec completes that index record.
|
|
72
|
+
|
|
73
|
+
Status and resume resolve a task only through its immutable task pointer and request revision, then apply the W04 task-store checks. Wrong actor and missing task return non-leaking envelopes. Files merely placed under a task directory are not artifacts or completion proof. An explicit local preparation retains the deterministic cleanup owner. Without that preparation, a packaged-import request first invokes qualified native conversion, then the exact CLI's contract-context preparation; a source-evidence request begins with contract context. Each resume advances one registered preparation, execution, or readback stage. Other work remains an ordered human action or a separately registered trusted command action; the facade does not invent or discover CommandSpecs by scanning files.
|
|
74
|
+
|
|
75
|
+
Native conversion uses the selected qualified TIDAS executable with an isolated environment. Automatic format detection omits the native `--from-format` option. Output files, the import report and the adapter result enter the existing content-bound task transaction. A converter-reported failure blocks later stages; successful conversion alone is not task completion. CLI context packs preserve their actual task-contained file references and enter the same index. A new invocation never adopts an interrupted, unindexed context generation.
|
|
76
|
+
|
|
77
|
+
After context preparation, the facade materializes typed row arrays from the selected seed or the primary native dataset tree. Process-bundle copies remain evidence and are not counted as additional source rows. Derived inputs must have a verified producer in the same task index. Context preparation includes the converted dependency types as well as the requested types.
|
|
78
|
+
|
|
79
|
+
The assessment stage invokes native schema validation, CLI deterministic QA and the existing curation/authoring owners on the same indexed row files. A process collection also receives a CLI-owned curation queue containing its flow and support closure. Concrete contact/source/unitgroup/flowproperty checks match `support` queue entries only when the underlying row type agrees. A complete native validation batch with data-issues exit code 2 still produces the compatibility report needed for repair.
|
|
80
|
+
|
|
81
|
+
The compatibility report retains native diagnostic fields and supplies curation's `code` and JSON-pointer `path` from the native issue code/location. Row normalization uses the canonical `json` payload slot for typed API wrappers so native validation, curation and CLI patch application address the same domain payload while preserving row metadata and source lineage.
|
|
82
|
+
|
|
83
|
+
Curation blockers or authoring tasks produce `needs_input` with references to the registered reports and task manifests. Active row, schema, QA, curation and authoring files are checked before presenting that state; changed bytes block continuation. Public authoring artifacts omit developer-runner execution commands and retain full source/context evidence plus the required English guidance. Assessment readiness is distinct from semantic input acceptance, write authorization and final completion.
|
|
84
|
+
|
|
85
|
+
After local semantic work is ready, a further resume performs process/flow identity preflight through the qualified CLI. The task spec must already identify the intended project and user; otherwise the result is `needs_auth`. The host may supply explicit OAuth public configuration or process-only headless authentication through `FoundryFacadeOptions.authentication`. Initialization and task start remain credential-free. The facade never inherits ambient tokens, CLI overrides, Node options or preflight result caches.
|
|
86
|
+
|
|
87
|
+
Preflight reuses the existing request builder, query audit, receipt-bound runner and index merger. Requests target current unwrapped payloads and retain source trace context. Remote reads finish before a local transaction registers their immutable evidence; that transaction cannot replay a remote operation. Registration rechecks current rows under the task lock. Failed reads remain visible as `needs_input` and a later resume may retry the read-only stage. Status never performs a search. Successful preflight invalidates the earlier assessment, and the next resume re-runs curation against its exact identity index. Manual review becomes dedicated identity work even for the generic profile. This read evidence supplies decision context; submitting a bound identity decision remains separate from write authorization.
|
|
88
|
+
|
|
89
|
+
An executable next action contains Node/active source-or-emitted entry argv, `cwd=workspaceRoot` and purpose. Its verified binding digest covers every executable field; workspace, task and actor are explicit argv values, while task lookup revalidates the immutable revision fingerprint and current runtime/input facts before work. It has no `display` authority. A final restricted data CommandSpec still requires the W04 execution-context/identity/authorization gate; Owner execution validates it immediately before the first dispatch.
|
|
90
|
+
|
|
91
|
+
After ready assessment and required identity preflight, resume invokes the existing finalize owner. It preserves reference/source/contact/canonical repair, cleanup, native schema, deterministic QA, location audit, curation, dry-run, remote reference verification and mutation/handoff report ordering. Each dataset type uses its own contract pack; Unit Group and Flow Property rows use the owner's support mode separately. Finalization dispatch accepts only local checks, explicit `--dry-run` operations and read-only remote verification, never `--commit`.
|
|
92
|
+
|
|
93
|
+
Finalization gets a new output generation and fresh current-type identity requests, retaining dependency evidence without overwriting prior indexed reports. Selected producer lineage is verified before remote reads and current rows are rechecked under the capture lock. `foundry-finalize.json` binds the exact rows and assessment. A ready result becomes `needs_input` with `permissions.required` and a current-approval action; blocked results expose their owner reports. Repeating unchanged resume returns the same pending finalization without repeating remote reads. Reference-only scopes continue through independent canonical verification. Sealed approval continues through the owner execution stages described below.
|
|
94
|
+
|
|
95
|
+
## Owner execution and recovery
|
|
96
|
+
|
|
97
|
+
A resume after sealed approval first records an immutable owner execution request. It binds the final rows, capsule, exact commit/verify CommandSpecs, account and CLI batch content/policy contracts. The next resume acquires a per-scope lock, obtains fresh identity and revalidates the existing execution admission. No remote mutation runs inside a replayable local task transaction.
|
|
98
|
+
|
|
99
|
+
Before the first dispatch, the batch attempt-start event durably registers an immutable consumed marker and flushes its append-only event. Only the dedicated consume operation may write that marker under `attempts/owner-v1/<scope>/consumed.json`. The indexed marker preserves no-replay state even if mutable event logs disappear. Unknown, truncated, conflicting or altered attempt evidence cannot permit another write.
|
|
100
|
+
|
|
101
|
+
Each owner command is dispatched once as executable plus argv with explicit authentication and `shell=false`. Commit stdout must match its contained report. A confirmed success requires the existing closeout checks and fresh independent root, owner, state, payload and reference verification. Lost or unknown responses and narrowly recognized same-identity conflicts use independent readback; known business failures remain unresolved. Recovery does not require the old write grant to remain unexpired and cannot change the original request. The CLI batch item's verified/recovered result determines success; aggregate batch completion alone is insufficient.
|
|
102
|
+
|
|
103
|
+
Every readback gets a fresh output directory. A verified result binds the exact input, report and JSONL check hashes. Completed scopes preserve their final rows while dependent scopes are finalized again after new verified progress. Reference-only partitions use the separate canonical verification stage below; semantic changes cannot replace consumed scope rows.
|
|
104
|
+
|
|
105
|
+
## Canonical reference verification
|
|
106
|
+
|
|
107
|
+
Identity reuse retains original source rows in the reference partition and selects different canonical targets in its rewrite evidence. After current finalization, resume verifies those selected table/id/version targets through the qualified CLI `dataset verify-remote --root-policy existing`. Its generated query contains only reference descriptors. It does not compare the source payload with the reused dataset or construct a write candidate.
|
|
108
|
+
|
|
109
|
+
The verification scope binds current row metadata, exact identity/partition/rewrite artifact facts, canonical targets and the current account. Each original reference row needs one matching canonical decision. A fresh CLI identity and explicit authentication environment provide the account's current read visibility; missing or hidden targets remain unresolved.
|
|
110
|
+
|
|
111
|
+
Success requires matching fresh stdout/report bytes and exactly one successful JSONL check for each requested target, with matching row index, table, id, exact version and latest version. Missing, duplicate, substituted or outdated checks cannot establish completion even if the summary claims success. Each attempt has a new output directory; local capture rechecks the current scope under the task lock. No mutation or write grant is involved.
|
|
112
|
+
|
|
113
|
+
Status performs local evidence verification only. Failed verification exposes `reference_verification_required` and a bound resume action for another read. A successful current result is reused without another remote query. Completion also requires every remaining write scope to have its independent owner readback. Changing an indexed report, query or check invalidates the proof and cannot preserve completed status.
|
|
114
|
+
|
|
115
|
+
## Authorization input
|
|
116
|
+
|
|
117
|
+
`--authorization-input` selects a strict `tiangong-foundry.authorization-input.v1` descriptor separately from semantic input. It binds task, actor, current finalization SHA-256, dataset type, `input_kind` (`current_rows` or `final_rows`), input SHA-256 and expected previous authorization-pointer SHA-256 (null for initial registration). It separately selects a grant file and unique user-decision/source-model evidence files with hashes. At least one user-decision item is required; each file is bounded to 8 MiB and the selection to 64 MiB. Credential and linked-file inputs are rejected. The grant's evidence references must use the selected canonical absolute paths, as required by the existing registration contract.
|
|
118
|
+
|
|
119
|
+
Finalization exposes per-scope `authorization_inputs` with independently computed bindings and input digests. These are review metadata, not grants. The trusted caller must select approval evidence from actual current user authorization; task output or grant text alone cannot supply approval. The existing validator checks the grant, current CLI identity and scope; registration rechecks current finalization while holding the task lock and uses the existing compare-and-swap pointer. Concurrent distinct initial grants cannot both activate.
|
|
120
|
+
|
|
121
|
+
For a ready `final_rows` scope, the runtime rebuilds the original owner handoff under the validated grant, binds CommandSpec artifacts to absolute final-row paths, and creates the existing execution capsule. It registers a `foundry-authorization.json` result; identical current submissions reuse it without re-authentication or another capsule. Projection requires the matching current finalization, active pointer digest and unexpired record. A sealed result is explicitly pending execution and never dispatches a mutation. `current_rows` registration records preparation approval. Subsequent resume re-finalizes the selected type under that current grant, then proves final-row lineage and derives/activates the exact successor before sealing. Actions, evidence, account/profile binding and expiry are unchanged. Equal-byte derived files reuse the original grant only after lineage proof. A capture interruption after activation resumes from the retained preparation approval and verifies the active grant is its exact derivation; it does not request another approval. Blocked re-finalization retains its reports without repeating remote reads. Existing authorization, capsule and no-replay rules remain authoritative for subsequent execution.
|
|
122
|
+
|
|
123
|
+
## Single-result envelope
|
|
124
|
+
|
|
125
|
+
### Semantic input
|
|
126
|
+
|
|
127
|
+
`--semantic-input` selects a `tiangong-foundry.semantic-input.v1` JSON descriptor. The descriptor binds the same task and actor, the current assessment artifact SHA-256, and a bounded `submissions` array. Each entry has `kind=patch`, `classification`, `location` or `identity`, the registered owner task's SHA-256, a selected input file and its SHA-256. File paths resolve from the explicit workspace. Duplicate work-item digests, unknown fields, credential paths and changed bytes are rejected. Each file is limited to 8 MiB and the complete selection to 64 MiB.
|
|
128
|
+
|
|
129
|
+
The public runtime independently resolves work through the current task index; a caller cannot supply a replacement manifest or runtime trust anchor. It snapshots the descriptor and selected patch bytes into a new task-owned generation, then uses a projection of the trusted authoring manifest to collect only the selected tasks. Original work items are unchanged. Public acceptance requires structured evidence, basis and the available required context kinds even when the historical profile did not demand them.
|
|
130
|
+
|
|
131
|
+
Patch inputs use the exact CLI's local `dataset patch apply`, with authoring-package and action-item closure checks. Classification and location inputs use their existing dedicated deterministic owners and exact task context-bundle checks. Assessment prepares their task, schema context, queue and template from current row findings; it does not select codes. Decision files accept the owner's JSON/JSONL forms. One submission may select only one owner per row type, requiring reassessment before another owner uses the changed rows. Public tasks omit developer-runner commands.
|
|
132
|
+
|
|
133
|
+
An output file alone is insufficient: only successful owner execution, `status=completed`, zero blockers and preserved row count can select repaired rows. Invalid proposals retain diagnostics and leave the current rows unchanged. A successful submission publishes a new indexed row manifest, preserves the predecessor, and makes a subsequent resume assess that new version. Identical accepted submissions are idempotent; different submissions against an old assessment are rejected. The current assessment is revalidated under the task lock before publication so concurrent submissions cannot overwrite each other.
|
|
134
|
+
|
|
135
|
+
Identity submission selects one task per call because reuse can affect other row types. Every decision must match a current task identity, its exact context bundle and its registered authoring-package snapshot and digest. Snapshot paths are checked before the owner may read them. Reuse requires the matching dataset table and explicit canonical id/version. The existing identity owner produces output, reference-reuse and unresolved partitions; their combined row contents must exactly preserve the input scope. A completed reuse also runs the existing process-reference rewrite owner, retaining original row metadata. Current row manifests retain identity and rewrite report references even when all local write candidates become reference reuse. A later assessment consumes those reports; changed row lineage requires a fresh preflight before write planning.
|
|
136
|
+
|
|
137
|
+
Unresolved or failed identity application retains its diagnostic partitions and leaves the previous rows current. Resolving or externalizing unresolved references remains necessary before a write handoff. Semantic input is local preparation: it grants no write permission and clears no attempts. Reference-only local resolution is not final task completion.
|
|
138
|
+
|
|
139
|
+
`--json` emits exactly one JSON object on stdout, followed by a newline. Progress goes to stderr. The schema identifier is `tiangong-foundry.operation-result.v1`; required fields are:
|
|
140
|
+
|
|
141
|
+
| Field | Meaning |
|
|
142
|
+
| --- | --- |
|
|
143
|
+
| `schema` | Exact protocol identifier. |
|
|
144
|
+
| `operation` | The public operation, e.g. `task.resume`. |
|
|
145
|
+
| `status` | One of the statuses in the exit table. |
|
|
146
|
+
| `task_id` | Task id or null for workspace operations. |
|
|
147
|
+
| `artifacts` | Typed artifact references with path/URI, role and content facts where applicable. |
|
|
148
|
+
| `blockers` | Stable codes, user-facing reasons and affected scopes. |
|
|
149
|
+
| `next_actions` | Ordered human steps or trusted executable-plus-argv actions bound to this task/revision. |
|
|
150
|
+
| `runtime_identity` | Qualified component versions/content identity and protocol versions; no environment dump. |
|
|
151
|
+
| `permissions` | Separate state (`not_required`, `required`, `granted` or `invalid`), requested actions and the relevant approval reference. |
|
|
152
|
+
|
|
153
|
+
Every command next action includes executable, argv, CWD, purpose and the relevant task/input/runtime binding. `binding_sha256` is the canonical `tiangong-foundry.command-next-action-binding.v1` digest over those exact executable fields; the envelope validator rejects any field drift. The registered task, actor and workspace travel as argv values and the emitted runtime entry is the first argv value. Human actions carry instructions and a stable action code. Display strings are explanatory only; consumers never execute shell text extracted from inputs, documents or logs. Account credentials, OAuth codes/tokens/cookies and session contents cannot appear in the envelope or diagnostics.
|
|
154
|
+
|
|
155
|
+
The machine schema is `specs/schemas/foundry-operation-result.schema.json`. File artifacts carry exact path/bytes/SHA facts; inline artifacts carry their serialized byte/hash facts. Success states have no blockers; every non-success state has at least one. Unknown hierarchical operations use `operation=unknown` and `needs_input`; extra positional or option fields are rejected before workspace mutation.
|
|
156
|
+
|
|
157
|
+
## Status and exit codes
|
|
158
|
+
|
|
159
|
+
| Status | Exit | Meaning |
|
|
160
|
+
| --- | --: | --- |
|
|
161
|
+
| `ready` | 0 | Current preparation is ready; no implication of write permission or task completion. |
|
|
162
|
+
| `running` | 0 | An identified operation continues; status must be queried through the same task. |
|
|
163
|
+
| `completed` | 0 | Current input/revision has all required completion and, where applicable, readback evidence. |
|
|
164
|
+
| `failed` | 1 | Execution or validation could not produce the requested operation result. |
|
|
165
|
+
| `needs_input` | 2 | Concrete missing input or task approval is required; permission state remains separate. |
|
|
166
|
+
| `needs_auth` | 3 | A trusted CLI/browser login or identity correction is required; no secret is requested in task JSON. |
|
|
167
|
+
| `blocked` | 4 | A gate or ambiguous/consumed operation prevents advancement; blockers identify the affected scopes. |
|
|
168
|
+
| `failed` with blocker `operation_interrupted` | 130 | Cancellation/interruption preserved evidence; mutation ambiguity follows no-replay/readback recovery. |
|
|
169
|
+
|
|
170
|
+
The process entry handles the first SIGINT/SIGTERM as a cooperative abort request and checks it before and after atomic facade boundaries. If an atomic local write finishes before the signal can be observed, the exit-130 result retains that evidence for idempotent status/resume. The one-shot handler is removed by the first signal, so a second signal uses the host's normal termination behavior. A completed operation already returned by the facade is not rewritten as interrupted afterward.
|
|
171
|
+
|
|
172
|
+
Unknown protocol/layout versions fail closed with `blocked` and a stable version blocker. Malformed public arguments/specs use `needs_input`. A child exit 0, empty queue, copied success report or successful download alone cannot produce `completed`.
|
|
173
|
+
|
|
174
|
+
`completed` requires either a current indexed `dataset-import-completion-report`, or verified execution results covering every current write scope with every current reference-only partition independently verified. The task store verifies producer plans, receipts and artifact hashes before either projection. A copied unindexed report cannot prove completion. Recognized consumed owner requests return `mutation_readback_required` and a bound readback continuation; unknown or malformed attempt state remains blocked. The facade never clears attempts or redispatches consumed mutations. Pre-observed cancellation returns `operation_interrupted` and exit 130 without creating state; installed-process signal qualification is repeated in W06.
|
|
175
|
+
|
|
176
|
+
Every facade revision also rechecks all retained predecessors in its request chain. Missing, changed or linked predecessor task/publication state blocks continuation. Any predecessor attempt blocks creating or resuming a descendant with `facade_predecessor_readback_required`, regardless of the attempt's declared outcome or changed input bytes/paths. The original task remains available for its owner status/readback. This guard checks current registered facade history; the migration owner additionally retains origin/scope evidence and rechecks it before execution admission across migrated workspaces and independently named requests.
|
|
177
|
+
|
|
178
|
+
## Runtime selection and migration seam
|
|
179
|
+
|
|
180
|
+
The public facade accepts CLI/TIDAS expectations only through its process-local host interface. Ordinary argv, task specs, `.env` and ambient `TIDAS_BIN`/expectation variables cannot select trust anchors. Without a host selection, doctor, start, status and local resume work and report `qualification.required`; child-required work must return the runtime qualification action. The managed bin now obtains this selection from the CLI IPC context and its verified component metadata. The final immutable production product manifest remains a W08 deliverable. The current exact CLI 0.1.12 constraint remains explicit rather than silently accepting a future version.
|
|
181
|
+
|
|
182
|
+
`workspace migrate --dry-run` recursively inventories only regular files/directories, rejects links and returns `tiangong-foundry.workspace-migration-plan.v1` as an inline content-bound artifact. It classifies control, local-preparation, terminal-success, attempted/unknown, authorization/account and unclassified paths. The public envelope is bounded to 10,000 entries and 64 directory levels. The total hashed inventory is bounded to 256 MiB. Files larger than 64 MiB and recognized credential/session files retain path/size/classification facts with `sha256=null`; their contents are not read by this inventory. The tree digest binds this observational inventory, not an atomic filesystem snapshot, so W10 must re-read and verify every selected source immediately before apply. It writes nothing. W10 owns application, rollback and detailed old-schema mapping.
|
|
183
|
+
|
|
184
|
+
## Prepared support authorization
|
|
185
|
+
|
|
186
|
+
Cleanup may change the byte representation of a Unit Group or Flow Property before its input-bound permission is reapplied. When the selected scope is blocked only by `reference_only_support_type_write_blocked` and the retained approval includes both its exact write action and `canonical_support_local_mint`, resume may derive the grant against the already indexed final-row lineage. It then re-finalizes that scope using the newly bound input and original approval origin. Actions, evidence, account/profile and expiry remain unchanged. Schema, content, reference and other blockers cannot enter this path.
|
|
187
|
+
|
|
188
|
+
Finalization records which authorization hash it used; a still-blocked result under that same grant is retained instead of repeatedly running the stage. Completed scopes preserve their original reports and final-row generations during both ordinary dependency finalization and later prepared-approval continuation. A ready scope with an already activated derived grant returns a bound continuation command to finish sealing, without requesting another approval.
|
|
189
|
+
|
|
190
|
+
## Account verification mode
|
|
191
|
+
|
|
192
|
+
The optional `account_intent.account_mode` task field selects `ordinary` or `production-test`; omission retains the existing ordinary behavior and serialized shape. An explicit mode participates in the request fingerprint. Its workspace/task account registration is immutable, so resuming the same task with a different effective mode is rejected. Migration task templates preserve the explicit mode while omitting session references. An explicitly selected host mode for the same account must agree with the task mode. Ambient `FOUNDRY_ACCOUNT_MODE` cannot set or change public task intent.
|
|
193
|
+
|
|
194
|
+
Finalization and sealed handoffs receive that registered mode explicitly, and stored execution requests recheck it. In ordinary mode, a failed root payload comparison may use the existing traceHash acceptance owner. The pinned public CLI reports completed remote-verification blockers with exit 1; the adapter distinguishes that data result from usage/native-tool exits before considering acceptance. It obtains a fresh payload through qualified CLI `flow get` or `process get` with explicit authentication, executable/argv and retained command/log artifacts. The fresh payload and selected local domain payload must match the original check's raw hashes; only then may equal payloads after removing `tiangongfoundry:importTraceSummary.traceHash` be accepted. Canonical `json` row envelopes are unwrapped without changing input files. Original failed verification files, fresh reads and separate acceptance evidence remain indexed.
|
|
195
|
+
|
|
196
|
+
Production-test mode never invokes traceHash acceptance: owner/state/identity/version and complete payload must match exactly. Other payload changes, mismatched fresh-read hashes, missing or hidden references, and unresolved checks remain blocking in every mode. Recovery stays read-only and cannot replay the consumed mutation.
|
|
197
|
+
|
|
198
|
+
## Authentication and permissions
|
|
199
|
+
|
|
200
|
+
CLI session ownership, fresh identity receipts and the existing explicit process-only headless contract remain authoritative. Workspace/task/actor intent applies on every host; a Codex thread id is supplemental. Doctor reports `not_requested`, `needs_auth` or `configured_unverified` from explicit intent and bounded session-reference metadata without reading it or claiming authentication. Actual restricted resume obtains a fresh CLI identity. Login never grants publish/delete/mint permission. Existing approval for an unchanged batch is reused after evidence validation; no per-row confirmation is introduced. When a new approval is necessary, preparation and reviewable mutation evidence come first.
|
|
201
|
+
|
|
202
|
+
The facade cannot authorize actions from source text or infer permission from a historical profile. Missing grants block only affected operations; independent preparation and ready scopes continue. User-facing summaries show stages, counts and concrete remedies, with versions/argv/hashes in diagnostic artifacts when needed.
|
|
203
|
+
|
|
204
|
+
Transfer planning adds `--to <destination> --actor <actor> --request <request>` and optional repeated `--stage-manifest <source-state-relative-path>` to the same dry-run operation. It produces `workspace-migration-transfer-plan.v2`, independently binds runtime and intent, observes source bytes again, and interprets selected historical attempt evidence without granting execution authority. Explicit adoption/apply/audit and runtime selection are defined by the migration contract. See [workspace migration](workspace-migration-contract.md). Both inventory and transfer paths reject unsupported hosts before legacy-state reads.
|
|
205
|
+
|
|
206
|
+
Explicit `--stage --plan <file>` copies the complete selected v2 source snapshot into an inactive migration area; `--audit --plan <file>` rechecks it. Both repeat independent transfer intent and `--input` selections. Pending markers cannot be initialized or used as active workspaces, and neither a staged receipt nor a historical declaration grants replay permission. `--adoption-dry-run` and `--apply` require independently selected task specifications and a trusted runtime host; successful application publishes only after current-owner preparation and audit.
|
|
207
|
+
|
|
208
|
+
The migration operation also accepts `--runtime-use --actor <id> --request <id> --access read|write` with an independently trusted host target manifest; file migration flags cannot be mixed with it. The host carries `workspaceAccess`, optional `runtimeManager`, `runtimeTarget`, `accountIntent` and `cacheBase` through the typed boundary. An explicit read selection never returns a preparation command from task status. Workspace pointers are selection intent, not manifest trust anchors.
|
|
209
|
+
|
|
210
|
+
Runtime selection from a managed installed package revalidates ownership of its current component cache before leasing current and target components. Rollback does not require the target to contain the executing package; its independently trusted current host manifest remains the ownership authority. A damaged, incomplete or unrelated cache fails before replacement beneath the running package, while ordinary workspace and source exclusions remain enforced.
|
|
211
|
+
|
|
212
|
+
A managed launch policy can supply a target manifest as a file already bound by the current trusted component inventory. `null` selects the current manifest. This supplies the existing `runtimeTarget` host seam without a manifest-path or digest option in ordinary argv. The same host also supplies its component-cache root, which is excluded from workspace operations before marker reads or writes.
|
|
213
|
+
|
|
214
|
+
`createFoundryWorkspaceAccess({ manifestBytes, expectedSha256, access })` is the public host bridge when bootstrap and Foundry load separate CLI SDK instances. It verifies the independently selected digest again with Foundry's own CLI instance. The host must obtain that expected digest from its trusted release/skill configuration; it must not derive it from workspace data or the bytes being checked. The bridge is not exposed through ordinary argv or task specifications.
|
|
215
|
+
|
|
216
|
+
Unexpected runtime failures retain the generic failure code and safe message; recognized filesystem/Node error codes may be included without raw exception text, paths or user data. This helps identify host failures while preserving the non-leaking error envelope.
|
|
217
|
+
|
|
218
|
+
Context, assessment and semantic stages allocate new task-contained directories with exclusive creation, including long Windows task paths. A prior generation is retained rather than reused after interruption.
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Foundry Runtime Context and Filesystem Contract
|
|
3
|
+
docType: contract
|
|
4
|
+
scope: repo
|
|
5
|
+
status: active
|
|
6
|
+
authoritative: true
|
|
7
|
+
owner: tiangong-lca-data-foundry
|
|
8
|
+
language: en
|
|
9
|
+
whenToUse:
|
|
10
|
+
- when resolving Foundry package assets or a user workspace
|
|
11
|
+
- when adapting an existing command owner to the consumer runtime
|
|
12
|
+
whenToUpdate:
|
|
13
|
+
- when runtime layout, root ownership, input facts or workspace initialization changes
|
|
14
|
+
checkPaths:
|
|
15
|
+
- package.json
|
|
16
|
+
- scripts/foundry-runtime.ts
|
|
17
|
+
- scripts/foundry-facade.ts
|
|
18
|
+
- scripts/runtime-entry.ts
|
|
19
|
+
- scripts/lib/foundry-runtime-context.ts
|
|
20
|
+
- scripts/lib/foundry-runtime-command-policy.ts
|
|
21
|
+
- scripts/lib/foundry-runtime-qualification.ts
|
|
22
|
+
- scripts/lib/foundry-execution-admission.ts
|
|
23
|
+
- scripts/lib/foundry-facade-store.ts
|
|
24
|
+
- scripts/lib/foundry-migration-inventory.ts
|
|
25
|
+
- scripts/lib/foundry-runtime-paths.ts
|
|
26
|
+
- scripts/lib/foundry-package-contract.ts
|
|
27
|
+
- scripts/package-entry.ts
|
|
28
|
+
- scripts/public-api.ts
|
|
29
|
+
- tsconfig.package.json
|
|
30
|
+
- specs/schemas/foundry-package-descriptor.schema.json
|
|
31
|
+
- scripts/lib/tidas-adapter.ts
|
|
32
|
+
- scripts/lib/import-curation/internal/runtime-io.ts
|
|
33
|
+
- scripts/lib/import-curation/curation-cleanup.ts
|
|
34
|
+
- test/unit/runtime-layout.test.mts
|
|
35
|
+
- test/unit/foundry-package-contract.test.mts
|
|
36
|
+
- test/unit/foundry-runtime-context.test.mts
|
|
37
|
+
- test/unit/foundry-runtime-command-policy.test.mts
|
|
38
|
+
- test/unit/foundry-runtime-qualification.test.mts
|
|
39
|
+
- test/unit/foundry-runtime-authority-schemas.test.mts
|
|
40
|
+
- test/scenarios/runtime-workspace.test.mts
|
|
41
|
+
- test/scenarios/foundry-execution-admission.test.mts
|
|
42
|
+
- test/scenarios/foundry-package-consumer.test.mts
|
|
43
|
+
lastReviewedAt: 2026-09-09
|
|
44
|
+
lastReviewedCommit: 21f10ac1643798aade3bd930c99785a0e6eaf0d9
|
|
45
|
+
lastReviewedNote: "Reviewed for Foundry #128: exact version-only 0.1.2 follows qualified main21f10ac via a fresh release event after the prior GitHub run could not restart. Only package identity and review metadata change; CLI0.1.12, TIDAS0.3.0, full source/public qualification, signing, first-identity handoff and final F1 acceptance remain unchanged and required."
|
|
46
|
+
related:
|
|
47
|
+
- docs/architecture.md
|
|
48
|
+
- docs/task-authorization-contract.md
|
|
49
|
+
- docs/public-runtime-contract.md
|
|
50
|
+
- docs/package-distribution-contract.md
|
|
51
|
+
---
|
|
52
|
+
|
|
53
|
+
# Runtime context
|
|
54
|
+
|
|
55
|
+
Local preparation enters the registered v2 task store in `foundry-task-store.ts`; it binds source/profile/actor/runtime metadata and revalidates indexed producer lineage before using derived input. Fresh CLI identity, exact runtime qualification, registered authorization, derived-input succession and child execution admission are exposed through the runtime API. Account intent remains separate from authentication. The API returns a reviewed CommandSpec to the existing no-replay owner; it does not execute or retry a mutation itself.
|
|
56
|
+
|
|
57
|
+
The consumer runtime receives an explicit `FoundryRuntimeContext`. Construction reads package identity and an explicitly selected/discovered workspace marker, but never loads `.env`, creates state, changes CWD or performs authentication. A process-local brand prevents serialized context data from becoming an executable context. `accountIntent` is expected identity plus an optional `accountMode` verification policy (`ordinary` or `production-test`), not proof of login or permission; `actorId` is caller intent and must also be checked against durable task state before execution.
|
|
58
|
+
|
|
59
|
+
The runtime entry now exposes the six W05 hierarchical operations described in `public-runtime-contract.md`, while retaining the old source developer commands. The facade delegates cleanup and native import to their existing owners, and contract context to the exact published CLI. Their local outputs are registered through the same task transaction. All 63 internal commands keep their explicit disposition in `foundry-runtime-command-policy.ts`; the six public operations are a separate orchestration surface over those owners. Repository maintenance remains excluded, and task/native families remain internal with declared asset/input/output roots, child-process ownership, qualification and authorization requirements.
|
|
60
|
+
|
|
61
|
+
The public task facade delegates sealed owner execution to `foundry-workflow-execution.ts`, request/attempt state to `foundry-owner-execution-store.ts`, and independent owner verification to `foundry-owner-readback.ts`. The existing closeout factory lives under `lib/finalize-owners` with its developer-command re-export preserved. Local operation receipts capture evidence only; the CLI batch boundary owns one-shot mutation and readback recovery. `foundry-workflow-reference-verify.ts` separately binds current semantic canonical targets to qualified CLI reference checks, using an explicit authentication environment and fresh output generation. See [public execution and recovery](public-runtime-contract.md#owner-execution-and-recovery).
|
|
62
|
+
|
|
63
|
+
## Runtime qualification and child admission
|
|
64
|
+
|
|
65
|
+
The public workflow selects derived row/context facts from the current verified task index before assessment. `runFoundryTaskOperation` rechecks their producer ancestry and original sources. Native validation and the exact CLI's local QA/queue commands use the qualified runtime and isolated environment; curation and authoring write only to a fresh task-owned generation. Runtime assets and source-owner reference bases remain separate from user workspace paths.
|
|
66
|
+
|
|
67
|
+
`qualifyFoundryRuntime` compares an independently selected CLI expectation with the exact installed `@tiangong-lca/cli@0.1.12` runtime descriptor. It also compares a strict TIDAS expectation with the selected platform, executable bytes, compatible 0.2.x or 0.3.x version, validation protocols, event schemas and asset fingerprint. The selected TIDAS executable is copied into a private temporary directory, rehashed there and invoked with the credential-free child environment; both handshake calls must be silent. Qualification uses a process-local brand. The portable identity described by `runtime-qualification.schema.json` is diagnostic evidence and cannot be deserialized into authority.
|
|
68
|
+
|
|
69
|
+
The TIDAS expectation admits only `linux-x64`, `linux-arm64`, `darwin-arm64` and `win32-x64`; `darwin-x64` cannot enter the schema or runtime context. `tidas-runtime-expectation.schema.json` is the reviewed machine shape. Qualification creation performs the isolated version/protocol/assets handshake once. Every later assertion reopens and hashes the selected executable and rejects any byte drift before child admission; identical immutable bytes do not replay the handshake. This keeps the original observed behavior bound to exact content while avoiding repeated child-process creation inside one admission call.
|
|
70
|
+
|
|
71
|
+
`execution-context.schema.json` describes the content-addressed child handoff stored under `evidence/executions/`. It is distinct from the older offline `foundry-execution-capsule-stage.v1` admission ledger: the older contract proves immutable staged evidence and attempt state, while `tiangong-foundry.execution-context.v1` binds a current task invocation. Rehydration requires a fresh process-local context, qualification and identity; exact workspace/task/actor, approved source ancestry, current final-row bytes, active authorization and QA waivers, installed owner CLI, owner-draft argv semantics, task-contained output root and CommandSpec digest are rechecked. The action list must match the CLI operation. Serialized admissions, unrelated CLI commands and changed capsule/spec/input bytes fail closed.
|
|
72
|
+
|
|
73
|
+
## Root ownership
|
|
74
|
+
|
|
75
|
+
Public semantic input remains separate from frozen task source selection and runtime trust. The invocation checks task/actor/current-assessment/work-item bindings, captures explicit non-credential input files, and registers immutable snapshots. Existing indexed work provides the collector context; submitted files provide candidate data only. Repaired rows retain source ancestry, and the next assessment must match the newest row manifest. No semantic data or local apply result is authorization for a remote action.
|
|
76
|
+
|
|
77
|
+
| Root | Meaning and authority |
|
|
78
|
+
| --- | --- |
|
|
79
|
+
| `runtimeRoot` | Immutable executing package. No user outputs or state may be written here. |
|
|
80
|
+
| `assetRoot` | Reviewed runtime schemas, profiles and semantic documents within the package. |
|
|
81
|
+
| `workspaceRoot` | User-selected project, independent of the package and current CWD. |
|
|
82
|
+
| `controlRoot` | `<workspace>/.foundry`; versioned workspace coordination. |
|
|
83
|
+
| `stateRoot` | Workspace coordination records; not arbitrary task outputs. |
|
|
84
|
+
| `taskRoot` | `<workspace>/.foundry/workspaces/<task-id>` for one explicit task. |
|
|
85
|
+
| `tempRoot` | Recomputable scratch space within the selected task/control root. |
|
|
86
|
+
| `cacheRoot` | Recomputable Foundry content under the OS user cache, isolated by runtime identity, platform, workspace and account intent. Managed executable components remain CLI-owned. |
|
|
87
|
+
|
|
88
|
+
`--workspace` selects a project explicitly. Otherwise only an existing `.foundry/workspace.json` marker discovered upward from the caller's CWD establishes a workspace. Filesystem roots, the package directory, installed `.agents/skills` / `.codex/skills` paths and `_npx` directories are rejected as workspaces. No failed lookup falls back to the package root.
|
|
89
|
+
|
|
90
|
+
Node must be at least 24.19 and below 25. The admitted platform matrix is macOS arm64, Linux x64/arm64 and Windows x64. Admission runs before workspace mutations or input capture. macOS Intel is unsupported.
|
|
91
|
+
|
|
92
|
+
## Package layout
|
|
93
|
+
|
|
94
|
+
`package.json.foundryRuntime` accepts the retained `tiangong-foundry.runtime-layout.v1` source/emitted shape and makes v2 authoritative for new builds. V2 adds `package_entry` and `package_descriptor` while preserving the developer `source_entry` and full-repository `emitted_entry`. All paths are relative, contained and regular where a file is required. The resolver chooses the declared tree that contains the active module; unknown schemas, ambiguous roots and path traversal are rejected. An installed package needs neither source `.ts`, full `dist`, Git nor a workspace, and a copied name-only manifest cannot hijack a nested build's root.
|
|
95
|
+
|
|
96
|
+
The layout resolver proves local layout and reports package-manifest/entry digests. When only the package entry is present, it also verifies the strict package descriptor, exact payload set and sanitized public manifest before creating a context. This does not replace W08 release provenance or the CLI runtime manager's component verification. Source maps, maintenance tools and live-case drivers are absent from the W06 closure.
|
|
97
|
+
|
|
98
|
+
## Workspace marker and initialization
|
|
99
|
+
|
|
100
|
+
The default initialization marker is `tiangong-foundry.workspace.v1`, with `layout_version: 1`, a UUID `workspace_id` and a UTC creation time. Initialization installs a complete marker through an exclusive atomic hardlink from an owned temporary file. A concurrent winner is re-read and validated. Repetition preserves existing bytes and workspace identity, then verifies required control directories. An interrupted recognized v1 initialization may complete its directories; unknown marker versions are never overwritten.
|
|
101
|
+
|
|
102
|
+
An unversioned nonempty `.foundry` requires explicit inventory/migration. Initialization does not label old state as new, clear old attempts or replay work. In particular, no real #95 workspace is migrated by this implementation.
|
|
103
|
+
|
|
104
|
+
## Inputs and outputs
|
|
105
|
+
|
|
106
|
+
User-selected external inputs are regular files captured as canonical path, byte size and SHA-256. Capture streams hashes and detects changes while reading. Data reads require a selected fact and matching current bytes; file descriptors are checked against the selected file before reading. Credential `.env*` files and an account's session reference cannot become dataset inputs. This selection boundary does not make a data file's instructions authoritative.
|
|
107
|
+
|
|
108
|
+
Task artifacts are written only under the selected `taskRoot`; state and cache have distinct resolver areas. Existing path components and physical containment are checked, including after directories are created. Symlink/junction escapes and a changed workspace marker are rejected. A complete new artifact is installed exclusively from an owned temporary file. Existing identical bytes may be reused; different existing bytes require a new output revision. A failed operation never deletes a prior artifact.
|
|
109
|
+
|
|
110
|
+
The default in-memory data-read bound is 64 MiB; native/streaming stages must declare and enforce their own larger-input protocol instead of silently loading unbounded payloads. Cache contents and layout records are not write or replay authority.
|
|
111
|
+
|
|
112
|
+
## Facade state and downstream integration
|
|
113
|
+
|
|
114
|
+
W05 stores request indexes and task pointers under workspace state. Their deterministic revision identity binds normalized task spec plus ordered canonical input facts; task payloads and outputs remain in the W04 task store. Status and resume reconstruct the context from those records and recheck original bytes. The facade does not treat request state as permission or attempt authority.
|
|
115
|
+
|
|
116
|
+
W06 builds only the required facade/runtime modules, schemas and assets and proves the same behavior from a source-free read-only installed candidate; `package-distribution-contract.md` owns that exact closure. W08 publishes F1 and binds the process-local runtime-selection interface to an immutable CLI-manager product manifest. Local preparation does not grant restricted writes; W03 task permissions and existing attempt/readback no-replay controls remain mandatory. Developer maintenance entrypoints, tests and private case drivers remain excluded from the consumer artifact.
|
|
117
|
+
|
|
118
|
+
The shared `assertFoundryRuntimeHost` gate also protects inventory-only migration, which cannot construct a context from an unknown legacy marker. Transfer planning constructs the destination context before reading the source and requires disjoint canonical roots with no existing destination `.foundry`. It does not initialize either workspace. See [workspace migration](workspace-migration-contract.md) for transfer, explicit adoption/activation and rollback boundaries.
|
|
119
|
+
|
|
120
|
+
A strict `workspace-migration-pending.v1` marker returns no active workspace id. `initializeFoundryWorkspace` and consumer doctor explicitly reject pending state. Migration staging/audit can inspect it to recover its exact claim and preserved archive; normal task creation remains unavailable until a separately audited activation.
|
|
121
|
+
|
|
122
|
+
Facade revision lookup validates retained predecessor jobs/publications without requiring their original input bytes to match a new revision. It checks every earlier revision for attempt evidence and refuses descendant continuation when any is present. Missing/changed predecessor storage is preserved as a recovery condition. This read-only request-chain check does not change runtime qualification or replace W10's complete migrated-task history and activation requirements.
|
|
123
|
+
|
|
124
|
+
Migrated `workspace.v2` state binds an activation receipt, required features and an extension object. Construction validates the anchored migration documents and requires an independently trusted host selection. Write access must qualify the executing Foundry version and every required feature; unknown write features fail closed. The internal pending-adoption scope supplies a future id only during the bounded local callback and cannot survive it or create authorization/execution admission. Read-only task inspection skips write locks and cannot repair missing records. Read-compatible inspection may verify retained older runtime/profile snapshots without treating them as current write rules.
|
|
125
|
+
|
|
126
|
+
`state/runtime-selection.json` records an explicit component selection and read/write mode. Ordinary writes must match it. The dedicated selector requires an independently qualified current writer, verifies/pins both component versions through the public CLI manager, and records selection history without rewriting the workspace marker or business state. An explicit CLI session reference cannot be read as marker or protected migration metadata.
|
|
127
|
+
|
|
128
|
+
An installed package may retain the component cache that contains it only when its current host manifest is still independently trusted, the public CLI inspection verifies the complete current component set, and the installed package verifier proves its identity inside one of those components. The context retains that host manifest privately; the persisted selection pointer and rollback target cannot substitute for it. Workspace and excluded migration roots remain disjoint from the cache in both directions, and the cache cannot sit inside the runtime root. Source and developer-emitted roots receive no package exception. Existing parent directories are canonicalized even for missing descendants, so filesystem aliases cannot bypass those boundaries.
|
|
129
|
+
|
|
130
|
+
Managed facade construction passes the independently selected component-cache root through the internal context options. The context rejects workspace overlap before reading its marker and privately retains that root for subsequent assertions. Overridden migration destinations inherit the same exclusion. `foundry-runtime-cache.ts` owns this shared canonical-path boundary; it does not create a cache or grant installed-package ownership.
|
|
131
|
+
|
|
132
|
+
The package-owned managed initializer receives the public CLI IPC context before public operations, verifies the installed entry and component metadata, and supplies the existing CLI/TIDAS qualification, workspace-access and runtime-target interfaces. It reads no `.env` or task-selected trust anchor. The metadata schema and exact admission sequence are defined by `package-distribution-contract.md`; native qualification and task/identity authorization retain their existing owners.
|
|
133
|
+
|
|
134
|
+
Prepared-support finalization explicitly selects the approved input file for its dataset type. Other completed scope artifacts are retained through the existing verified-progress map; the original row manifest and approval origin remain lineage anchors. `approval_authorization_sha256` distinguishes a new derived-input finalization from an unchanged blocked result.
|
|
135
|
+
|
|
136
|
+
Workflow generation and scratch directories use task-confined cryptographic names with exclusive `mkdir`, rather than `mkdtemp` under deep task paths. This preserves distinct immutable generations on Windows when a registered task plus operation digest exceeds the Windows `mkdtemp` path limit. Workspace write access and path confinement are checked before creation; existing directories are never adopted.
|
|
137
|
+
|
|
138
|
+
The native validation adapter also allocates a cryptographically named exclusive staging directory beside its selected output. This keeps atomic same-filesystem replacement and cancellation cleanup available at deep Windows task paths. Failed or cancelled validation preserves the previous output; successful validation publishes the complete new report set.
|
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Foundry Safety Policy
|
|
3
|
+
docType: policy
|
|
4
|
+
scope: remote-write-safety
|
|
5
|
+
status: active
|
|
6
|
+
authoritative: true
|
|
7
|
+
owner: tiangong-lca-data-foundry
|
|
8
|
+
language: en
|
|
9
|
+
whenToUse:
|
|
10
|
+
- when deciding whether a Foundry import scope may proceed from dry-run to remote commit
|
|
11
|
+
- when reviewing task write policy, mutation manifest, commit handoff, readback, or human approval requirements
|
|
12
|
+
whenToUpdate:
|
|
13
|
+
- when remote commit gates, human approval boundaries, write policy, or blocked-scope recovery rules change
|
|
14
|
+
checkPaths:
|
|
15
|
+
- docs/safety-policy.md
|
|
16
|
+
- WORKFLOW.md
|
|
17
|
+
- README.md
|
|
18
|
+
- AGENTS.md
|
|
19
|
+
- docs/foundry-task-contracts.md
|
|
20
|
+
- docs/package-distribution-contract.md
|
|
21
|
+
- docs/import-profiles/bafu/profile.md
|
|
22
|
+
- docs/import-profiles/bafu/constraints.md
|
|
23
|
+
- specs/automated-lca-capability-registry.json
|
|
24
|
+
- specs/workspace-capability-adapters.md
|
|
25
|
+
- scripts/foundry-golden-diff.ts
|
|
26
|
+
- scripts/check-tidas-cutover.ts
|
|
27
|
+
- scripts/lib/tidas-adapter.ts
|
|
28
|
+
- scripts/lib/foundry-package-contract.ts
|
|
29
|
+
- scripts/package-entry.ts
|
|
30
|
+
- test/scenarios/foundry-package-consumer.test.mts
|
|
31
|
+
- scripts/lib/post-authoring-finalize-utils.ts
|
|
32
|
+
- scripts/commands/tasks.ts
|
|
33
|
+
- scripts/commands/import-completion.ts
|
|
34
|
+
- scripts/commands/commit-handoff.ts
|
|
35
|
+
- scripts/commands/identity-decision-task.ts
|
|
36
|
+
- scripts/commands/support-cache.ts
|
|
37
|
+
- scripts/commands/cli-wrappers.ts
|
|
38
|
+
- scripts/commands/execution-capsule.ts
|
|
39
|
+
- scripts/commands/post-write-closeout.ts
|
|
40
|
+
- scripts/commands/library-scope-workflow.ts
|
|
41
|
+
- scripts/commands/bafu-leaf-classification-tasks.ts
|
|
42
|
+
- scripts/commands/bafu-auto-authoring.ts
|
|
43
|
+
- scripts/commands/bafu-process-scope-e2e.ts
|
|
44
|
+
- scripts/commands/bafu-batch-import-run.ts
|
|
45
|
+
- scripts/commands/core.ts
|
|
46
|
+
- scripts/commands/identity-preflight-run.ts
|
|
47
|
+
- scripts/commands/post-authoring-finalize.ts
|
|
48
|
+
- scripts/lib/import-curation/internal/prewrite-cleanup.ts
|
|
49
|
+
- scripts/lib/import-curation/internal/workflow-queue-context.ts
|
|
50
|
+
- scripts/lib/import-curation/internal/full-context-proof.ts
|
|
51
|
+
- scripts/lib/import-curation/internal/workflow-decision-apply-context.ts
|
|
52
|
+
- scripts/lib/import-curation/internal/profiles-config.ts
|
|
53
|
+
- scripts/lib/import-curation/internal/workflow-patch-collect.ts
|
|
54
|
+
- scripts/lib/import-curation/internal/workflow-identity-decision-context.ts
|
|
55
|
+
- scripts/lib/import-curation/internal/workflow-patch-evidence-context.ts
|
|
56
|
+
- scripts/lib/import-curation/internal/workflow-row-transform-context.ts
|
|
57
|
+
- scripts/lib/import-curation/internal/workflow-dry-run-context.ts
|
|
58
|
+
- scripts/lib/import-curation/internal/workflow-evidence-scope.ts
|
|
59
|
+
- scripts/lib/import-curation/internal/workflow-decision-full-context.ts
|
|
60
|
+
- scripts/lib/import-curation/internal/workflow-authoring-tasks.ts
|
|
61
|
+
- scripts/lib/import-curation/internal/workflow-semantic-actions.ts
|
|
62
|
+
- scripts/lib/import-curation/internal/workflow-patch-evidence.ts
|
|
63
|
+
- scripts/lib/import-curation/internal/workflow-identity-preflight.ts
|
|
64
|
+
- scripts/lib/import-curation/internal/authoring-task-workflow.ts
|
|
65
|
+
- scripts/lib/import-curation/internal/authoring-patch-workflow.ts
|
|
66
|
+
- scripts/lib/import-curation/internal/curation-gate-workflow.ts
|
|
67
|
+
- scripts/lib/import-curation/authoring-packages.ts
|
|
68
|
+
- scripts/lib/import-curation/patch-collect.ts
|
|
69
|
+
- scripts/lib/import-curation/curation-gate.ts
|
|
70
|
+
- scripts/lib/import-curation/curation-cleanup.ts
|
|
71
|
+
- scripts/lib/batch-orchestration/control-artifact-store.ts
|
|
72
|
+
- scripts/lib/batch-orchestration/scope-control-retention.ts
|
|
73
|
+
- scripts/lib/batch-orchestration/scope-safe-prune.ts
|
|
74
|
+
- scripts/lib/import-curation/internal/workflow-reference-closure.ts
|
|
75
|
+
- scripts/lib/import-curation/internal/workflow-source-reference-context.ts
|
|
76
|
+
- scripts/lib/import-curation/internal/mutation-manifest-workflow.ts
|
|
77
|
+
- scripts/lib/import-curation/mutation-manifest.ts
|
|
78
|
+
- scripts/lib/foundry-execution-admission.ts
|
|
79
|
+
- specs/schemas/execution-context.schema.json
|
|
80
|
+
- scripts/foundry-facade.ts
|
|
81
|
+
- scripts/lib/foundry-facade-store.ts
|
|
82
|
+
lastReviewedAt: 2026-09-05
|
|
83
|
+
lastReviewedCommit: 8cbbddb1a727ff2858918d0ff6d2efb1c8827390
|
|
84
|
+
lastReviewedNote: "Reviewed for #106 W06: installed package bytes/manifest are verified before facade context, and the public bin cannot enter mutation owners."
|
|
85
|
+
---
|
|
86
|
+
|
|
87
|
+
# Safety Policy
|
|
88
|
+
|
|
89
|
+
## Default Write Mode
|
|
90
|
+
|
|
91
|
+
`dry-run`.
|
|
92
|
+
|
|
93
|
+
## Remote Commit
|
|
94
|
+
|
|
95
|
+
An installed package is usable only after its sanitized manifest, descriptor and complete allowed payload match. A modified, extra, linked or private/source file fails before a package-backed context is created. This package check is code/asset integrity, not task permission: it does not make a profile, completion report or mutation executable. The public bin cannot route flat developer commands, and a W06 candidate is not a published F1 component.
|
|
96
|
+
|
|
97
|
+
Remote database writes are blocked unless:
|
|
98
|
+
|
|
99
|
+
- the task explicitly permits commit
|
|
100
|
+
- the workflow policy permits commit
|
|
101
|
+
- the exact write scope is included in the task write policy and, for batch runs, was claimed through queue locks within configured `max_parallelism`
|
|
102
|
+
- schema validation passes
|
|
103
|
+
- deterministic QA and Foundry curation pass
|
|
104
|
+
- source evidence is present for authored fields
|
|
105
|
+
- profiles that require full-context AI semantic completion have an AI authoring package containing SDK schema, methodology YAML, runtime ruleset, profile constraints, queue/dependency closure, source row, and current entity payload before any semantic field is accepted
|
|
106
|
+
- blocked Foundry authoring packages, when present, were converted into explicit `dataset-authoring-task-build` task artifacts before AI output was accepted
|
|
107
|
+
- AI-authored patch outputs, when produced as task files, were collected through `dataset-authoring-patch-collect` with a `ready_for_patch_apply` report and no incomplete template, unresolved placeholder, missing evidence, package mismatch, or unclosed action-item blocker
|
|
108
|
+
- AI-authored field changes, when present, were applied through `dataset-patch-apply` / `tiangong-lca dataset patch apply` with a completed apply report
|
|
109
|
+
- AI-authored patches, when produced from Foundry authoring packages, carry package lineage, close the package action items they resolve, and have an `authoring_package_sha256` that matches a readable full-context authoring package from the patch task manifest or curation gate
|
|
110
|
+
- full-context authoring packages must contain non-empty SDK schema, methodology YAML, and runtime ruleset text; path references alone are invalid
|
|
111
|
+
- full-context AI patch operations must carry both a basis and structured evidence with source plus quote/trace/path/citation pointer; generic basis-only patches are invalid for remote write planning
|
|
112
|
+
- AI-authored patch evidence includes `resolution.mode` and `resolution.used_context_kinds`, so final manifests can distinguish evidence-backed completion, source-language normalization, source-trace verification, and `common:other` deferral; classification and location queue fixes are proven by their dedicated decision-apply reports instead of patch operations
|
|
113
|
+
- TIDAS location-like machine fields must contain valid `tidas_locations_category.json` codes, not natural-language place descriptions. Location code repairs for profiles with full-context AI completion must be proven by completed `location-decisions-apply` evidence, while descriptive geography context remains in TIDAS description/name/source-trace fields; rows whose location cannot be confidently coded remain blocked before remote write.
|
|
114
|
+
- Full-context profiles must pass content saturation before remote write planning. If source trace, schema, methodology YAML, or profile context contains a provable formal-field value, the row remains blocked until AI patch evidence fills the field or records an allowed structured deferral for action items that explicitly permit deferral. Underfilled synonyms, supply/location descriptors, quantitative flow properties, bibliographic source details, or official contact details are content-saturation blockers.
|
|
115
|
+
- `common:other` deferral is allowed only for action items whose allowed resolution modes include `deferred_to_common_other`; it must be produced by AI patch evidence for the same row, write structured `tiangongfoundry:unresolvedTrace` with status, action item code, blocked path, reason, structured evidence, and next action, and close the matching action item; evidence must include source plus quote/trace/path/citation pointer
|
|
116
|
+
- mandatory schema fields cannot be marked resolved by moving the missing value to `common:other`; they need evidence-backed values or remain blocked before remote write
|
|
117
|
+
- source-only-output exchange acceptance must be produced by same-row AI patch evidence with `resolution.mode=source_trace_verified`, or by deterministic cleanup proof generated from an explicit `source_rows_file` for the same row; both paths must write structured `tiangongfoundry:sourceExchangeCompleteness` with accepted status and structured source trace evidence, and deterministic proof must show the source row is Output-only and that the final row preserves the non-flow-reference exchange signature
|
|
118
|
+
- for profiles that require full-context AI semantic completion, deterministic AI evidence is mandatory, not optional: classification queue fixes must carry completed `classification-decisions-apply` evidence, location queue fixes must carry completed `location-decisions-apply` evidence, and other patches must carry patch collect/apply evidence with `authoring_package_sha256` and `closes_action_items`
|
|
119
|
+
- reference closure passes in the post-authoring mutation manifest; mutually-referencing writable support rows must be grouped into one mixed `support` write scope when needed. Flow Properties and Unit Groups resolve through the canonical support cache by default; only a frozen profile may explicitly authorize canonical-cache-miss FP/UG as same-owner `state_code=0` candidates, ordered Unit Group before Flow Property and excluded from the public cache. Any referenced dataset outside the exact write scope must be proven by `dataset verify-remote` after its row exists remotely, or the dependent write scope remains blocked before commit handoff
|
|
120
|
+
- support/source write scopes contain only true source identities for source rows; data-format, compliance-system, and placeholder identities such as `ILCD format` or `Not specified` must remain canonical reference rewrites/provenance and are blocked by the mutation manifest before commit handoff; true source rows with empty or type-only descriptions such as `Report` must be repaired from citation/name evidence before write planning
|
|
121
|
+
- missing canonical unitgroups, flowproperties, elementary flows, compliance sources, data-format sources, contacts, or true sources block only the dependent write scope unless its frozen profile has a reviewed account-local candidate path. Every candidate still requires owner, unit-scale, schema, QA, curation, closure, audit, handoff, and readback proof; a failed support scope is deferred and independent scopes with proven closure may continue
|
|
122
|
+
- blocked write scopes must append machine-readable import-ledger rows under `blocked.scopes.human-review.jsonl` and categorized `blocked.dependencies.*.jsonl` files with concrete blocker reasons, required human action, and the rerun path; successful readback-verified scopes must append `ok.*.verified.jsonl` rows so later batch reruns can skip already imported rows
|
|
123
|
+
- curation cleanup has run and cleaned rows were revalidated
|
|
124
|
+
- deterministic cleanup may externalize import-only source trace only after hashing it into a safe summary; circular/unserializable trace evidence fails before deletion. Retained Foundry trace evidence must carry its namespace, local machine locators must be deleted or SHA-redacted, and source-only-output proof remains bound to exact ordered non-flow-reference exchange signatures.
|
|
125
|
+
- verified-scope scratch may be deleted only after every required report/plan/log/ledger reference is stored and reverified by SHA-256 in the run-level control store. The scope report must separate immutable artifact identity, original locator, store locator, and payload-pruned disposition. Missing evidence, invalid receipts, blob drift, repository/store path escape, or any scope/store/cache symlink blocks deletion. Failed or ambiguous scopes retain scratch; shared-context cache is recomputable-only and emits an explicit prune report.
|
|
126
|
+
- post-authoring Foundry curation gate passes on the exact final rows and references a deterministic QA report for those rows
|
|
127
|
+
- state-code-aware mutation plan exists
|
|
128
|
+
- Foundry `dataset-mutation-manifest` is `ready_for_remote_write` for the exact write scope
|
|
129
|
+
- blocked mutation manifests must not export executable rows in `*.write-candidates.jsonl`; planned-but-blocked rows belong only in `*.blocked-write-candidates.jsonl`
|
|
130
|
+
- when `common:other.tiangongfoundry:unresolvedTrace` or `sourceExchangeCompleteness` entries exist, the mutation manifest exports them as JSONL follow-up queues for later database-side curation
|
|
131
|
+
- mutation-manifest evidence reports point to the exact write rows: schema and remote verification `input_path` match the rows file, cleanup `cleaned_rows_file` matches the rows file, and AI patch apply output chains into cleanup input when AI patching was used
|
|
132
|
+
- `dataset-commit-handoff-plan` reports `ready_for_explicit_commit` for the exact finalize report, mutation manifest, final rows file, target user id, and expected state_code
|
|
133
|
+
- commit and post-write verify are authoritative `tiangong-foundry.command-spec.v1` objects; their SHA-256 binds executable, argv, and the same final-row path/bytes/SHA-256, while display is never executed and every runner rechecks artifact bytes before `shell=false` spawn
|
|
134
|
+
- a new process may receive a restricted commit CommandSpec only after `tiangong-foundry.execution-context.v1` is rehydrated from task evidence with current process-local runtime qualification and identity, approved-input ancestry, active exact actions/QA waivers, unchanged final rows, task-contained output path and reviewed owner CLI argv semantics; this admission returns the spec but never dispatches or retries it
|
|
135
|
+
- facade task start performs no authentication and creates a new predecessor-bound task revision whenever selected path/content or task intent changes; it never resets or reuses an earlier task's attempt authority
|
|
136
|
+
- facade task resume may automatically run only its registered deterministic local preparation; a nonempty, malformed or ambiguous attempt area blocks with readback-only recovery, and copied/unindexed completion files never yield `completed`
|
|
137
|
+
- insert/versioned writes have explicit reasons
|
|
138
|
+
- state_code=100 rows have source-review records instead of direct overwrite
|
|
139
|
+
- a dry-run artifact exists
|
|
140
|
+
- the configured remote/readback verification gate passes
|
|
141
|
+
- after commit, `tiangong-lca dataset verify-remote --compare-root-payload --target-user-id <id> --state-code <code>` passes for the exact committed rows
|
|
142
|
+
- explicit production case TDD runs only through a named `case:production:*` script outside ordinary CI. The designated test account may exercise every capability that account is authorized to use only on its isolated, unreviewed, unpublished rows; public production reads are allowed, while foreign/public/shared mutation and review/publish transitions are forbidden. Each write case requires a fresh intent-bound identity receipt, an exact argv/artifact binding, at most one mutation dispatch, and a unique owner/state/payload readback; transport ambiguity stops at read-only investigation without an automatic retry.
|
|
143
|
+
- `missing_dataset` for a foreign or RLS-hidden `state_code=0` reference is always a hard blocker; another account's observation, a static trusted key, or a profile exception cannot rewrite the check/report to passed. Production-test accounts accept no post-write difference. Ordinary runs may normalize only an exact root payload mismatch proven to differ solely at `tiangongfoundry:importTraceSummary.traceHash` after a fresh CLI readback.
|
|
144
|
+
- after commit and readback, Foundry `dataset-post-write-closeout` reports `completed`; it must prove the handoff was ready, the CLI commit report was a real commit with no row failures, post-write verification used the same final rows, root readback checks have equal local/remote payload hashes, owner/state_code match the handoff, profile-required full schema/YAML/context AI proof and evidence counts remain attached, and any `common:other` trace queues remain attached
|
|
145
|
+
- for a task with one or more committed scopes, Foundry `dataset-import-completion-report` reports `completed` after aggregating every closeout report required by the task; missing closeouts, duplicate closeouts for the same dataset type/final rows, non-completed closeouts, mismatched finalize/mutation scopes, missing profile-required full-context proof or evidence counts, unreadable trace queues, or missing required dataset types keep the task blocked
|
|
146
|
+
- for resumable batch imports, Foundry `dataset-import-ledger-report` must be able to summarize the append-only import ledger into `resume.skipped-verified.jsonl` and `resume.plan.jsonl`, preserving ready-only execution across reruns
|
|
147
|
+
- high-level library/BAFU orchestration may resume, pause, stop claiming scopes, run bounded workers, or emit read-only preflight plans, but none of those states grants write authority; only an explicit commit request may delegate an artifact-bound, receipt-checked executable-plus-argv handoff after every scope gate passes
|
|
148
|
+
- Foundry task state moves from `tasks/active` to `tasks/done` only through `task-complete`, which requires a matching `dataset-import-completion-report.completed` for the same task id, at least one post-write closeout scope, and profile-required full schema/YAML/context AI completion proof before entry
|
|
149
|
+
|
|
150
|
+
For `state_code=0`, ordinary account-owned working-data repair should use update-first semantics. For missing or ambiguous `state_code`, stop at dry-run and create a follow-up task.
|
|
151
|
+
|
|
152
|
+
## Secrets
|
|
153
|
+
|
|
154
|
+
Never commit:
|
|
155
|
+
|
|
156
|
+
- `.env`
|
|
157
|
+
- API keys
|
|
158
|
+
- access tokens
|
|
159
|
+
- full database payload dumps
|
|
160
|
+
- runtime logs with credentials
|
|
161
|
+
|
|
162
|
+
## Human Involvement
|
|
163
|
+
|
|
164
|
+
The goal is batch automation with hard gates and recovery. Humans approve policy changes, exceptional waivers, delete actions, and missing canonical database support decisions. They do not supervise every scan, repair candidate, or gate-passing commit scope when the task write policy permits profile-gated automated batch commit.
|