@tiangong-lca/foundry 0.1.9 → 0.1.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (83) hide show
  1. package/README.md +10 -8
  2. package/docs/architecture.md +9 -7
  3. package/docs/foundry-task-contracts.md +10 -4
  4. package/docs/import-profiles/bafu/constraints.md +1 -1
  5. package/docs/import-profiles/bafu/profile.md +1 -1
  6. package/docs/import-profiles/worldsteel/constraints.md +3 -3
  7. package/docs/import-profiles/worldsteel/import-coverage.md +3 -3
  8. package/docs/import-profiles/worldsteel/import-plan.md +4 -4
  9. package/docs/import-profiles/worldsteel/profile.md +3 -3
  10. package/docs/package-distribution-contract.md +9 -9
  11. package/docs/public-runtime-contract.md +17 -7
  12. package/docs/runtime-context-contract.md +5 -5
  13. package/docs/task-authorization-contract.md +3 -3
  14. package/package-dist/assets/foundry-package-descriptor.json +218 -128
  15. package/package-dist/scripts/foundry-facade.js +71 -0
  16. package/package-dist/scripts/foundry-runtime.d.ts +12 -2
  17. package/package-dist/scripts/lib/finalize-owners/commit-handoff.js +3 -3
  18. package/package-dist/scripts/lib/finalize-owners/{native-insert-closeout.d.ts → native-draft-closeout.d.ts} +1 -1
  19. package/package-dist/scripts/lib/finalize-owners/{native-insert-closeout.js → native-draft-closeout.js} +10 -6
  20. package/package-dist/scripts/lib/finalize-owners/{native-insert-handoff.d.ts → native-draft-handoff.d.ts} +7 -5
  21. package/package-dist/scripts/lib/finalize-owners/{native-insert-handoff.js → native-draft-handoff.js} +30 -11
  22. package/package-dist/scripts/lib/finalize-owners/post-write-closeout.js +2 -2
  23. package/package-dist/scripts/lib/foundry-authorization-input.d.ts +10 -1
  24. package/package-dist/scripts/lib/foundry-authorization-input.js +27 -3
  25. package/package-dist/scripts/lib/foundry-command-metadata.js +25 -2
  26. package/package-dist/scripts/lib/foundry-command-registry.d.ts +4 -4
  27. package/package-dist/scripts/lib/foundry-command-registry.js +3 -0
  28. package/package-dist/scripts/lib/foundry-execution-admission.js +3 -3
  29. package/package-dist/scripts/lib/foundry-facade-store.js +56 -6
  30. package/package-dist/scripts/lib/foundry-owner-execution-store.d.ts +33 -16
  31. package/package-dist/scripts/lib/foundry-owner-execution-store.js +32 -3
  32. package/package-dist/scripts/lib/foundry-owner-readback.d.ts +3 -0
  33. package/package-dist/scripts/lib/foundry-owner-readback.js +101 -27
  34. package/package-dist/scripts/lib/foundry-package-contract.d.ts +2 -2
  35. package/package-dist/scripts/lib/foundry-package-contract.js +2 -2
  36. package/package-dist/scripts/lib/foundry-repair-execution.d.ts +11 -0
  37. package/package-dist/scripts/lib/foundry-repair-execution.js +70 -0
  38. package/package-dist/scripts/lib/foundry-repair-handoff.d.ts +16 -0
  39. package/package-dist/scripts/lib/foundry-repair-handoff.js +108 -0
  40. package/package-dist/scripts/lib/foundry-repair-preflight.d.ts +96 -0
  41. package/package-dist/scripts/lib/foundry-repair-preflight.js +313 -0
  42. package/package-dist/scripts/lib/foundry-repair-reference-binding.d.ts +26 -0
  43. package/package-dist/scripts/lib/foundry-repair-reference-binding.js +120 -0
  44. package/package-dist/scripts/lib/foundry-repair-reference-proof.d.ts +63 -0
  45. package/package-dist/scripts/lib/foundry-repair-reference-proof.js +329 -0
  46. package/package-dist/scripts/lib/foundry-repair-scope.d.ts +76 -0
  47. package/package-dist/scripts/lib/foundry-repair-scope.js +304 -0
  48. package/package-dist/scripts/lib/foundry-runtime-command-policy.js +1 -0
  49. package/package-dist/scripts/lib/foundry-runtime-qualification.js +2 -2
  50. package/package-dist/scripts/lib/foundry-runtime-utils.d.ts +3 -0
  51. package/package-dist/scripts/lib/foundry-runtime-utils.js +6 -1
  52. package/package-dist/scripts/lib/foundry-successor-predecessor.d.ts +36 -0
  53. package/package-dist/scripts/lib/foundry-successor-predecessor.js +399 -0
  54. package/package-dist/scripts/lib/foundry-task-registration.js +64 -3
  55. package/package-dist/scripts/lib/foundry-task-start-spec.d.ts +3 -0
  56. package/package-dist/scripts/lib/foundry-task-start-spec.js +24 -1
  57. package/package-dist/scripts/lib/foundry-task-store.d.ts +13 -1
  58. package/package-dist/scripts/lib/foundry-task-store.js +23 -12
  59. package/package-dist/scripts/lib/foundry-task-types.d.ts +22 -1
  60. package/package-dist/scripts/lib/foundry-tidas-source.d.ts +15 -0
  61. package/package-dist/scripts/lib/foundry-tidas-source.js +90 -0
  62. package/package-dist/scripts/lib/foundry-workflow-authorization.d.ts +2 -1
  63. package/package-dist/scripts/lib/foundry-workflow-authorization.js +194 -26
  64. package/package-dist/scripts/lib/foundry-workflow-context.js +4 -0
  65. package/package-dist/scripts/lib/foundry-workflow-execution.js +6 -1
  66. package/package-dist/scripts/lib/foundry-workflow-repair.d.ts +36 -0
  67. package/package-dist/scripts/lib/foundry-workflow-repair.js +580 -0
  68. package/package-dist/scripts/lib/foundry-workflow-state.js +66 -18
  69. package/package-dist/scripts/lib/import-curation/curation-cleanup.js +39 -8
  70. package/package-dist/scripts/lib/import-curation/internal/context-inputs.js +1 -1
  71. package/package-dist/scripts/lib/import-curation/internal/prewrite-cleanup.d.ts +13 -2
  72. package/package-dist/scripts/lib/import-curation/internal/prewrite-cleanup.js +100 -29
  73. package/package-dist/scripts/lib/import-curation/internal/workflow-authoring-tasks.js +1 -2
  74. package/package-dist/scripts/lib/import-curation/internal/workflow-patch-collect.js +2 -3
  75. package/package-dist/scripts/lib/import-curation/internal/workflow-queue-context.js +8 -8
  76. package/package-dist/scripts/lib/import-curation/internal/workflow-semantic-actions.js +12 -2
  77. package/package.json +2 -2
  78. package/specs/import-profiles.json +1 -1
  79. package/specs/schemas/foundry-authorization-input.schema.json +45 -2
  80. package/specs/schemas/foundry-managed-runtime.schema.json +1 -1
  81. package/specs/schemas/foundry-package-descriptor.schema.json +2 -2
  82. package/specs/schemas/foundry-task-start.schema.json +200 -19
  83. package/specs/schemas/runtime-qualification.schema.json +1 -1
@@ -3,6 +3,14 @@ import path from "node:path";
3
3
  import { createHash } from "node:crypto";
4
4
  import { FoundryContextError, resolveFoundryOutput, } from "./foundry-runtime-context.js";
5
5
  import { readTaskBytes } from "./foundry-task-io.js";
6
+ /**
7
+ * The repair producer's registration of the preparation report. These two values are repeated here
8
+ * rather than imported so this projection module stays a graph leaf; the public repair suite fails
9
+ * if the producer ever stops registering under them.
10
+ */
11
+ const FOUNDRY_REPAIR_PREFLIGHT_COMMAND = "dataset-workflow-repair-preflight";
12
+ const FOUNDRY_REPAIR_REPORT_NAME = "foundry-repair-preflight.json";
13
+ const FOUNDRY_REPAIR_PREPARATION_SCHEMA = "tiangong-foundry.repair-preparation.v1";
6
14
  export function workflowObject(value) {
7
15
  if (!value || typeof value !== "object" || Array.isArray(value))
8
16
  throw new FoundryContextError("workflow_report_invalid", "Workflow metadata must be an object.");
@@ -150,27 +158,67 @@ export function currentWorkflowState(context, entries) {
150
158
  }
151
159
  let authorization = null;
152
160
  let preparedApproval = null;
153
- if (finalization && fs.existsSync(path.join(context.taskRoot, "authorization.json"))) {
161
+ if (context.taskRoot && fs.existsSync(path.join(context.taskRoot, "authorization.json"))) {
154
162
  const pointer = createHash("sha256")
155
163
  .update(readTaskBytes(context, "authorization.json"))
156
164
  .digest("hex");
157
- for (const entry of [...entries].reverse()) {
158
- if (entry.command !== "dataset-workflow-authorization" ||
159
- path.basename(entry.path) !== "foundry-authorization.json")
160
- continue;
161
- const found = readWorkflowArtifact(context, entry);
162
- if (found.value.schema !== "tiangong-foundry.authorization-stage.v1")
163
- throw new FoundryContextError("workflow_authorization_invalid", "Registered approval metadata is invalid.");
164
- const prepared = finalization.value.approval_source_sha256 === entry.sha256 &&
165
- found.value.input_kind === "current_rows";
166
- if (prepared)
167
- preparedApproval = found;
168
- if ((found.value.finalization_sha256 === finalization.entry.sha256 || prepared) &&
169
- found.value.pointer_sha256 === pointer &&
170
- typeof found.value.expires_at_utc === "string" &&
171
- Date.parse(found.value.expires_at_utc) > Date.now()) {
172
- authorization = found;
173
- break;
165
+ if (finalization) {
166
+ for (const entry of [...entries].reverse()) {
167
+ if (entry.command !== "dataset-workflow-authorization" ||
168
+ path.basename(entry.path) !== "foundry-authorization.json")
169
+ continue;
170
+ const found = readWorkflowArtifact(context, entry);
171
+ if (found.value.schema !== "tiangong-foundry.authorization-stage.v1")
172
+ throw new FoundryContextError("workflow_authorization_invalid", "Registered approval metadata is invalid.");
173
+ const prepared = finalization.value.approval_source_sha256 === entry.sha256 &&
174
+ found.value.input_kind === "current_rows";
175
+ if (prepared)
176
+ preparedApproval = found;
177
+ if ((found.value.finalization_sha256 === finalization.entry.sha256 || prepared) &&
178
+ found.value.pointer_sha256 === pointer &&
179
+ typeof found.value.expires_at_utc === "string" &&
180
+ Date.parse(found.value.expires_at_utc) > Date.now()) {
181
+ authorization = found;
182
+ break;
183
+ }
184
+ }
185
+ }
186
+ if (!authorization) {
187
+ // A repair scope has no finalization: its registered authority is the latest preparation report
188
+ // of this task, and only while that report is a prepared dispatchable write scope. An approval
189
+ // bound to a superseded report, or to evidence that has since become no-change or blocked,
190
+ // carries no current authority.
191
+ const latest = entries
192
+ .filter((entry) => entry.command === FOUNDRY_REPAIR_PREFLIGHT_COMMAND &&
193
+ path.basename(entry.path) === FOUNDRY_REPAIR_REPORT_NAME)
194
+ .sort((left, right) => left.sequence - right.sequence)
195
+ .at(-1);
196
+ if (latest) {
197
+ const report = readWorkflowArtifact(context, latest).value;
198
+ const reportScope = report.scope;
199
+ const dispatchable = report.schema === FOUNDRY_REPAIR_PREPARATION_SCHEMA &&
200
+ report.status === "prepared" &&
201
+ Boolean(reportScope) &&
202
+ typeof reportScope === "object" &&
203
+ !Array.isArray(reportScope) &&
204
+ reportScope.status === "dispatchable";
205
+ if (dispatchable)
206
+ for (const entry of [...entries].reverse()) {
207
+ if (entry.command !== "dataset-workflow-authorization" ||
208
+ path.basename(entry.path) !== "foundry-authorization.json")
209
+ continue;
210
+ const found = readWorkflowArtifact(context, entry);
211
+ if (found.value.schema !== "tiangong-foundry.authorization-stage.v1")
212
+ throw new FoundryContextError("workflow_authorization_invalid", "Registered approval metadata is invalid.");
213
+ if (found.value.input_kind === "repair_rows" &&
214
+ found.value.finalization_sha256 === latest.sha256 &&
215
+ found.value.pointer_sha256 === pointer &&
216
+ typeof found.value.expires_at_utc === "string" &&
217
+ Date.parse(found.value.expires_at_utc) > Date.now()) {
218
+ authorization = found;
219
+ break;
220
+ }
221
+ }
174
222
  }
175
223
  }
176
224
  }
@@ -1,7 +1,8 @@
1
1
  import path from "node:path";
2
2
  import { datasetTypeFromOptions, datasetTypePlural } from "./internal/dataset-types.js";
3
3
  import { datasetIdentity } from "./internal/dataset-payload.js";
4
- import { annualSupplyMissingDataSentinelText, applyAnnualSupplyMissingDataSentinel, applyDeterministicSourceExchangeCompletenessProofs, buildSourceRowsByIdentity, ensureFoundryTraceNamespaces, externalizeImportTraceMetadata, normalizeDateTimeMetadata, sanitizeFoundryTraceEvidenceLocators, } from "./internal/prewrite-cleanup.js";
4
+ import { sha256Json } from "./internal/hash-utils.js";
5
+ import { annualSupplyFieldPath, applyDeterministicSourceExchangeCompletenessProofs, buildSourceRowsByIdentity, ensureFoundryTraceNamespaces, externalizeImportTraceMetadata, normalizeAnnualSupplyEvidence, normalizeDateTimeMetadata, sanitizeFoundryTraceEvidenceLocators, } from "./internal/prewrite-cleanup.js";
5
6
  import { fileExists, jsonLines, nowIso, readRows, repoRelativePath, resolveRepoPath, writeJson, writeText, } from "./internal/runtime-io.js";
6
7
  function dateTimeBlockersFromError(error) {
7
8
  if (!error || typeof error !== "object" || Array.isArray(error))
@@ -27,7 +28,7 @@ export function runDatasetCurationCleanup({ repoRoot, options = {}, io, } = {})
27
28
  usage: [
28
29
  "node scripts/foundry.ts dataset-curation-cleanup --type <process|flow|lifecyclemodel|support|contact|source> --rows-file <rows.jsonl> [--source-rows-file <source-rows.jsonl>] --out-dir <cleanup-dir>",
29
30
  ],
30
- purpose: "Run deterministic prewrite cleanup transforms: annual-supply sentinel completion, import trace externalization, Foundry trace namespace repair, local locator redaction, and timestamp normalization.",
31
+ purpose: "Run deterministic prewrite cleanup transforms: annual-supply evidence preservation, import trace externalization, Foundry trace namespace repair, local locator redaction, and timestamp normalization.",
31
32
  remote_write_mode: "read-only",
32
33
  blockers: [],
33
34
  };
@@ -110,11 +111,13 @@ export function runDatasetCurationCleanup({ repoRoot, options = {}, io, } = {})
110
111
  redacted_foundry_trace_evidence_locators: 0,
111
112
  added_foundry_trace_namespaces: 0,
112
113
  normalized_datetime_values: 0,
113
- annual_supply_missing_data_sentinels: 0,
114
+ annual_supply_unknown_normalized: 0,
115
+ annual_supply_evidence_gaps: 0,
114
116
  source_exchange_completeness_proofs: 0,
115
117
  },
116
118
  source_rows_file: sourceRowsFile && hasFile(sourceRowsFile) ? repoRelativePath(root, sourceRowsFile) : null,
117
119
  source_exchange_completeness_proofs: [],
120
+ annual_supply_evidence_gaps: [],
118
121
  blockers,
119
122
  policy: {
120
123
  purpose: "Reject invalid TIDAS/ILCD datetime metadata before any cleanup transform or cleaned-row output.",
@@ -133,12 +136,21 @@ export function runDatasetCurationCleanup({ repoRoot, options = {}, io, } = {})
133
136
  let externalizedSourceTraceSummaries = 0;
134
137
  let addedFoundryTraceNamespaces = 0;
135
138
  let redactedFoundryTraceEvidenceLocators = 0;
136
- let annualSupplyMissingDataSentinels = 0;
139
+ let annualSupplyUnknownNormalized = 0;
137
140
  let sourceExchangeCompletenessProofs = 0;
138
141
  const sourceExchangeProofRows = [];
142
+ const inputPayloadSha256 = rows.map((row, rowIndex) => sha256Json(datasetIdentity(row, rowIndex, datasetType).payload));
143
+ const pendingAnnualSupplyGaps = [];
139
144
  cleanedRows.forEach((cleaned, rowIndex) => {
140
- if (applyAnnualSupplyMissingDataSentinel(cleaned, datasetType)) {
141
- annualSupplyMissingDataSentinels += 1;
145
+ const annualSupply = normalizeAnnualSupplyEvidence(cleaned, datasetType);
146
+ if (annualSupply.changed)
147
+ annualSupplyUnknownNormalized += 1;
148
+ if (annualSupply.gap) {
149
+ pendingAnnualSupplyGaps.push({
150
+ index: rowIndex,
151
+ reason: annualSupply.gap.reason,
152
+ reviewRequired: annualSupply.gap.review_required,
153
+ });
142
154
  }
143
155
  if (applyDeterministicSourceExchangeCompletenessProofs(cleaned, datasetType, {
144
156
  rowIndex,
@@ -155,6 +167,23 @@ export function runDatasetCurationCleanup({ repoRoot, options = {}, io, } = {})
155
167
  redactedFoundryTraceEvidenceLocators += sanitizeFoundryTraceEvidenceLocators(cleaned);
156
168
  addedFoundryTraceNamespaces += ensureFoundryTraceNamespaces(cleaned);
157
169
  });
170
+ // Bound only after every other cleanup transform has run, so the output hash describes the
171
+ // exact unwrapped payload the caller will write, with no row metadata mixed in.
172
+ const annualSupplyEvidenceGaps = pendingAnnualSupplyGaps.map((pending) => {
173
+ const identity = datasetIdentity(rows[pending.index], pending.index, datasetType);
174
+ const outputIdentity = datasetIdentity(cleanedRows[pending.index], pending.index, datasetType);
175
+ return {
176
+ row_index: pending.index,
177
+ dataset_type: datasetType,
178
+ dataset_id: identity.id,
179
+ version: identity.version,
180
+ field: annualSupplyFieldPath,
181
+ reason: pending.reason,
182
+ review_required: pending.reviewRequired,
183
+ input_payload_sha256: inputPayloadSha256[pending.index] ?? null,
184
+ output_payload_sha256: sha256Json(outputIdentity.payload),
185
+ };
186
+ });
158
187
  writeRows(outFile, jsonLines(cleanedRows));
159
188
  const report = {
160
189
  schema_version: 2,
@@ -173,11 +202,13 @@ export function runDatasetCurationCleanup({ repoRoot, options = {}, io, } = {})
173
202
  redacted_foundry_trace_evidence_locators: redactedFoundryTraceEvidenceLocators,
174
203
  added_foundry_trace_namespaces: addedFoundryTraceNamespaces,
175
204
  normalized_datetime_values: normalizedDateTimeValues,
176
- annual_supply_missing_data_sentinels: annualSupplyMissingDataSentinels,
205
+ annual_supply_unknown_normalized: annualSupplyUnknownNormalized,
206
+ annual_supply_evidence_gaps: annualSupplyEvidenceGaps.length,
177
207
  source_exchange_completeness_proofs: sourceExchangeCompletenessProofs,
178
208
  },
179
209
  source_rows_file: sourceRowsFile && hasFile(sourceRowsFile) ? repoRelativePath(root, sourceRowsFile) : null,
180
210
  source_exchange_completeness_proofs: sourceExchangeProofRows,
211
+ annual_supply_evidence_gaps: annualSupplyEvidenceGaps,
181
212
  blockers: [],
182
213
  policy: {
183
214
  purpose: "Normalize write-time metadata and externalize import-only tidasimport:sourceTrace after curation context has been captured and before remote write.",
@@ -186,7 +217,7 @@ export function runDatasetCurationCleanup({ repoRoot, options = {}, io, } = {})
186
217
  foundry_trace_namespace_policy: "Any common:other tiangongfoundry:* trace kept in write payload gets @xmlns:tiangongfoundry before Rust tidas validation.",
187
218
  foundry_trace_locator_policy: "Local machine paths from tiangongfoundry:* trace evidence are redacted from write payloads; authoring packages and patch evidence retain the full local context.",
188
219
  datetime_policy: "TIDAS/ILCD dateTime values with timezone offsets are normalized to UTC Z form when the UTC projection remains inside the accepted four-digit year grammar; valid year-boundary offsets retain their exact source bytes.",
189
- annual_supply_placeholder_policy: `annualSupplyOrProductionVolume is schema-required. If source evidence is missing or converted as a placeholder such as 'Not specified', Foundry writes '${annualSupplyMissingDataSentinelText}' so the row remains importable and later database-side curation can bulk-locate the intentionally non-physical sentinel.`,
220
+ annual_supply_evidence_policy: "annualSupplyOrProductionVolume is schema-required. Foundry preserves real evidence — a single object or a language array — byte-semantically and in its original element order, and never rewrites a real quantity that merely collides numerically with a historical marker. A missing, empty, or explicitly-marked-absent volume is normalized to the supported empty array and reported as a row-level evidence gap in annual_supply_evidence_gaps; Foundry never fills in a synthesized quantity. Unsupported shapes are left untouched for the SDK/CLI gate to reject. Cleanup completion means the local transform finished, not that the row is authoring, write, or publication ready; downstream schema, authoring, curation, and write gates remain the blocking owners.",
190
221
  source_exchange_completeness_policy: "For process rows, if an explicit source rows file is supplied and the source process row is Output-only with the same non-flow-reference exchange signature as the final row, Foundry may write deterministic tiangongfoundry:sourceExchangeCompleteness proof. Otherwise source-only-output acceptance still requires AI source_trace_verified evidence or exchange repair.",
191
222
  },
192
223
  };
@@ -6,7 +6,7 @@ import { asText, directoryExists, ensureArray, fileExists, readJson, readText, r
6
6
  function asJsonRecord(value) {
7
7
  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
8
8
  }
9
- export const tidasSchemaSearchRoots = ["@tiangong-lca/cli@0.1.14/assets/tidas-schemas"];
9
+ export const tidasSchemaSearchRoots = ["@tiangong-lca/cli@0.1.19/assets/tidas-schemas"];
10
10
  export function tidasSchemaPath(repoRoot, schemaFile) {
11
11
  void repoRoot;
12
12
  const candidate = path.join(resolveInstalledTiangongLcaCliPackage().schemaDir, schemaFile);
@@ -1,5 +1,6 @@
1
1
  import { datasetIdentity } from "./dataset-payload.ts";
2
- export declare const annualSupplyMissingDataSentinelText = "9999 missing-data-sentinel/year";
2
+ export declare const legacyAnnualSupplyMissingDataSentinelText = "9999 missing-data-sentinel/year";
3
+ export declare const annualSupplyFieldPath = "processDataSet.modellingAndValidation.dataSourcesTreatmentAndRepresentativeness.annualSupplyOrProductionVolume";
3
4
  export declare const foundryTraceNamespace = "https://tiangong-lca.dev/foundry/import-curation/1";
4
5
  interface JsonRecord {
5
6
  [key: string]: unknown;
@@ -19,7 +20,17 @@ interface SourceExchangeProofOptions {
19
20
  }
20
21
  export declare function normalizeUtcDateTimeString(value: unknown): string | null;
21
22
  export declare function normalizeDateTimeMetadata(value: unknown): number;
22
- export declare function applyAnnualSupplyMissingDataSentinel(row: unknown, datasetType: string): boolean;
23
+ export type AnnualSupplyGapReason = "missing" | "empty" | "legacy_marker" | "explicit_missing_text" | "already_unknown" | "mixed_entries";
24
+ export interface AnnualSupplyGap {
25
+ field: string;
26
+ reason: AnnualSupplyGapReason;
27
+ review_required: boolean;
28
+ }
29
+ export interface AnnualSupplyResult {
30
+ changed: boolean;
31
+ gap: AnnualSupplyGap | null;
32
+ }
33
+ export declare function normalizeAnnualSupplyEvidence(row: unknown, datasetType: string): AnnualSupplyResult;
23
34
  export declare function applyDeterministicSourceExchangeCompletenessProofs(row: unknown, datasetType: string, { rowIndex, sourceRowsByKey, sourceRowsFile, rowsFile, proofRows, }?: SourceExchangeProofOptions): boolean;
24
35
  export declare function buildSourceRowsByIdentity(sourceRows: unknown[]): SourceRowsByIdentity;
25
36
  export declare function externalizeImportTraceMetadata(value: unknown): {
@@ -1,7 +1,10 @@
1
1
  import { datasetIdentity, datasetRoot, unwrapDatasetPayload } from "./dataset-payload.js";
2
2
  import { sha256Json, sha256Text } from "./hash-utils.js";
3
3
  import { asText, ensureArray } from "./runtime-io.js";
4
- export const annualSupplyMissingDataSentinelText = "9999 missing-data-sentinel/year";
4
+ // Historical recognition marker only. Foundry no longer writes this value; it is retained so
5
+ // service rows written by earlier rounds can still be recognized and normalized.
6
+ export const legacyAnnualSupplyMissingDataSentinelText = "9999 missing-data-sentinel/year";
7
+ export const annualSupplyFieldPath = "processDataSet.modellingAndValidation.dataSourcesTreatmentAndRepresentativeness.annualSupplyOrProductionVolume";
5
8
  export const foundryTraceNamespace = "https://tiangong-lca.dev/foundry/import-curation/1";
6
9
  const datetimeFieldsToNormalize = new Set(["common:timeStamp", "common:dateOfLastRevision"]);
7
10
  const foundryTraceKeys = [
@@ -118,46 +121,114 @@ export function normalizeDateTimeMetadata(value) {
118
121
  update.parent[update.key] = update.normalized;
119
122
  return updates.length;
120
123
  }
121
- function annualSupplyTextValue(value) {
122
- if (typeof value === "string")
123
- return value.trim();
124
- if (isRecord(value)) {
125
- return asText(value["#text"] ?? value.value);
124
+ // Narrow, complete-string recognition only. Scientific prose that merely mentions an unknown or
125
+ // unavailable volume stays untouched; the downstream SDK/CLI/authoring gates own rejecting it.
126
+ const missingAnnualSupplyTexts = new Set([
127
+ "not specified",
128
+ "not declared in source package",
129
+ "source production volume unavailable",
130
+ "production volume unavailable",
131
+ "source evidence unavailable",
132
+ ]);
133
+ function normalizeAnnualSupplyText(value) {
134
+ return value.trim().toLowerCase().replace(/\s+/gu, " ").replace(/\.$/u, "");
135
+ }
136
+ function classifyAnnualSupplyText(text) {
137
+ const normalized = normalizeAnnualSupplyText(text);
138
+ if (normalized === normalizeAnnualSupplyText(legacyAnnualSupplyMissingDataSentinelText)) {
139
+ return { kind: "unknown", reason: "legacy_marker" };
140
+ }
141
+ if (normalized === "")
142
+ return { kind: "unknown", reason: "empty" };
143
+ if (missingAnnualSupplyTexts.has(normalized)) {
144
+ return { kind: "unknown", reason: "explicit_missing_text" };
126
145
  }
127
- return "";
146
+ return { kind: "real", text };
128
147
  }
129
- function isPlaceholderAnnualSupplyValue(value) {
130
- const text = annualSupplyTextValue(value);
131
- const normalized = text.toLowerCase();
132
- return (!text ||
133
- /^9999$/u.test(text) ||
134
- /^not\s+specified\.?$/iu.test(text) ||
135
- /^not\s+declared\s+in\s+source\s+package\.?$/iu.test(text) ||
136
- normalized.includes("source production volume unavailable") ||
137
- normalized.includes("production volume unavailable") ||
138
- normalized.includes("source evidence unavailable"));
148
+ function classifyAnnualSupplyEntry(value) {
149
+ if (typeof value === "string")
150
+ return classifyAnnualSupplyText(value);
151
+ if (!isRecord(value))
152
+ return null;
153
+ const raw = value["#text"] ?? value.value;
154
+ if (typeof raw !== "string")
155
+ return null;
156
+ return classifyAnnualSupplyText(raw);
157
+ }
158
+ // A language-array entry must be an object carrying both a non-empty string `@xml:lang` and a
159
+ // string `#text`. Any other element — including plain strings such as `["Not specified"]` — is an
160
+ // unsupported shape and is preserved untouched so the SDK/CLI gate owns rejecting it.
161
+ function classifyAnnualSupplyLanguageEntry(value) {
162
+ if (!isRecord(value))
163
+ return null;
164
+ const language = value["@xml:lang"];
165
+ if (typeof language !== "string" || language.trim() === "")
166
+ return null;
167
+ const text = value["#text"];
168
+ if (typeof text !== "string")
169
+ return null;
170
+ return classifyAnnualSupplyText(text);
139
171
  }
140
- function annualSupplySentinelValue() {
172
+ function unchangedAnnualSupplyResult(reason, reviewRequired = false) {
141
173
  return {
142
- "@xml:lang": "en",
143
- "#text": annualSupplyMissingDataSentinelText,
174
+ changed: false,
175
+ gap: reason === null
176
+ ? null
177
+ : { field: annualSupplyFieldPath, reason, review_required: reviewRequired },
144
178
  };
145
179
  }
146
- export function applyAnnualSupplyMissingDataSentinel(row, datasetType) {
147
- if (datasetType !== "process")
148
- return false;
180
+ function annualSupplyContainer(row, datasetType) {
149
181
  const payload = unwrapDatasetPayload(row, datasetType);
150
182
  const root = datasetRoot(payload, datasetType);
151
183
  const modelling = isRecord(root.modellingAndValidation) ? root.modellingAndValidation : {};
152
184
  const dataSources = modelling.dataSourcesTreatmentAndRepresentativeness;
153
- if (!isRecord(dataSources))
154
- return false;
185
+ return isRecord(dataSources) ? dataSources : null;
186
+ }
187
+ // Unknown volume is written as the supported empty language array; it is never filled with a
188
+ // synthesized quantity, and the runner reports it as a row-level evidence gap.
189
+ function unknownAnnualSupplyResult(dataSources, reason) {
190
+ dataSources.annualSupplyOrProductionVolume = [];
191
+ return {
192
+ changed: true,
193
+ gap: { field: annualSupplyFieldPath, reason, review_required: false },
194
+ };
195
+ }
196
+ // Real evidence — single object or language array — is preserved byte-semantically, including its
197
+ // original element order. Unsupported shapes are preserved for the SDK/CLI gate to reject.
198
+ export function normalizeAnnualSupplyEvidence(row, datasetType) {
199
+ if (datasetType !== "process")
200
+ return unchangedAnnualSupplyResult(null);
201
+ const dataSources = annualSupplyContainer(row, datasetType);
202
+ if (!dataSources)
203
+ return unchangedAnnualSupplyResult(null);
155
204
  const current = dataSources.annualSupplyOrProductionVolume;
156
- if (current !== undefined && !isPlaceholderAnnualSupplyValue(current)) {
157
- return false;
205
+ if (current === undefined || current === null) {
206
+ return unknownAnnualSupplyResult(dataSources, "missing");
158
207
  }
159
- dataSources.annualSupplyOrProductionVolume = annualSupplySentinelValue();
160
- return true;
208
+ if (Array.isArray(current)) {
209
+ if (current.length === 0)
210
+ return unchangedAnnualSupplyResult("already_unknown");
211
+ const entries = [];
212
+ for (const element of current) {
213
+ const classified = classifyAnnualSupplyLanguageEntry(element);
214
+ if (classified === null)
215
+ return unchangedAnnualSupplyResult(null);
216
+ entries.push(classified);
217
+ }
218
+ const realCount = entries.filter((entry) => entry.kind === "real").length;
219
+ if (realCount === entries.length)
220
+ return unchangedAnnualSupplyResult(null);
221
+ if (realCount === 0) {
222
+ const legacyOnly = entries.every((entry) => entry.kind === "unknown" && entry.reason === "legacy_marker");
223
+ return unknownAnnualSupplyResult(dataSources, legacyOnly ? "legacy_marker" : "explicit_missing_text");
224
+ }
225
+ // Mixed real and unknown entries: keep every real element and flag the row for review.
226
+ return unchangedAnnualSupplyResult("mixed_entries", true);
227
+ }
228
+ const single = classifyAnnualSupplyEntry(current);
229
+ if (single === null || single.kind === "real")
230
+ return unchangedAnnualSupplyResult(null);
231
+ return unknownAnnualSupplyResult(dataSources, single.reason);
161
232
  }
162
233
  function processDataSetInformation(row) {
163
234
  const payload = unwrapDatasetPayload(row, "process");
@@ -2,7 +2,6 @@ import fs from "node:fs";
2
2
  import path from "node:path";
3
3
  import { datasetTypePlural, supportedDatasetTypes } from "./dataset-types.js";
4
4
  import { sha256Text } from "./hash-utils.js";
5
- import { annualSupplyMissingDataSentinelText } from "./prewrite-cleanup.js";
6
5
  import { asText, ensureArray, fileExists, jsonLines, nowIso, readJson, readText, repoRelativePath, resolveRepoPath, sanitizeFileName, unique, writeJson, writeText, } from "./runtime-io.js";
7
6
  import { buildPatchTemplate, contextSummaryHasKind, contextSummaryHasNonEmptyPayload, contextSummaryHasPattern, decisionOnlyActionItems, fullContextAiConfigRequiresAuthoring, markdownList, packageContextFileSummary, patchAuthoringActionItems, relOrNull, requiredFullContextFilePatterns, requiredFullContextKinds, sharedContextBundleReadinessBlockers, } from "./workflow-semantic-actions.js";
8
7
  function isRecord(value) {
@@ -245,7 +244,7 @@ The patch must:
245
244
  - preserve source-language content and provide evidence-backed English for fields required by the current TIDAS/profile contract; keep the same factual meaning
246
245
  - do not use \`common:other\` as a substitute for mandatory schema fields; schema-required values need evidence-backed values or must remain blocked
247
246
  - if a value cannot be inferred safely and the action item's allowed modes include \`deferred_to_common_other\`, add \`common:other.tiangongfoundry:unresolvedTrace\` with \`status\`, \`action_item_code\`, \`blocked_path\`, \`reason\`, structured \`evidence\`, and \`next_action\`; evidence must include source plus quote/trace/path/citation pointer
248
- - do not defer \`annualSupplyOrProductionVolume\` to \`common:other\`; if source annual volume evidence is missing, Foundry deterministic cleanup writes \`${annualSupplyMissingDataSentinelText}\` into the required field for later database-side curation
247
+ - do not defer \`annualSupplyOrProductionVolume\` to \`common:other\` and never invent a quantity from a reference flow or a default unit; supply a real annualized quantity from source evidence, or leave the field to Foundry deterministic cleanup, which normalizes it to the supported empty array and records a row-level evidence gap
249
248
  - if source exchange completeness is being accepted as source-faithful, use \`resolution.mode=source_trace_verified\` and add \`common:other.tiangongfoundry:sourceExchangeCompleteness\` with accepted \`status\` and structured source trace evidence; evidence must include source plus quote/trace/path/citation pointer
250
249
 
251
250
  ## Deterministic Apply
@@ -1,5 +1,4 @@
1
1
  import path from "node:path";
2
- import { annualSupplyMissingDataSentinelText } from "./prewrite-cleanup.js";
3
2
  import { asText, ensureArray, fileExists, optionList, readJson, readRows, readText, repoRelativePath, resolveRepoPath, unique, } from "./runtime-io.js";
4
3
  import { operationFullContextEvidenceBlockers, operationHasEvidence, operationResolution, operationResolutionMode, operationTouchesCommonOther, operationUsedContextKinds, patchSetAuthoringPackage, patchSetDatasetId, patchSetDatasetVersion, patchSetOperations, taskRequiredContextKinds, taskRequiresFullContextEvidence, } from "./workflow-authoring-tasks.js";
5
4
  import { containsAiTemplatePlaceholder, operationClosesAnnualSupplyTarget, operationClosureCodes, operationClosureKeys, operationTargetsLocationCode, taskActionItemKeys, taskActionItemsForOperation, taskAuthoringPackageName, validateDeferredCommonOtherTrace, validateFlowClassificationDecisionOperation, validateLocationDecisionOperation, validateProcessClassificationDecisionOperation, validateSourceExchangeCompletenessTrace, } from "./workflow-patch-evidence.js";
@@ -30,8 +29,8 @@ export function validateCollectedPatchSet({ repoRoot, task, patchSet, patchSetIn
30
29
  if (deferredAnnualSupply) {
31
30
  blockers.push({
32
31
  code: "patch_deferred_annual_supply_not_allowed",
33
- message: "annualSupplyOrProductionVolume is schema-required and must not be deferred to common:other; use Foundry deterministic cleanup to write the searchable 9999 missing-data sentinel when source evidence is missing.",
34
- sentinel_value: annualSupplyMissingDataSentinelText,
32
+ message: "annualSupplyOrProductionVolume is schema-required and must not be deferred to common:other; supply a real annualized quantity from source evidence, or let Foundry deterministic cleanup normalize the field to the supported empty array and record a row-level evidence gap.",
33
+ normalized_unknown_value: [],
35
34
  patch_file: patchLocation,
36
35
  patch_set_index: patchSetIndex,
37
36
  entity,
@@ -1,7 +1,7 @@
1
1
  import path from "node:path";
2
2
  import { resolveArtifactPath } from "./artifact-inputs.js";
3
3
  import { identityKey, detectDatasetType, unwrapDatasetPayload } from "./dataset-payload.js";
4
- import { annualSupplyMissingDataSentinelText } from "./prewrite-cleanup.js";
4
+ import { annualSupplyFieldPath as canonicalAnnualSupplyFieldPath, legacyAnnualSupplyMissingDataSentinelText, } from "./prewrite-cleanup.js";
5
5
  import { asText, directoryExists, ensureArray, fileExists, readJson, readJsonIfExists, readRows, repoRelativePath, resolveRepoPath, } from "./runtime-io.js";
6
6
  function isRecord(value) {
7
7
  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
@@ -10,7 +10,7 @@ function isQueueTask(value) {
10
10
  return Boolean(value) && typeof value === "object";
11
11
  }
12
12
  // part-00.mjs
13
- export const annualSupplyFieldPath = "processDataSet.modellingAndValidation.dataSourcesTreatmentAndRepresentativeness.annualSupplyOrProductionVolume";
13
+ export const annualSupplyFieldPath = canonicalAnnualSupplyFieldPath;
14
14
  export function isAnnualSupplyTarget(code, itemPath) {
15
15
  return (asText(code).startsWith("annual_supply_or_production_volume") ||
16
16
  asText(itemPath).includes("annualSupplyOrProductionVolume"));
@@ -24,7 +24,7 @@ export function schemaIssueInstruction(issue) {
24
24
  const code = String(typedIssue?.code ?? "");
25
25
  const issuePath = String(typedIssue?.path ?? "");
26
26
  if (isAnnualSupplyTarget(code, issuePath)) {
27
- return `Use source evidence or an explicitly documented profile fallback to write annualSupplyOrProductionVolume as a real annualized quantity with unit, for example '<number> <unit>/year'. If no annualized source evidence exists, Foundry deterministic cleanup must write the intentionally non-physical sentinel '${annualSupplyMissingDataSentinelText}' so database-side follow-up can bulk-locate and replace it later.`;
27
+ return `Use source evidence or an explicitly documented profile fallback to write annualSupplyOrProductionVolume as a real annualized quantity with unit, for example '<number> <unit>/year'. Never invent a quantity from a reference flow or a default unit. If no annualized source evidence exists, Foundry deterministic cleanup normalizes the field to the supported empty array and records a row-level evidence gap; the historical '${legacyAnnualSupplyMissingDataSentinelText}' marker is recognized only so rows written by earlier rounds can be normalized, and is never written again.`;
28
28
  }
29
29
  if (code === "invalid_format") {
30
30
  return "Use the SDK schema and methodology YAML for this field to replace the invalid value with a schema-valid source-backed value.";
@@ -44,17 +44,17 @@ export function schemaIssueCurationAction(issue) {
44
44
  instruction: schemaIssueInstruction(issue),
45
45
  ...(annualSupplyIssue
46
46
  ? {
47
- sentinel_completion_allowed: true,
48
- sentinel_cleanup_path: annualSupplyFieldPath,
49
- sentinel_value: annualSupplyMissingDataSentinelText,
50
- sentinel_policy: "The 9999 missing-data sentinel is intentionally non-physical and easy to bulk-query; later database-side curation owns replacing it with real annual volume evidence.",
47
+ unknown_normalization_allowed: true,
48
+ cleanup_field_path: annualSupplyFieldPath,
49
+ normalized_unknown_value: [],
50
+ unknown_evidence_policy: "An absent annual volume is normalized to the supported empty array and reported as a row-level evidence gap; Foundry never writes a synthesized quantity, and downstream schema, authoring, curation, and write gates keep owning rejection.",
51
51
  }
52
52
  : {}),
53
53
  };
54
54
  if (annualSupplyIssue) {
55
55
  return {
56
56
  ...base,
57
- action_kind: "annual_supply_sentinel_completion",
57
+ action_kind: "annual_supply_unknown_evidence_normalization",
58
58
  required_owner: "foundry_deterministic_cleanup",
59
59
  ai_required: false,
60
60
  instruction: schemaIssueInstruction(issue),
@@ -3,7 +3,6 @@ import { normalizeTidasLanguageCode } from "../../tidas-language-utils.js";
3
3
  import { fullContextAiCompletionRequirement } from "./context-inputs.js";
4
4
  import { dataSetInformation, datasetRoot } from "./dataset-payload.js";
5
5
  import { sha256Text } from "./hash-utils.js";
6
- import { annualSupplyMissingDataSentinelText } from "./prewrite-cleanup.js";
7
6
  import { asText, ensureArray, fileExists, readJson, repoRelativeArtifactPath, repoRelativePath, resolveRepoPath, } from "./runtime-io.js";
8
7
  import { collectCommonOtherTraceEntries } from "./trace-summary.js";
9
8
  import { hasNonEmptyTraceEvidence } from "./workflow-authoring-tasks.js";
@@ -498,6 +497,17 @@ export function collectNamePlanQualitySemanticActions(payload, datasetType) {
498
497
  : "name.baseName contains route, mix, availability, or location segments that should be split into the structured TIDAS name fields.",
499
498
  evidence: {
500
499
  ...finding,
500
+ // W8 public premises are referenced by identity; source-specific detection and
501
+ // the decision to block remain Foundry policy, not copied public definitions.
502
+ public_rule_refs: finding.code === "semantic_name_base_contains_unsplit_segments" ||
503
+ finding.code === "semantic_name_quantitative_property_not_split"
504
+ ? datasetType === "flow"
505
+ ? ["tidas.flow.name.base-name.technical"]
506
+ : datasetType === "process"
507
+ ? ["tidas.process.name.qualifiers.structured"]
508
+ : []
509
+ : [],
510
+ public_rule_source: "tiangong-lca/tidas-spec@ea4a58984c22734f2d54cda6d45b2733d9920ac0:assets/tidas/rules/public-rules.v1.json",
501
511
  current_name: {
502
512
  baseName: textValue(name?.baseName) || null,
503
513
  treatmentStandardsRoutes: textValue(name?.treatmentStandardsRoutes) || null,
@@ -1225,7 +1235,7 @@ export function buildPatchTemplate(packagePayload, packagePath) {
1225
1235
  "Do not remove authoring_package; strict Foundry apply uses it for package lineage and action-item closure.",
1226
1236
  "Do not use common:other as a substitute for mandatory schema fields. Only action items whose allowed_resolution_modes include deferred_to_common_other may be deferred.",
1227
1237
  "For deferred_to_common_other, add tiangongfoundry:unresolvedTrace under common:other with status, action_item_code, blocked_path, reason, structured evidence, and next_action. Evidence must include source plus quote_or_trace/source_path/field_path/citation.",
1228
- `Do not defer annualSupplyOrProductionVolume to common:other. When source annual volume evidence is missing, Foundry deterministic cleanup writes '${annualSupplyMissingDataSentinelText}' so the required schema field remains present and later database-side curation can bulk-locate it.`,
1238
+ "Do not defer annualSupplyOrProductionVolume to common:other and do not invent a quantity from a reference flow or a default unit. Supply a real annualized quantity from source evidence, or leave the field to Foundry deterministic cleanup, which normalizes it to the supported empty array and records a row-level evidence gap.",
1229
1239
  "For source_trace_verified, add tiangongfoundry:sourceExchangeCompleteness under common:other with accepted status and structured source trace evidence. Evidence must include source plus quote_or_trace/source_path/field_path/citation.",
1230
1240
  ],
1231
1241
  patch_sets: [
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tiangong-lca/foundry",
3
- "version": "0.1.9",
3
+ "version": "0.1.10",
4
4
  "type": "module",
5
5
  "description": "Control plane for TianGong LCA external dataset import and TIDAS authoring work.",
6
6
  "repository": {
@@ -81,7 +81,7 @@
81
81
  },
82
82
  "license": "MIT",
83
83
  "dependencies": {
84
- "@tiangong-lca/cli": "0.1.14"
84
+ "@tiangong-lca/cli": "0.1.19"
85
85
  },
86
86
  "foundryRuntime": {
87
87
  "schema": "tiangong-foundry.runtime-layout.v2",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "schema_version": 2,
3
- "updated_at_utc": "2026-09-10T23:06:45Z",
3
+ "updated_at_utc": "2026-09-21T07:44:02Z",
4
4
  "default_profile": "generic",
5
5
  "profiles": {
6
6
  "generic": {