@tiangong-lca/cli 0.0.22 → 0.0.24

package/dist/src/lib/dataset-maintenance-contract.js

@@ -2,6 +2,7 @@ import crypto from 'node:crypto';
 import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { inspectMaintenanceSupportPayload } from './dataset-maintenance-support-validation.js';
+import { isDatasetMaintenanceSnapshotCompleteness, } from './dataset-maintenance-pagination.js';
 import { CliError } from './errors.js';
 export const MAINTENANCE_MUTABLE_TABLES = ['contacts', 'sources', 'flows', 'processes'];
 export const MAINTENANCE_SUPPORT_TABLES = ['unitgroups', 'flowproperties'];
@@ -10,6 +11,7 @@ export const MAINTENANCE_SCAN_TABLES = [
     'lifecyclemodels',
     ...MAINTENANCE_SUPPORT_TABLES,
 ];
+export const DERIVATIVE_REBUILD_COMPONENTS = ['extracted_md', 'embedding_ft'];
 function token(value) {
     if (typeof value !== 'string') {
         return null;
@@ -158,16 +160,19 @@ function parseAction(value, index, accountUserId, operation) {
     }
     const action = requireToken(value.action, `actions[${index}].action`);
     const table = requireToken(value.table, `actions[${index}].table`);
-    if (!['save_draft', 'delete', 'update_json_ordered'].includes(action)) {
+    if (!['save_draft', 'delete', 'update_json_ordered', 'rebuild_derivatives'].includes(action)) {
         throw new CliError(`Unsupported maintenance action: ${action}`, {
             code: 'DATASET_MAINTENANCE_ACTION_UNSUPPORTED',
             exitCode: 2,
         });
     }
     const aliasAction = action === 'update_json_ordered';
-    const allowedTable = aliasAction
-        ? ['flowproperties', 'flows', 'processes'].includes(table)
-        : MAINTENANCE_MUTABLE_TABLES.includes(table);
+    const derivativeAction = action === 'rebuild_derivatives';
+    const allowedTable = derivativeAction
+        ? table === 'processes'
+        : aliasAction
+            ? ['flowproperties', 'flows', 'processes'].includes(table)
+            : MAINTENANCE_MUTABLE_TABLES.includes(table);
     if (!allowedTable) {
         throw new CliError(`Maintenance cannot mutate protected or unsupported dataset table: ${table}`, {
             code: 'DATASET_MAINTENANCE_TABLE_PROTECTED',
@@ -175,7 +180,9 @@ function parseAction(value, index, accountUserId, operation) {
         });
     }
     if ((operation === 'merge-support-aliases' && !aliasAction) ||
-        (operation !== 'merge-support-aliases' && aliasAction)) {
+        (operation === 'rebuild-derivatives' && !derivativeAction) ||
+        (!['merge-support-aliases', 'rebuild-derivatives'].includes(operation) &&
+            (aliasAction || derivativeAction))) {
         throw new CliError(`Maintenance operation ${operation} cannot contain ${action} actions.`, {
             code: 'DATASET_MAINTENANCE_OPERATION_ACTION_MISMATCH',
             exitCode: 2,
@@ -239,6 +246,23 @@ function parseAction(value, index, accountUserId, operation) {
             exitCode: 2,
         });
     }
+    const components = Array.isArray(value.components)
+        ? value.components.map((component, componentIndex) => requireToken(component, `actions[${index}].components[${componentIndex}]`))
+        : [];
+    if (derivativeAction &&
+        (components.length !== DERIVATIVE_REBUILD_COMPONENTS.length ||
+            components.some((component, componentIndex) => component !== DERIVATIVE_REBUILD_COMPONENTS[componentIndex]))) {
+        throw new CliError(`Derivative rebuild action ${index} requires components in exact order: ${DERIVATIVE_REBUILD_COMPONENTS.join(', ')}.`, {
+            code: 'DATASET_MAINTENANCE_DERIVATIVE_COMPONENTS_INVALID',
+            exitCode: 2,
+        });
+    }
+    if (!derivativeAction && 'components' in value) {
+        throw new CliError(`Maintenance non-derivative action ${index} cannot include components.`, {
+            code: 'DATASET_MAINTENANCE_DERIVATIVE_COMPONENTS_INVALID',
+            exitCode: 2,
+        });
+    }
     const exchangeKeys = new Set(exchangeInstances.map((entry) => `${entry.exchange_index}\u0000${entry.data_set_internal_id}\u0000${entry.flow_id}`));
     if (exchangeKeys.size !== exchangeInstances.length) {
         throw new CliError(`Alias action ${index} contains duplicate exchange instances.`, {
@@ -268,6 +292,7 @@ function parseAction(value, index, accountUserId, operation) {
         ...(exchangeInstances.length ? { exchange_instances: exchangeInstances } : {}),
         ...(desiredPayloadPath ? { desired_payload_path: desiredPayloadPath } : {}),
         ...(expectedBeforeSha256 ? { expected_before_sha256: expectedBeforeSha256 } : {}),
+        ...(derivativeAction ? { components: [...DERIVATIVE_REBUILD_COMPONENTS] } : {}),
     };
 }
 export function parseMaintenanceScope(value, expectedOperation) {
@@ -278,7 +303,14 @@ export function parseMaintenanceScope(value, expectedOperation) {
         });
     }
     const operation = requireToken(value.operation, 'operation');
-    if (!['delete', 'retire', 'redo-import', 'repair-references', 'merge-support-aliases'].includes(operation)) {
+    if (![
+        'delete',
+        'retire',
+        'redo-import',
+        'repair-references',
+        'merge-support-aliases',
+        'rebuild-derivatives',
+    ].includes(operation)) {
         throw new CliError(`Unsupported maintenance operation: ${operation}`, {
             code: 'DATASET_MAINTENANCE_OPERATION_UNSUPPORTED',
             exitCode: 2,
@@ -299,9 +331,10 @@ export function parseMaintenanceScope(value, expectedOperation) {
     }
     const actions = value.actions.map((entry, index) => parseAction(entry, index, userId, operation));
     const targetMode = token(value.target_mode);
-    if ((operation === 'merge-support-aliases' && targetMode !== 'owner_draft') ||
-        (operation !== 'merge-support-aliases' && targetMode !== null)) {
-        throw new CliError('merge-support-aliases requires target_mode=owner_draft; other operations forbid target_mode.', {
+    if ((['merge-support-aliases', 'rebuild-derivatives'].includes(operation) &&
+        targetMode !== 'owner_draft') ||
+        (!['merge-support-aliases', 'rebuild-derivatives'].includes(operation) && targetMode !== null)) {
+        throw new CliError('merge-support-aliases and rebuild-derivatives require target_mode=owner_draft; other operations forbid target_mode.', {
             code: 'DATASET_MAINTENANCE_TARGET_MODE_INVALID',
             exitCode: 2,
             details: { operation, target_mode: targetMode },
@@ -317,6 +350,12 @@ export function parseMaintenanceScope(value, expectedOperation) {
             exitCode: 2,
         });
     }
+    if (operation === 'rebuild-derivatives' && actions.length !== 1) {
+        throw new CliError('rebuild-derivatives requires exactly one action.', {
+            code: 'DATASET_MAINTENANCE_DERIVATIVE_ACTION_COUNT_INVALID',
+            exitCode: 2,
+        });
+    }
     if (aliasBatches.length) {
         const batchIds = new Set(aliasBatches.map((batch) => batch.batch_id));
         const dimensions = new Set(aliasBatches.map((batch) => batch.dimension));
@@ -473,6 +512,32 @@ export function computePlanSha256(plan) {
     const body = { ...plan, plan_sha256: '' };
     return sha256Json(body);
 }
+function validDerivativeSnapshot(value, action) {
+    if (!isJsonObject(value))
+        return false;
+    const requiredHashes = [
+        value.json_sha256,
+        value.json_ordered_sha256,
+        value.extracted_text_sha256,
+        value.snapshot_sha256,
+    ];
+    const nullableHashes = [value.extracted_md_sha256, value.embedding_ft_sha256];
+    return Boolean(value.schema_version === 'dataset-derivative-snapshot.v1' &&
+        value.table === 'processes' &&
+        value.id === action.id &&
+        value.version === action.version &&
+        value.user_id === action.expected_user_id &&
+        value.state_code === 0 &&
+        value.modified_at === action.before?.modified_at &&
+        typeof value.modified_at === 'string' &&
+        Number.isFinite(Date.parse(value.modified_at)) &&
+        requiredHashes.every((hash) => typeof hash === 'string' && /^[a-f0-9]{64}$/u.test(hash)) &&
+        nullableHashes.every((hash) => hash === null || (typeof hash === 'string' && /^[a-f0-9]{64}$/u.test(hash))) &&
+        value.json_sha256 === value.json_ordered_sha256 &&
+        (value.embedding_ft_at === null ||
+            (typeof value.embedding_ft_at === 'string' &&
+                Number.isFinite(Date.parse(value.embedding_ft_at)))));
+}
 export function parseMaintenancePlan(value) {
     if (!isJsonObject(value) ||
         value.schema_version !== 1 ||
@@ -487,6 +552,13 @@ export function parseMaintenancePlan(value) {
         });
     }
     const plan = value;
+    if (plan.snapshot_completeness !== undefined &&
+        !isDatasetMaintenanceSnapshotCompleteness(plan.snapshot_completeness, MAINTENANCE_SCAN_TABLES)) {
+        throw new CliError('Maintenance plan snapshot completeness proof is invalid.', {
+            code: 'DATASET_MAINTENANCE_PLAN_INVALID',
+            exitCode: 2,
+        });
+    }
     const expected = computePlanSha256(plan);
     if (plan.plan_sha256 !== expected) {
         throw new CliError('Maintenance plan hash does not match its canonical contents.', {
@@ -585,13 +657,23 @@ export function parseMaintenancePlan(value) {
                 ? 'save_before_snapshot'
                 : action.action === 'delete'
                     ? 'restore_deleted_before_snapshot'
-                    : 'restore_atomic_alias_before_snapshot';
-            if (action.rollback.strategy !== expectedRollbackStrategy ||
-                action.rollback.before_payload_sha256 !== before.payload_sha256 ||
-                !isJsonObject(action.rollback.before_payload) ||
-                sha256Json(action.rollback.before_payload) !== before.payload_sha256 ||
-                action.rollback.model_id !== before.model_id ||
-                action.rollback.rule_verification !== before.rule_verification) {
+                    : action.action === 'update_json_ordered'
+                        ? 'restore_atomic_alias_before_snapshot'
+                        : 'none_derivative_only';
+            const derivativeRollback = action.action === 'rebuild_derivatives';
+            const rollbackMatches = derivativeRollback
+                ? action.rollback.strategy === expectedRollbackStrategy &&
+                    action.rollback.before_payload_sha256 === null &&
+                    action.rollback.before_payload === null &&
+                    action.rollback.model_id === null &&
+                    action.rollback.rule_verification === null
+                : action.rollback.strategy === expectedRollbackStrategy &&
+                    action.rollback.before_payload_sha256 === before.payload_sha256 &&
+                    isJsonObject(action.rollback.before_payload) &&
+                    sha256Json(action.rollback.before_payload) === before.payload_sha256 &&
+                    action.rollback.model_id === before.model_id &&
+                    action.rollback.rule_verification === before.rule_verification;
+            if (!rollbackMatches) {
                 throw new CliError('Ready maintenance plan action rollback snapshot is invalid.', {
                     code: 'DATASET_MAINTENANCE_PLAN_INVALID',
                     exitCode: 2,
@@ -621,6 +703,8 @@ export function parseMaintenancePlan(value) {
         plan.summary.delete === plan.actions.filter((action) => action.action === 'delete').length &&
         (plan.summary.update_json_ordered ?? 0) ===
             plan.actions.filter((action) => action.action === 'update_json_ordered').length &&
+        (plan.summary.rebuild_derivatives ?? 0) ===
+            plan.actions.filter((action) => action.action === 'rebuild_derivatives').length &&
         (plan.summary.atomic_batches ?? 0) === (plan.alias_batches?.length ?? 0) &&
         (plan.summary.scaled_exchanges ?? 0) ===
             (plan.alias_batches?.reduce((sum, batch) => sum + batch.summary.exchanges, 0) ?? 0) &&
@@ -831,6 +915,32 @@ export function parseMaintenancePlan(value) {
             });
         }
     }
+    if (plan.operation === 'rebuild-derivatives') {
+        const action = plan.actions[0];
+        const validDerivativePlan = Boolean(plan.target_mode === 'owner_draft' &&
+            plan.actions.length === 1 &&
+            !plan.alias_batches &&
+            plan.artifacts.derivative_baseline === 'derivative-baseline.json' &&
+            action?.action === 'rebuild_derivatives' &&
+            action.table === 'processes' &&
+            sha256Json(action.components) === sha256Json(DERIVATIVE_REBUILD_COMPONENTS) &&
+            action.desired_payload === null &&
+            action.rollback.strategy === 'none_derivative_only' &&
+            (action.status === 'blocked' || validDerivativeSnapshot(action.derivative_before, action)));
+        if (!validDerivativePlan) {
+            throw new CliError('Maintenance derivative rebuild plan contract is inconsistent.', {
+                code: 'DATASET_MAINTENANCE_PLAN_INVALID',
+                exitCode: 2,
+            });
+        }
+    }
+    else if (plan.actions.some((action) => action.derivative_before !== undefined) ||
+        plan.artifacts.derivative_baseline !== undefined) {
+        throw new CliError('Non-derivative maintenance plan contains derivative-only fields.', {
+            code: 'DATASET_MAINTENANCE_PLAN_INVALID',
+            exitCode: 2,
+        });
+    }
     return plan;
 }
 //# sourceMappingURL=dataset-maintenance-contract.js.map