@tiangong-lca/cli 0.1.0 → 0.1.2

package/dist/src/lib/dataset-maintenance-contract.d.ts

@@ -0,0 +1,317 @@
+import { type DatasetMaintenanceSnapshotCompleteness } from './dataset-maintenance-pagination.js';
+export type JsonObject = Record<string, unknown>;
+export declare const MAINTENANCE_MUTABLE_TABLES: readonly ['contacts', 'sources', 'flows', 'processes'];
+export declare const MAINTENANCE_SUPPORT_TABLES: readonly ['unitgroups', 'flowproperties'];
+export declare const MAINTENANCE_SCAN_TABLES: readonly ["contacts", "sources", "flows", "processes", "lifecyclemodels", "unitgroups", "flowproperties"];
+export type DatasetMaintenanceMutableTable = (typeof MAINTENANCE_MUTABLE_TABLES)[number];
+export type DatasetMaintenanceSupportTable = (typeof MAINTENANCE_SUPPORT_TABLES)[number];
+export type DatasetMaintenanceActionTable = DatasetMaintenanceMutableTable | 'flowproperties';
+export type DatasetMaintenanceScanTable = (typeof MAINTENANCE_SCAN_TABLES)[number];
+export type DatasetMaintenanceOperation = 'delete' | 'retire' | 'redo-import' | 'repair-references' | 'merge-support-aliases' | 'rebuild-derivatives';
+export type DatasetMaintenanceActionKind = 'save_draft' | 'delete' | 'update_json_ordered' | 'rebuild_derivatives';
+export type DatasetMaintenanceTargetMode = 'owner_draft';
+export declare const DERIVATIVE_REBUILD_COMPONENTS: readonly ['extracted_md', 'embedding_ft'];
+export type DatasetMaintenanceDerivativeComponent = (typeof DERIVATIVE_REBUILD_COMPONENTS)[number];
+export type DatasetMaintenanceDerivativeSnapshot = {
+    schema_version: 'dataset-derivative-snapshot.v1';
+    table: 'processes';
+    id: string;
+    version: string;
+    user_id: string;
+    state_code: 0;
+    modified_at: string;
+    json_sha256: string;
+    json_ordered_sha256: string;
+    extracted_md_sha256: string | null;
+    embedding_ft_sha256: string | null;
+    embedding_ft_at: string | null;
+    snapshot_sha256: string;
+};
+export type DatasetMaintenanceAliasDimension = 'time' | 'length_time';
+export type DatasetMaintenanceEntityRef = {
+    id: string;
+    version: string;
+};
+export type DatasetMaintenanceAliasBatch = {
+    batch_id: string;
+    dimension: DatasetMaintenanceAliasDimension;
+    factor: string;
+    source: {
+        unitgroup: DatasetMaintenanceEntityRef;
+        flowproperty: DatasetMaintenanceEntityRef;
+    };
+    target: {
+        unitgroup: DatasetMaintenanceEntityRef;
+        flowproperty: DatasetMaintenanceEntityRef;
+    };
+};
+export type DatasetMaintenanceExchangeInstance = {
+    exchange_index: number;
+    data_set_internal_id: string;
+    flow_id: string;
+    flow_version: string;
+    direction: 'Input' | 'Output';
+    before_exchange_sha256: string;
+    before_mean_amount: string;
+    before_resulting_amount: string;
+};
+export type DatasetMaintenanceAliasMutation = {
+    kind: 'flowproperty_unitgroup_reference';
+} | {
+    kind: 'flow_flowproperty_reference';
+    flow_property_internal_id: string;
+    source_flowproperty_id: string;
+    source_flowproperty_version: string;
+} | {
+    kind: 'process_exchange_amounts';
+    exchanges: Array<{
+        index: number;
+        internal_id: string;
+        flow_id: string;
+        flow_version: string;
+        direction: 'Input' | 'Output';
+        before_exchange_sha256: string;
+    }>;
+};
+export type DatasetMaintenanceScopeAction = {
+    action_id: string;
+    action: DatasetMaintenanceActionKind;
+    table: DatasetMaintenanceActionTable;
+    id: string;
+    version: string;
+    expected_user_id: string;
+    expected_state_code: 0;
+    reason_code: string;
+    reason: string;
+    evidence: unknown[];
+    batch_id?: string;
+    exchange_instances?: DatasetMaintenanceExchangeInstance[];
+    desired_payload_path?: string;
+    expected_before_sha256?: string;
+    components?: DatasetMaintenanceDerivativeComponent[];
+};
+export type DatasetMaintenanceScope = {
+    schema_version: 1;
+    task_id: string;
+    operation: DatasetMaintenanceOperation;
+    account: {
+        user_id: string;
+        email?: string;
+    };
+    source_import_run_id?: string;
+    source_lineage?: unknown;
+    target_mode?: DatasetMaintenanceTargetMode;
+    alias_batches?: DatasetMaintenanceAliasBatch[];
+    actions: DatasetMaintenanceScopeAction[];
+};
+export type DatasetMaintenanceRemoteRow = {
+    table: DatasetMaintenanceScanTable;
+    id: string;
+    version: string;
+    user_id: string | null;
+    state_code: number | null;
+    modified_at: string | null;
+    json?: JsonObject | null;
+    json_ordered: JsonObject | null;
+    model_id: string | null;
+    rule_verification: boolean | null;
+};
+export type DatasetMaintenanceRowSnapshot = DatasetMaintenanceRemoteRow & {
+    row_sha256: string;
+    payload_sha256: string | null;
+};
+export type DatasetMaintenanceBlocker = {
+    code: string;
+    message: string;
+    action_id?: string;
+    table?: DatasetMaintenanceScanTable;
+    id?: string;
+    version?: string;
+    details?: unknown;
+};
+export type DatasetMaintenanceProtectedRow = {
+    table: DatasetMaintenanceScanTable;
+    id: string;
+    version: string;
+    modified_at: string | null;
+    row_sha256: string;
+    payload_sha256: string | null;
+    reason: 'non_action_visible_row' | 'blocked_action_row';
+};
+export type DatasetMaintenanceReferenceImpact = {
+    target_action_id: string;
+    target_table: DatasetMaintenanceActionTable;
+    target_id: string;
+    target_version: string;
+    phase: 'current' | 'projected';
+    source_table: DatasetMaintenanceScanTable;
+    source_id: string;
+    source_version: string;
+    reference_path: string;
+    reference_version: string | null;
+};
+export type DatasetMaintenancePlanAction = DatasetMaintenanceScopeAction & {
+    ordinal: number;
+    status: 'ready' | 'blocked';
+    before: DatasetMaintenanceRowSnapshot | null;
+    desired_payload: {
+        path: string;
+        sha256: string;
+    } | null;
+    blockers: DatasetMaintenanceBlocker[];
+    alias_mutation?: DatasetMaintenanceAliasMutation;
+    derivative_before?: DatasetMaintenanceDerivativeSnapshot;
+    rollback: {
+        strategy: 'save_before_snapshot' | 'restore_deleted_before_snapshot' | 'restore_atomic_alias_before_snapshot' | 'none_derivative_only';
+        before_payload_sha256: string | null;
+        before_payload: JsonObject | null;
+        model_id: string | null;
+        rule_verification: boolean | null;
+    };
+};
+export type DatasetMaintenanceAliasExchangeRewrite = DatasetMaintenanceExchangeInstance & {
+    action_id: string;
+    process_id: string;
+    process_version: string;
+    after_mean_amount: string;
+    after_resulting_amount: string;
+    after_exchange_sha256: string;
+};
+export type DatasetMaintenanceAliasBatchPlan = DatasetMaintenanceAliasBatch & {
+    action_ids: string[];
+    target_snapshots: {
+        unitgroup: DatasetMaintenanceRowSnapshot | null;
+        flowproperty: DatasetMaintenanceRowSnapshot | null;
+        source_unitgroup: DatasetMaintenanceRowSnapshot | null;
+    };
+    conversion_evidence: {
+        source_unitgroup_payload_sha256: string | null;
+        source_reference_unit: JsonObject | null;
+        target_conversion_unit: JsonObject | null;
+    };
+    exchange_rewrites: DatasetMaintenanceAliasExchangeRewrite[];
+    summary: {
+        rows: number;
+        flowproperties: number;
+        flows: number;
+        processes: number;
+        exchanges: number;
+        amount_fields: number;
+        unrelated_exchanges: number;
+    };
+    postconditions: {
+        source_unitgroup_incoming_refs: number;
+        source_flowproperty_flow_refs: number;
+        target_flow_refs: number;
+        target_exchange_refs: number;
+    };
+};
+export type DatasetMaintenancePlan = {
+    schema_version: 1;
+    generated_at_utc: string;
+    task_id: string;
+    operation: DatasetMaintenanceOperation;
+    operation_id: string;
+    account: {
+        user_id: string;
+        email: string | null;
+    };
+    source_import_run_id: string | null;
+    source_lineage: unknown;
+    target_mode: DatasetMaintenanceTargetMode | null;
+    status: 'ready' | 'blocked';
+    scope_sha256: string;
+    visible_snapshot_sha256: string;
+    snapshot_completeness?: DatasetMaintenanceSnapshotCompleteness<DatasetMaintenanceScanTable>;
+    projected_reference_sha256: string;
+    plan_sha256: string;
+    summary: {
+        actions: number;
+        save_draft: number;
+        delete: number;
+        update_json_ordered?: number;
+        rebuild_derivatives?: number;
+        atomic_batches?: number;
+        scaled_exchanges?: number;
+        scaled_amount_fields?: number;
+        unrelated_exchanges_preserved?: number;
+        protected_rows: number;
+        blockers: number;
+        current_reference_impacts: number;
+        projected_reference_impacts: number;
+    };
+    artifacts: {
+        maintenance_scope: string;
+        rls_visible_snapshot: string;
+        protected_rows: string;
+        reference_impact_report: string;
+        maintenance_plan: string;
+        dry_run_report: string;
+        payload_dir: string;
+        exchange_rewrite_plan?: string;
+        derivative_baseline?: string;
+    };
+    actions: DatasetMaintenancePlanAction[];
+    alias_batches?: DatasetMaintenanceAliasBatchPlan[];
+    protected_rows: DatasetMaintenanceProtectedRow[];
+    blockers: DatasetMaintenanceBlocker[];
+};
+export type DatasetMaintenanceProgressEntry = {
+    schema_version: 1;
+    plan_sha256: string;
+    operation_id: string;
+    action_id: string;
+    action: DatasetMaintenanceActionKind;
+    table: DatasetMaintenanceActionTable;
+    id: string;
+    version: string;
+    reason_code: string;
+    audit_context: {
+        plan_sha256: string;
+        operation_id: string;
+        action_id: string;
+        reason_code: string;
+        source: 'tiangong-lca dataset maintenance apply';
+        target_mode?: DatasetMaintenanceTargetMode;
+    };
+    actor: {
+        user_id: string;
+        email: string;
+    };
+    started_at_utc: string;
+    ended_at_utc: string;
+    before_sha256: string;
+    after_sha256: string | null;
+    remote_result_sha256: string | null;
+    result: 'success' | 'failed';
+    error: string | null;
+    rollback: DatasetMaintenancePlanAction['rollback'];
+    batch_id?: string;
+    target_mode?: DatasetMaintenanceTargetMode;
+    batch_request_sha256?: string;
+    database_audit_id?: string;
+    summary_audit_id?: string;
+    plan_request_sha256?: string;
+    plan_summary_audit_id?: string;
+};
+export declare function isJsonObject(value: unknown): value is JsonObject;
+export declare function stableJsonValue(value: unknown): unknown;
+export declare function stableJsonText(value: unknown): string;
+export declare function sha256Text(value: string): string;
+export declare function sha256Json(value: unknown): string;
+export declare function snapshotRemoteRow(row: DatasetMaintenanceRemoteRow): DatasetMaintenanceRowSnapshot;
+export declare function maintenanceRowKey(row: {
+    table: DatasetMaintenanceScanTable;
+    id: string;
+    version: string;
+}): string;
+export declare function parseMaintenanceScope(value: unknown, expectedOperation?: DatasetMaintenanceOperation): DatasetMaintenanceScope;
+export declare function readJsonFile(filePath: string, label: string): unknown;
+export declare function writeImmutableJson(filePath: string, value: unknown): string;
+export declare function writeImmutableJsonLines(filePath: string, values: unknown[]): string;
+export declare function appendStableJsonLine(filePath: string, value: unknown): string;
+export declare function readJsonLinesIfPresent(filePath: string): unknown[];
+export declare function safeActionFileName(actionId: string): string;
+export declare function resolveMaintenancePlanArtifactPath(planDir: string, relativePath: string, label: string): string;
+export declare function computePlanSha256(plan: DatasetMaintenancePlan): string;
+export declare function parseMaintenancePlan(value: unknown): DatasetMaintenancePlan;

package/dist/src/lib/dataset-maintenance-derivatives.d.ts

@@ -0,0 +1,48 @@
+import { type DatasetMaintenanceDerivativeSnapshot, type DatasetMaintenancePlan, type DatasetMaintenancePlanAction, type JsonObject } from './dataset-maintenance-contract.js';
+export type DatasetMaintenanceDerivativeRequestStatus = 'queued' | 'dispatching' | 'markdown_pending' | 'embedding_pending' | 'completed' | 'stale' | 'failed';
+export type DatasetMaintenanceDerivativeSubmitProof = {
+    schema_version: 'dataset-derivative-rebuild-plan.v1';
+    plan_sha256: string;
+    operation_id: string;
+    target_visibility: 'owner_draft';
+    plan_request_sha256: string;
+    idempotent_replay: boolean;
+    action_count: 1;
+    accepted_count: 1;
+    summary_audit_id: string;
+    request_id: string;
+    status: DatasetMaintenanceDerivativeRequestStatus;
+    action_request_sha256: string;
+    database_audit_id: string;
+};
+export type DatasetMaintenanceDerivativeStatusProof = {
+    schema_version: 'dataset-derivative-rebuild-status.v1';
+    request_id: string;
+    plan_sha256: string;
+    operation_id: string;
+    action_id: string;
+    table: 'processes';
+    id: string;
+    version: string;
+    status: DatasetMaintenanceDerivativeRequestStatus;
+    phase: string;
+    fence_active: boolean;
+    plan_request_sha256: string;
+    action_request_sha256: string;
+    database_audit_id: string;
+    summary_audit_id: string;
+    completed_snapshot_sha256: string | null;
+    completed_at: string | null;
+    error: JsonObject | null;
+};
+export declare function parseDerivativeSnapshotResponse(value: unknown, expected: {
+    id: string;
+    version: string;
+    userId: string;
+}): DatasetMaintenanceDerivativeSnapshot;
+export declare function isDerivativeRebuildPlan(plan: DatasetMaintenancePlan): boolean;
+export declare function derivativePlanAction(plan: DatasetMaintenancePlan): DatasetMaintenancePlanAction;
+export declare function buildDerivativePlanRequest(plan: DatasetMaintenancePlan): JsonObject;
+export declare function parseDerivativeSubmitResponse(value: unknown, plan: DatasetMaintenancePlan): DatasetMaintenanceDerivativeSubmitProof;
+export declare function parseDerivativeStatusResponse(value: unknown, plan: DatasetMaintenancePlan, submit: DatasetMaintenanceDerivativeSubmitProof): DatasetMaintenanceDerivativeStatusProof;
+export declare function derivativeStatusCategory(status: DatasetMaintenanceDerivativeRequestStatus): 'pending' | 'passed' | 'failed';

package/dist/src/lib/dataset-maintenance-flow-identity-approval-claim.d.ts

@@ -0,0 +1,50 @@
+export type FlowIdentityApprovalClaim = {
+    schema_version: 'dataset-flow-identity-local-approval-claim.v1';
+    claimed_at_utc: string;
+    approval_kind: 'initial' | 'recovery';
+    approval_identity_sha256: string;
+    execution_identity_sha256: string;
+    request_id: string;
+    environment: 'production';
+    project_ref: string;
+    actor_user_id: string;
+    actor_email: string;
+    target_visibility: 'owner_draft';
+    user_state_claim: 'authenticated_actor_state_100_plus_own_state_0';
+    plan_sha256: string;
+    freeze_sha256: string;
+    canonical_out_dir: string;
+    maximum_cli_apply_spawns: 1;
+    approval_reusable: false;
+};
+declare function isErrno(error: unknown, code: string): boolean;
+declare function hasPrivateClaimPermissions(mode: number, platform: NodeJS.Platform): boolean;
+declare function rethrowClaimCreateError(error: unknown, claimPath: string): never;
+declare function validateClaim(value: unknown, expectedIdentity: string): FlowIdentityApprovalClaim;
+export declare function resolveFlowIdentityApprovalClaimRoot(options: {
+    env: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    homeDir?: string;
+}): string;
+export declare function flowIdentityApprovalClaimPath(options: {
+    stateRoot: string;
+    approvalIdentitySha256: string;
+}): string;
+/** Strict create-only claim. Existing identical bytes are still consumed. */
+export declare function claimFlowIdentityApproval(options: {
+    claim: FlowIdentityApprovalClaim;
+    env: NodeJS.ProcessEnv;
+    stateRoot?: string;
+}): string;
+export declare function readFlowIdentityApprovalClaim(options: {
+    approvalIdentitySha256: string;
+    env: NodeJS.ProcessEnv;
+    stateRoot?: string;
+}): FlowIdentityApprovalClaim | null;
+export declare const __testInternals: {
+    hasPrivateClaimPermissions: typeof hasPrivateClaimPermissions;
+    isErrno: typeof isErrno;
+    rethrowClaimCreateError: typeof rethrowClaimCreateError;
+    validateClaim: typeof validateClaim;
+};
+export {};

package/dist/src/lib/dataset-maintenance-flow-identity-capture.d.ts

@@ -0,0 +1,110 @@
+import { type ValidationDeps } from './dataset-maintenance-flow-identity-plan.js';
+import { materializePrivateArtifactDirectoryAtomically } from './dataset-maintenance-protected-artifacts.js';
+import { attestMaintenanceFlowIdentityCapture, fetchMaintenanceAccountTableRows, fetchMaintenanceExactRows, resolveMaintenanceRemoteContext } from './dataset-maintenance-remote.js';
+import { type DatasetMaintenanceRemoteRow, type DatasetMaintenanceRowSnapshot, type JsonObject } from './dataset-maintenance-contract.js';
+import type { FetchLike } from './http.js';
+export type FlowIdentityPrerequisites = {
+    schema_version: 'dataset-flow-identity-prerequisites.v2';
+    step2: {
+        readback_sha256: string;
+        completed_at_utc: string;
+        status: 'passed';
+    };
+    issue29_target1: {
+        readback_sha256: string;
+        completed_at_utc: string;
+        status: 'passed';
+    };
+    issue29_target2: {
+        readback_sha256: string;
+        completed_at_utc: string;
+        status: 'passed';
+    };
+};
+export type CaptureFlowIdentityOptions = {
+    policyPath: string;
+    reviewLedgerPath: string;
+    prerequisitesPath: string;
+    toolchainEvidencePath: string;
+    requestId: string;
+    operationId: string;
+    expectedProjectRef: string;
+    confirm: string;
+    cliVersion: string;
+    sdkVersion: string;
+    outDir: string;
+    pageSize?: number;
+    readConcurrency?: number;
+    timeoutMs?: number;
+    env: NodeJS.ProcessEnv;
+    fetchImpl: FetchLike;
+    now?: Date;
+    validation?: Partial<ValidationDeps>;
+};
+export type FlowIdentityCaptureReport = {
+    schema_version: 'dataset-flow-identity-capture-report.v2';
+    generated_at_utc: string;
+    status: 'captured';
+    environment: 'production';
+    project_ref: string;
+    actor: {
+        user_id: string;
+        email: string;
+    };
+    operation_id: string;
+    request_id: string;
+    receipt_id: string;
+    receipt_proof_sha256: string;
+    capture_request_sha256: string;
+    live_capture_evidence_core_sha256: string;
+    capture_artifact_sha256: string;
+    counts: {
+        sources: 305;
+        targets: number;
+        supports: number;
+        owner_draft_processes: number;
+        mappings: number;
+        affected_processes: number;
+        rewrites: number;
+    };
+    calls: {
+        capture_attest: 1;
+        scope_preflight: 0;
+        process_rewrite: 0;
+        scope_finalize: 0;
+        automatic_retry: false;
+    };
+    artifacts: {
+        request: string;
+        attestation: string;
+        live_capture: string;
+        report: string;
+    };
+};
+type CaptureDependencies = {
+    resolveContext: typeof resolveMaintenanceRemoteContext;
+    fetchAccountTableRows: typeof fetchMaintenanceAccountTableRows;
+    fetchExactRows: typeof fetchMaintenanceExactRows;
+    attest: typeof attestMaintenanceFlowIdentityCapture;
+    materialize: typeof materializePrivateArtifactDirectoryAtomically;
+};
+export declare function parseFlowIdentityPrerequisites(value: unknown): FlowIdentityPrerequisites;
+declare function snapshot(row: DatasetMaintenanceRemoteRow): DatasetMaintenanceRowSnapshot;
+declare function flowPropertyClaim(payload: JsonObject): {
+    id: string;
+    version: string;
+};
+declare function unitGroupClaim(payload: JsonObject): {
+    id: string;
+    version: string;
+};
+declare function executeCapture(options: CaptureFlowIdentityOptions, dependencies: CaptureDependencies): Promise<FlowIdentityCaptureReport>;
+export declare function captureFlowIdentity(options: CaptureFlowIdentityOptions): Promise<FlowIdentityCaptureReport>;
+export declare const __testInternals: {
+    executeCapture: typeof executeCapture;
+    flowPropertyClaim: typeof flowPropertyClaim;
+    parseFlowIdentityPrerequisites: typeof parseFlowIdentityPrerequisites;
+    snapshot: typeof snapshot;
+    unitGroupClaim: typeof unitGroupClaim;
+};
+export {};

package/dist/src/lib/dataset-maintenance-flow-identity-command.d.ts

@@ -0,0 +1,15 @@
+import { type RunFlowIdentityPlanOptions } from './dataset-maintenance-flow-identity-plan.js';
+export type RunFlowIdentityPlanFromFilesOptions = {
+    policyPath: string;
+    reviewLedgerPath: string;
+    liveCapturePath: string;
+    outDir: string;
+    now?: Date;
+    validation?: RunFlowIdentityPlanOptions['validation'];
+};
+declare function readCanonical(filePath: string, label: string): unknown;
+export declare function runFlowIdentityPlanFromFiles(options: RunFlowIdentityPlanFromFilesOptions): import("./dataset-maintenance-flow-identity-contract.js").FlowIdentityPlan;
+export declare const __testInternals: {
+    readCanonical: typeof readCanonical;
+};
+export {};