@tiangong-lca/cli 0.1.1 → 0.1.2

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

@@ -0,0 +1,268 @@
+import { type FlowIdentityApproval, type FlowIdentityExecutionIdentity, type FlowIdentityFreeze, type FlowIdentityScopeProof, type FlowIdentityScopeStatus } from './dataset-maintenance-flow-identity-execution-contract.js';
+import type { FlowIdentityPlan } from './dataset-maintenance-flow-identity-contract.js';
+import { type JsonObject } from './dataset-maintenance-contract.js';
+import { lookupMaintenanceFlowIdentityScope, readMaintenanceFlowIdentityScope, resolveMaintenanceRemoteContext, type DatasetMaintenanceRemoteContext } from './dataset-maintenance-remote.js';
+import type { FetchLike } from './http.js';
+declare const USER_STATE_CLAIM: 'authenticated_actor_state_100_plus_own_state_0';
+export type FlowIdentityRecoveryReason = 'wrapper_exited_without_permit' | 'process_response_ambiguous' | 'process_domain_rejected' | 'finalize_response_ambiguous' | 'derivatives_became_ready_after_wrapper_exit';
+export type FlowIdentityRecoveryMode = 'resume_and_finalize' | 'finalize_only';
+export type FlowIdentityRecoveryBaseline = {
+    status: FlowIdentityScopeStatus['status'];
+    completed_process_count: number;
+    next_ordinal: number;
+    primary_complete: boolean;
+    primary_current: boolean;
+    live_guard_current: boolean;
+    protected_closure_current: boolean;
+    derivatives_current: boolean;
+    whole_scope_proof_sha256: string;
+};
+export type FlowIdentityRecoveryFreeze = {
+    schema_version: 'dataset-flow-identity-recovery-freeze.v1';
+    generated_at_utc: string;
+    environment: 'production';
+    project_ref: string;
+    actor: {
+        user_id: string;
+        email: string;
+    };
+    target_visibility: 'owner_draft';
+    user_state_claim: typeof USER_STATE_CLAIM;
+    scope_id: string;
+    scope_proof_sha256: string;
+    operation_id: string;
+    plan_sha256: string;
+    original_freeze_sha256: string;
+    original_execution_request_id: string;
+    original_execution_identity_sha256: string;
+    original_execution_approval_request_sha256: string;
+    original_execution_approval_text_sha256: string;
+    original_execution_approval_identity_sha256: string;
+    recovery_reason: FlowIdentityRecoveryReason;
+    recovery_mode: FlowIdentityRecoveryMode;
+    baseline: FlowIdentityRecoveryBaseline;
+    toolchain_evidence_sha256: string;
+    approval_reusable: false;
+    maximum_wrapper_invocations: 1;
+    maximum_cli_apply_spawns: 1;
+    maximum_process_posts: number;
+    maximum_finalize_posts: 1;
+    automatic_retry: false;
+    recovery_freeze_sha256: string;
+};
+export type FlowIdentityRecoveryApprovalRequestCore = {
+    schema_version: 'dataset-flow-identity-recovery-approval-request.v1';
+    approved_at_utc: string;
+    environment: 'production';
+    project_ref: string;
+    actor: {
+        user_id: string;
+        email: string;
+    };
+    target_visibility: 'owner_draft';
+    user_state_claim: typeof USER_STATE_CLAIM;
+    scope_id: string;
+    scope_proof_sha256: string;
+    operation_id: string;
+    plan_sha256: string;
+    original_freeze_sha256: string;
+    original_execution_request_id: string;
+    original_execution_identity_sha256: string;
+    original_execution_approval_request_sha256: string;
+    original_execution_approval_text_sha256: string;
+    original_execution_approval_identity_sha256: string;
+    recovery_reason: FlowIdentityRecoveryReason;
+    recovery_mode: FlowIdentityRecoveryMode;
+    baseline: FlowIdentityRecoveryBaseline;
+    recovery_freeze_file_sha256: string;
+    recovery_freeze_sha256: string;
+    toolchain_evidence_sha256: string;
+    approval_reusable: false;
+    maximum_wrapper_invocations: 1;
+    maximum_cli_apply_spawns: 1;
+    maximum_process_posts: number;
+    maximum_finalize_posts: 1;
+    automatic_retry: false;
+};
+export type FlowIdentityRecoveryApprovalRequest = FlowIdentityRecoveryApprovalRequestCore & {
+    request_sha256: string;
+};
+export type FlowIdentityRecoveryApproval = {
+    schema_version: 'dataset-flow-identity-recovery-approval.v1';
+    approved_at_utc: string;
+    actor: {
+        user_id: string;
+        email: string;
+    };
+    plan_sha256: string;
+    scope_id: string;
+    scope_proof_sha256: string;
+    recovery_freeze_sha256: string;
+    toolchain_evidence_sha256: string;
+    recovery_approval_request_sha256: string;
+    recovery_approval_text_sha256: string;
+    recovery_approval_identity_sha256: string;
+};
+export type FreezeFlowIdentityRecoveryOptions = {
+    planPath: string;
+    freezePath: string;
+    approvalPath: string;
+    runDir: string;
+    toolchainEvidencePath: string;
+    expectedProjectRef: string;
+    confirm: string;
+    approvedAtUtc: string;
+    recoveryReason: FlowIdentityRecoveryReason;
+    cliVersion: string;
+    outDir: string;
+    env: NodeJS.ProcessEnv;
+    fetchImpl: FetchLike;
+    timeoutMs?: number;
+    now?: Date;
+    dependencies?: {
+        resolveContext: typeof resolveMaintenanceRemoteContext;
+        lookup: typeof lookupMaintenanceFlowIdentityScope;
+        read: typeof readMaintenanceFlowIdentityScope;
+    };
+};
+export type FlowIdentityRecoveryFreezeReport = {
+    schema_version: 'dataset-flow-identity-recovery-freeze-report.v1';
+    generated_at_utc: string;
+    status: 'frozen';
+    execution_submitted: false;
+    network_calls: 2 | 3;
+    database_calls: 1 | 2;
+    scope_id: string;
+    plan_sha256: string;
+    recovery_freeze_sha256: string;
+    recovery_freeze_file_sha256: string;
+    recovery_approval_request_sha256: string;
+    recovery_approval_text_sha256: string;
+    artifacts: {
+        freeze: string;
+        scope_proof: string;
+        approval_request: string;
+        approval_text: string;
+        report: string;
+    };
+};
+export type SealFlowIdentityRecoveryApprovalOptions = {
+    recoveryFreezePath: string;
+    approvalRequestPath: string;
+    humanApprovalPath: string;
+    approveFreezeFile: string;
+    approveRequest: string;
+    approveText: string;
+    confirm: string;
+    approvedAtUtc: string;
+    outDir: string;
+    now?: Date;
+};
+export type FlowIdentityRecoveryApprovalSealReport = {
+    schema_version: 'dataset-flow-identity-recovery-approval-seal-report.v1';
+    generated_at_utc: string;
+    status: 'sealed';
+    execution_submitted: false;
+    network_calls: 0;
+    database_calls: 0;
+    scope_id: string;
+    plan_sha256: string;
+    recovery_freeze_sha256: string;
+    recovery_approval_request_sha256: string;
+    recovery_approval_text_sha256: string;
+    recovery_approval_identity_sha256: string;
+    artifacts: {
+        human_approval: string;
+        approval: string;
+        report: string;
+    };
+};
+export type PreparedFlowIdentityRecoveryExecution = {
+    plan: FlowIdentityPlan;
+    originalFreeze: FlowIdentityFreeze;
+    originalApproval: FlowIdentityApproval;
+    originalIdentity: FlowIdentityExecutionIdentity;
+    scope: FlowIdentityScopeProof;
+    recoveryFreeze: FlowIdentityRecoveryFreeze;
+    recoveryApproval: FlowIdentityRecoveryApproval;
+    recoveryRequest: JsonObject;
+};
+/** Sanitized proof returned by the recovery admission RPC after the permit is removed. */
+export type FlowIdentityRecoveryProof = {
+    ok: true;
+    command: 'cmd_dataset_flow_identity_scope_recover_guarded';
+    schema_version: 'dataset-flow-identity-scope-recovery-result.v1';
+    scope_id: string;
+    scope_proof_sha256: string;
+    status: FlowIdentityRecoveryBaseline['status'];
+    completed_process_count: number;
+    next_ordinal: number;
+    whole_scope_proof_sha256: string;
+    recovery_wire_request_sha256: string;
+    recovery_approval_identity_sha256: string;
+    invocation_id: string;
+    audit_id: string;
+    replay: boolean;
+};
+export declare const FLOW_IDENTITY_RECOVERY_FREEZE_ARTIFACTS: {
+    readonly freeze: 'flow-identity-recovery-freeze.json';
+    readonly scope_proof: 'flow-identity-recovery-scope-proof.json';
+    readonly approval_request: 'flow-identity-recovery-approval-request.json';
+    readonly approval_text: 'flow-identity-recovery-approval-request.txt';
+    readonly report: 'flow-identity-recovery-freeze-report.json';
+};
+export declare const FLOW_IDENTITY_RECOVERY_APPROVAL_ARTIFACTS: {
+    readonly human_approval: 'flow-identity-recovery-human-approval.txt';
+    readonly approval: 'flow-identity-recovery-approval.json';
+    readonly report: 'flow-identity-recovery-approval-seal-report.json';
+};
+declare function canonicalTimestamp(value: string, label: string): string;
+declare function readRecoveryScopeProof(options: {
+    runDir: string;
+    plan: FlowIdentityPlan;
+    identity: FlowIdentityExecutionIdentity;
+}): FlowIdentityScopeProof | null;
+declare function recoveryBaseline(status: FlowIdentityScopeStatus): FlowIdentityRecoveryBaseline;
+export declare function computeFlowIdentityRecoveryFreezeSha256(freeze: FlowIdentityRecoveryFreeze): string;
+declare function recoveryRequestCore(value: FlowIdentityRecoveryApprovalRequest): FlowIdentityRecoveryApprovalRequestCore;
+export declare function computeFlowIdentityRecoveryApprovalRequestSha256(request: FlowIdentityRecoveryApprovalRequest): string;
+export declare function computeFlowIdentityRecoveryApprovalIdentitySha256(approval: FlowIdentityRecoveryApproval): string;
+export declare function renderFlowIdentityRecoveryApprovalText(core: FlowIdentityRecoveryApprovalRequestCore, requestSha256: string): string;
+export declare function parseFlowIdentityRecoveryFreeze(value: unknown): FlowIdentityRecoveryFreeze;
+export declare function parseFlowIdentityRecoveryApprovalRequest(value: unknown): FlowIdentityRecoveryApprovalRequest;
+export declare function parseFlowIdentityRecoveryApproval(value: unknown, freeze: FlowIdentityRecoveryFreeze): FlowIdentityRecoveryApproval;
+declare function assertContext(plan: FlowIdentityPlan, context: DatasetMaintenanceRemoteContext): void;
+declare function assertRecoverableStatus(status: FlowIdentityScopeStatus, plan: FlowIdentityPlan): void;
+export declare function freezeFlowIdentityRecovery(options: FreezeFlowIdentityRecoveryOptions): Promise<FlowIdentityRecoveryFreezeReport>;
+export declare function sealFlowIdentityRecoveryApproval(options: SealFlowIdentityRecoveryApprovalOptions): FlowIdentityRecoveryApprovalSealReport;
+declare function deterministicUuidFromSha256(digest: string): string;
+export declare function buildFlowIdentityRecoveryRequest(options: {
+    freeze: FlowIdentityRecoveryFreeze;
+    approval: FlowIdentityRecoveryApproval;
+}): JsonObject;
+export declare function parseFlowIdentityRecoveryProof(options: {
+    value: unknown;
+    freeze: FlowIdentityRecoveryFreeze;
+    approval: FlowIdentityRecoveryApproval;
+    request: JsonObject;
+    expectedInvocationId?: string;
+}): FlowIdentityRecoveryProof;
+export declare function prepareFlowIdentityRecoveryExecution(options: {
+    plan: unknown;
+    originalFreeze: unknown;
+    originalApproval: unknown;
+    scope: unknown;
+    recoveryFreeze: unknown;
+    recoveryApproval: unknown;
+}): PreparedFlowIdentityRecoveryExecution;
+export declare function assertFreshRecoveryBaseline(status: FlowIdentityScopeStatus, freeze: FlowIdentityRecoveryFreeze): void;
+export declare const __testInternals: {
+    assertContext: typeof assertContext;
+    assertRecoverableStatus: typeof assertRecoverableStatus;
+    canonicalTimestamp: typeof canonicalTimestamp;
+    deterministicUuidFromSha256: typeof deterministicUuidFromSha256;
+    readRecoveryScopeProof: typeof readRecoveryScopeProof;
+    recoveryBaseline: typeof recoveryBaseline;
+    recoveryRequestCore: typeof recoveryRequestCore;
+};
+export {};

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

@@ -0,0 +1,123 @@
+import { prepareFlowIdentityExecution, type FlowIdentityScopeProof, type FlowIdentityScopeStatus } from './dataset-maintenance-flow-identity-execution-contract.js';
+import { type PreparedFlowIdentityRecoveryExecution } from './dataset-maintenance-flow-identity-recovery.js';
+import type { FlowIdentityPlan, FlowIdentityProcessTemplate } from './dataset-maintenance-flow-identity-contract.js';
+import { finalizeMaintenanceFlowIdentityScope, lookupMaintenanceFlowIdentityScope, preflightMaintenanceFlowIdentityScope, recoverMaintenanceFlowIdentityScope, readMaintenanceFlowIdentityScope, resolveMaintenanceRemoteContext, rewriteMaintenanceFlowIdentityProcess, type DatasetMaintenanceRemoteContext } from './dataset-maintenance-remote.js';
+import type { FetchLike } from './http.js';
+import { type FlowIdentityApprovalClaim } from './dataset-maintenance-flow-identity-approval-claim.js';
+export type FlowIdentityRunStatus = 'passed' | 'pending' | 'blocked' | 'failed' | 'indeterminate';
+export type RunFlowIdentityOptions = {
+    planPath: string;
+    freezePath: string;
+    approvalPath: string;
+    recoveryFreezePath?: string;
+    recoveryApprovalPath?: string;
+    recoveryRunDir?: string;
+    outDir: string;
+    commit: boolean;
+    statusOnly: boolean;
+    approveExecution?: string;
+    confirm?: string;
+    waitSeconds?: number;
+    pollMs?: number;
+    timeoutMs?: number;
+    env: NodeJS.ProcessEnv;
+    fetchImpl: FetchLike;
+    now?: Date;
+    sleep?: (ms: number) => Promise<void>;
+};
+export type FlowIdentityRunReport = {
+    schema_version: 'dataset-flow-identity-run-report.v2';
+    generated_at_utc: string;
+    mode: 'commit' | 'status_only';
+    status: FlowIdentityRunStatus;
+    operation_id: string;
+    plan_sha256: string;
+    request_id: string;
+    identity_sha256: string;
+    scope_id: string | null;
+    database_status: FlowIdentityScopeStatus['status'] | null;
+    process_count: number;
+    completed_process_count: number;
+    next_ordinal: number | null;
+    automatic_retry: false;
+    issues: Array<{
+        code: string;
+        message: string;
+        details?: unknown;
+    }>;
+};
+type ProcessTemplate = Pick<FlowIdentityProcessTemplate, 'process' | 'rewrites' | 'collision_ledger'>;
+type PreparedRun = ReturnType<typeof prepareFlowIdentityExecution> & {
+    planPath: string;
+    outDir: string;
+    templates: ProcessTemplate[];
+    recovery: PreparedFlowIdentityRecoveryExecution | null;
+    approvalClaim: FlowIdentityApprovalClaim | null;
+};
+type RunDependencies = {
+    resolveContext: typeof resolveMaintenanceRemoteContext;
+    preflight: typeof preflightMaintenanceFlowIdentityScope;
+    lookup?: typeof lookupMaintenanceFlowIdentityScope;
+    recover?: typeof recoverMaintenanceFlowIdentityScope;
+    rewrite: typeof rewriteMaintenanceFlowIdentityProcess;
+    read: typeof readMaintenanceFlowIdentityScope;
+    finalize: typeof finalizeMaintenanceFlowIdentityScope;
+    sleep: (ms: number) => Promise<void>;
+    now: () => Date;
+    claimApproval?: (options: {
+        claim: FlowIdentityApprovalClaim;
+        env: NodeJS.ProcessEnv;
+    }) => string;
+};
+declare function errorDetails(error: unknown): {
+    name: string;
+    message: string;
+    code: string | null;
+};
+declare function readCanonicalJson(filePath: string, label: string): unknown;
+declare function processStem(ordinal: number, id: string, version: string): string;
+declare function loadProcessTemplates(planPath: string, plan: FlowIdentityPlan): ProcessTemplate[];
+declare function prepareRun(options: RunFlowIdentityOptions): PreparedRun;
+declare function assertContext(prepared: PreparedRun, context: DatasetMaintenanceRemoteContext): void;
+declare function numberedArtifact(directory: string, prefix: string): string;
+declare function validateCompletedRequests(prepared: PreparedRun, status: FlowIdentityScopeStatus): void;
+declare function requirePendingProcess(prepared: PreparedRun, status: FlowIdentityScopeStatus, ordinal: number): {
+    ledger: FlowIdentityScopeStatus['processes'][number];
+    template: ProcessTemplate;
+};
+declare function report(options: {
+    prepared: PreparedRun;
+    mode: 'commit' | 'status_only';
+    status: FlowIdentityRunStatus;
+    scope: FlowIdentityScopeProof | null;
+    database: FlowIdentityScopeStatus | null;
+    issues?: FlowIdentityRunReport['issues'];
+    now: Date;
+}): FlowIdentityRunReport;
+declare function completedRunStatus(status: FlowIdentityScopeStatus): 'passed' | 'blocked';
+declare function waitForFinalizeDecision(options: {
+    command: RunFlowIdentityOptions;
+    prepared: PreparedRun;
+    context: DatasetMaintenanceRemoteContext;
+    scope: FlowIdentityScopeProof;
+    initial: FlowIdentityScopeStatus;
+    dependencies: RunDependencies;
+}): Promise<FlowIdentityScopeStatus>;
+declare function executeRun(command: RunFlowIdentityOptions, dependencies: RunDependencies, preparedInput?: PreparedRun): Promise<FlowIdentityRunReport>;
+export declare function runFlowIdentity(options: RunFlowIdentityOptions): Promise<FlowIdentityRunReport>;
+export declare const __testInternals: {
+    assertContext: typeof assertContext;
+    completedRunStatus: typeof completedRunStatus;
+    errorDetails: typeof errorDetails;
+    executeRun: typeof executeRun;
+    loadProcessTemplates: typeof loadProcessTemplates;
+    numberedArtifact: typeof numberedArtifact;
+    prepareRun: typeof prepareRun;
+    processStem: typeof processStem;
+    readCanonicalJson: typeof readCanonicalJson;
+    requirePendingProcess: typeof requirePendingProcess;
+    report: typeof report;
+    validateCompletedRequests: typeof validateCompletedRequests;
+    waitForFinalizeDecision: typeof waitForFinalizeDecision;
+};
+export {};

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

@@ -0,0 +1,50 @@
+export type SealFlowIdentityApprovalOptions = {
+    planPath: string;
+    freezePath: string;
+    approvalRequestPath: string;
+    humanApprovalPath: string;
+    approveFreezeFile: string;
+    approveRequest: string;
+    approveText: string;
+    confirm: string;
+    approvedAtUtc: string;
+    outDir: string;
+    now?: Date;
+};
+export type FlowIdentityApprovalSealReport = {
+    schema_version: 'dataset-flow-identity-execution-approval-seal-report.v2';
+    generated_at_utc: string;
+    approval_authority_at_utc: string;
+    status: 'sealed';
+    execution_submitted: false;
+    network_calls: 0;
+    database_calls: 0;
+    plan_sha256: string;
+    operation_id: string;
+    freeze_file_sha256: string;
+    freeze_sha256: string;
+    policy_approval_text_sha256: string;
+    execution_approval_request_sha256: string;
+    execution_approval_text_sha256: string;
+    execution_approval_identity_sha256: string;
+    artifacts: {
+        human_approval: string;
+        approval: string;
+        report: string;
+    };
+};
+export declare const FLOW_IDENTITY_APPROVAL_ARTIFACTS: {
+    readonly human_approval: 'flow-identity-execution-human-approval.txt';
+    readonly approval: 'flow-identity-execution-approval.json';
+    readonly report: 'flow-identity-execution-approval-seal-report.json';
+};
+declare function requireHash(value: string, label: string): void;
+declare function requireDistinctApprovalHashDomains(hashes: readonly string[]): void;
+declare function requireCanonicalJson(filePath: string, label: string): import("./dataset-maintenance-protected-artifacts.js").ProtectedJsonArtifact;
+export declare function sealFlowIdentityApproval(options: SealFlowIdentityApprovalOptions): FlowIdentityApprovalSealReport;
+export declare const __testInternals: {
+    requireCanonicalJson: typeof requireCanonicalJson;
+    requireDistinctApprovalHashDomains: typeof requireDistinctApprovalHashDomains;
+    requireHash: typeof requireHash;
+};
+export {};

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

@@ -0,0 +1,85 @@
+import { type FlowIdentityScopeStatus } from './dataset-maintenance-flow-identity-execution-contract.js';
+import { type FlowIdentityLiveCapture, type FlowIdentityOccurrence, type FlowIdentityPlan } from './dataset-maintenance-flow-identity-contract.js';
+import { type DatasetMaintenanceRemoteRow, type DatasetMaintenanceRowSnapshot, type JsonObject } from './dataset-maintenance-contract.js';
+import type { FetchLike } from './http.js';
+export type VerifyFlowIdentityOptions = {
+    planPath: string;
+    freezePath: string;
+    approvalPath: string;
+    runDir: string;
+    outDir: string;
+    pageSize?: number;
+    timeoutMs?: number;
+    env: NodeJS.ProcessEnv;
+    fetchImpl: FetchLike;
+    now?: Date;
+};
+export type FlowIdentityVerificationIssue = {
+    code: string;
+    message: string;
+    details?: unknown;
+};
+export type FlowIdentityVerificationReport = {
+    schema_version: 'dataset-flow-identity-verification-report.v1';
+    generated_at_utc: string;
+    status: 'passed' | 'pending' | 'failed';
+    plan_sha256: string;
+    operation_id: string;
+    scope_id: string;
+    database_status: FlowIdentityScopeStatus['status'];
+    terminal_proof_sha256: string | null;
+    checks: {
+        source_rows_unchanged: boolean;
+        public_target_rows_unchanged: boolean;
+        support_rows_unchanged: boolean;
+        affected_processes_exact: boolean;
+        approved_source_reference_residue: number;
+        protected_closure_exact: boolean;
+        complete_owner_draft_process_scan: boolean;
+        derivatives_causally_terminal: boolean;
+    };
+    counts: {
+        source_rows: number;
+        public_target_rows: number;
+        support_rows: number;
+        affected_processes: number;
+        owner_draft_processes_scanned: number;
+    };
+    issues: FlowIdentityVerificationIssue[];
+};
+type ReadbackInput = {
+    plan: FlowIdentityPlan;
+    capture: FlowIdentityLiveCapture;
+    status: FlowIdentityScopeStatus;
+    currentStableRows: DatasetMaintenanceRemoteRow[];
+    currentOwnerDraftProcesses: DatasetMaintenanceRemoteRow[];
+    processScanComplete: boolean;
+};
+declare function rowKey(table: string, id: string, version: string, userId: string | null): string;
+declare function snapshotKey(row: DatasetMaintenanceRowSnapshot): string;
+declare function currentKey(row: DatasetMaintenanceRemoteRow): string;
+declare function snapshotWithoutJson(row: DatasetMaintenanceRemoteRow): DatasetMaintenanceRowSnapshot;
+declare function jsonColumnsMatch(row: DatasetMaintenanceRemoteRow): boolean;
+declare function processExchanges(payload: JsonObject | null): JsonObject[] | null;
+declare function buildOccurrenceIndex(rows: DatasetMaintenanceRemoteRow[], issues: FlowIdentityVerificationIssue[]): Map<string, FlowIdentityOccurrence[]>;
+declare function compareStableRows(options: {
+    expected: DatasetMaintenanceRowSnapshot[];
+    currentByKey: Map<string, DatasetMaintenanceRemoteRow>;
+    code: string;
+    issues: FlowIdentityVerificationIssue[];
+}): boolean;
+declare function derivativeSetIsCausallyTerminal(input: ReadbackInput): boolean;
+export declare function verifyFlowIdentityReadback(input: ReadbackInput): FlowIdentityVerificationReport;
+export declare function verifyFlowIdentity(options: VerifyFlowIdentityOptions): Promise<FlowIdentityVerificationReport>;
+export declare const __testInternals: {
+    buildOccurrenceIndex: typeof buildOccurrenceIndex;
+    compareStableRows: typeof compareStableRows;
+    currentKey: typeof currentKey;
+    derivativeSetIsCausallyTerminal: typeof derivativeSetIsCausallyTerminal;
+    processExchanges: typeof processExchanges;
+    jsonColumnsMatch: typeof jsonColumnsMatch;
+    rowKey: typeof rowKey;
+    snapshotKey: typeof snapshotKey;
+    snapshotWithoutJson: typeof snapshotWithoutJson;
+};
+export {};

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

@@ -0,0 +1,32 @@
+import { type JsonObject } from './dataset-maintenance-contract.js';
+export type StandardStMultiLang = string | {
+    '@xml:lang': string;
+    '#text': string;
+} | Array<{
+    '@xml:lang': string;
+    '#text': string;
+}>;
+declare function assertTransportString(value: string, path: string): void;
+declare function isExactStMultiLangEntry(value: unknown): value is {
+    '@xml:lang': string;
+    '#text': string;
+};
+export declare function isStandardFlowIdentityShortDescription(value: unknown): value is StandardStMultiLang;
+export declare function assertFlowIdentityWireJson(value: unknown, label?: string): JsonObject;
+export declare function assertFlowIdentityWireValue(value: unknown, label?: string): unknown;
+declare function arrayIndex(key: string): number | null;
+declare function compareCanonicalKeys(left: string, right: string): number;
+declare function canonicalRestrictedJson(value: unknown): string;
+export declare function flowIdentityRestrictedJsonText(value: unknown): string;
+export declare function flowIdentityRestrictedSha256(value: unknown): string;
+export declare const __testInternals: {
+    MAX_COUNT: number;
+    MAX_INDEX: number;
+    MAX_ORDINAL: number;
+    isExactStMultiLangEntry: typeof isExactStMultiLangEntry;
+    arrayIndex: typeof arrayIndex;
+    compareCanonicalKeys: typeof compareCanonicalKeys;
+    canonicalRestrictedJson: typeof canonicalRestrictedJson;
+    assertTransportString: typeof assertTransportString;
+};
+export {};

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

@@ -0,0 +1,58 @@
+export type DatasetMaintenanceTableCompleteness = {
+    status: 'complete';
+    complete: true;
+    strategy: 'postgrest_exact_count';
+    requested_page_size: number;
+    effective_page_size: number;
+    pages_fetched: number;
+    rows_fetched: number;
+    exact_total: number;
+    termination_reason: 'content_range_total_reached';
+    content_range_verified: true;
+    ordering_verified: true;
+    duplicate_count: 0;
+};
+export type DatasetMaintenanceSnapshotCompleteness<Table extends string = string> = {
+    status: 'complete';
+    complete: true;
+    strategy: 'postgrest_exact_count_multi_request';
+    requested_page_size: number;
+    page_count: number;
+    row_count: number;
+    entity_counts: Record<Table, number>;
+    tables: Array<{
+        table: Table;
+    } & DatasetMaintenanceTableCompleteness>;
+};
+export type DatasetMaintenancePage<T> = {
+    rows: T[];
+    source_url: string;
+    content_range: string | null;
+};
+type ParsedContentRange = {
+    start: number | null;
+    end: number | null;
+    total: number;
+};
+export declare function isDatasetMaintenanceSnapshotCompleteness<Table extends string>(value: unknown, expectedTables: readonly Table[]): value is DatasetMaintenanceSnapshotCompleteness<Table>;
+export declare function isSnapshotCompletenessCompatible<Table extends string>(value: unknown, baseline: DatasetMaintenanceSnapshotCompleteness<Table> | undefined, expectedTables: readonly Table[]): boolean;
+export declare function parseExactContentRange(value: string | null, details?: Record<string, unknown>): ParsedContentRange;
+export declare function fetchCompletePostgrestPages<T>(options: {
+    table: string;
+    requestedPageSize: number;
+    fetchPage: (offset: number) => Promise<DatasetMaintenancePage<T>>;
+    rowIdentity: (row: T) => string | null;
+}): Promise<{
+    rows: T[];
+    source_urls: string[];
+    completeness: DatasetMaintenanceTableCompleteness;
+}>;
+export declare function buildSnapshotCompleteness<Table extends string>(options: {
+    tables: readonly Table[];
+    requestedPageSize: number;
+    results: Array<{
+        table: Table;
+        completeness: DatasetMaintenanceTableCompleteness;
+    }>;
+}): DatasetMaintenanceSnapshotCompleteness<Table>;
+export {};

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

@@ -0,0 +1,40 @@
+import { type DatasetMaintenanceAliasSchemas } from './dataset-maintenance-alias-rewrite.js';
+import type { FetchLike } from './http.js';
+import { type DatasetMaintenanceOperation, type DatasetMaintenancePlan, type DatasetMaintenancePlanAction, type DatasetMaintenanceProtectedRow, type DatasetMaintenanceReferenceImpact, type DatasetMaintenanceRemoteRow, type DatasetMaintenanceRowSnapshot, type DatasetMaintenanceScopeAction, type JsonObject } from './dataset-maintenance-contract.js';
+import { maintenancePayloadIdentity, type DatasetMaintenanceSupportSchemas } from './dataset-maintenance-support-validation.js';
+export type RunDatasetMaintenancePlanOptions = {
+    scopePath: string;
+    operation: DatasetMaintenanceOperation;
+    outDir: string;
+    pageSize?: number;
+    timeoutMs?: number;
+    env: NodeJS.ProcessEnv;
+    fetchImpl: FetchLike;
+    now?: Date;
+    supportSchemas?: DatasetMaintenanceSupportSchemas;
+    aliasSchemas?: DatasetMaintenanceAliasSchemas;
+};
+declare function referenceImpacts(options: {
+    rows: DatasetMaintenanceRemoteRow[];
+    deletes: DatasetMaintenanceScopeAction[];
+    phase: DatasetMaintenanceReferenceImpact['phase'];
+}): DatasetMaintenanceReferenceImpact[];
+declare function projectedRows(options: {
+    current: DatasetMaintenanceRemoteRow[];
+    actions: DatasetMaintenancePlanAction[];
+    desiredPayloads: Map<string, JsonObject>;
+}): DatasetMaintenanceRemoteRow[];
+export declare function maintenanceProjectedReferenceFingerprint(rows: DatasetMaintenanceRemoteRow[]): unknown[];
+declare function protectedRows(options: {
+    snapshot: DatasetMaintenanceRowSnapshot[];
+    actions: DatasetMaintenancePlanAction[];
+}): DatasetMaintenanceProtectedRow[];
+export declare function runDatasetMaintenancePlan(options: RunDatasetMaintenancePlanOptions): Promise<DatasetMaintenancePlan>;
+export declare const __testInternals: {
+    desiredPayloadIdentity: typeof maintenancePayloadIdentity;
+    maintenanceProjectedReferenceFingerprint: typeof maintenanceProjectedReferenceFingerprint;
+    projectedRows: typeof projectedRows;
+    protectedRows: typeof protectedRows;
+    referenceImpacts: typeof referenceImpacts;
+};
+export {};

package/dist/src/lib/dataset-maintenance-protected-artifacts.d.ts

@@ -0,0 +1,16 @@
+export type ProtectedJsonArtifact = {
+    resolved: string;
+    value: unknown;
+    text: string;
+    file_sha256: string;
+};
+export type ProtectedTextArtifact = Omit<ProtectedJsonArtifact, 'value'>;
+export declare function readProtectedTextArtifact(filePath: string): ProtectedTextArtifact;
+export declare function readProtectedJsonArtifact(options: {
+    filePath: string;
+    label: string;
+}): ProtectedJsonArtifact;
+export declare function ensurePrivateArtifactDirectory(directory: string): string;
+export declare function materializePrivateArtifactDirectoryAtomically<T>(directory: string, materialize: (stagingDirectory: string) => T): T;
+export declare function writePrivateImmutableText(filePath: string, text: string): string;
+export declare function writePrivateImmutableJson(filePath: string, value: unknown): string;