Data maintenance and repair

Maintenance can modify or delete data. Use this reference only with an explicit scope, prepared plan inputs, and operator authorization. New users should start with read-only queries. The filenames and approval placeholders belong to a real maintenance task; they are not ready-to-run tutorial inputs.

This page uses the globally installed tiangong-lca short command; see getting started for installation.

Ordinary maintenance: plan, apply, verify

tiangong-lca dataset maintenance plan/apply/verify is for controlled account-level cleanup, bad import repair, support-data alias merges, and protected process derivative rebuilds. It runs as the currently authenticated user and relies on server-side RLS to limit visible and writable rows; do not treat it as a cross-account admin batch tool.

tiangong-lca dataset maintenance plan --scope ./maintenance-scope.json --operation redo-import --out-dir ./dataset-maintenance --page-size 1000 --timeout-ms 10000 --json
tiangong-lca dataset maintenance plan --scope ./derivative-rebuild-scope.json --operation rebuild-derivatives --out-dir ./derivative-rebuild --json
tiangong-lca dataset maintenance apply --plan ./dataset-maintenance/maintenance-plan.json --commit --approve-plan <sha256> --confirm <current-account-email> --timeout-ms 10000 --json
tiangong-lca dataset maintenance verify --plan ./dataset-maintenance/maintenance-plan.json --out-dir ./dataset-maintenance/verify --page-size 1000 --timeout-ms 10000 --json
tiangong-lca dataset maintenance plan --scope ./alias-scope.json --operation merge-support-aliases --out-dir ./dataset-maintenance --json
tiangong-lca dataset maintenance flow-identity --help

Protected production execution

Use merge-support-aliases only for protected owner-draft support-data alias repair. Ordinary apply is not the fallback for a sealed production execution: build the immutable plan first, use freeze-protected to re-read the exact production scope and generate the approval request, use seal-protected-approval to record byte-exact human approval locally, and use run-protected only to execute or inspect one sealed production run. verify must judge the result from a fresh readback proof instead of trusting only the apply/run report. Preflight timing still follows server-side expiry; the CLI only tolerates a small server-ahead clock skew and does not extend approval or execution validity. Derivative verification bridges database-domain action evidence to the fresh snapshot; do not compare CLI canonical JSON directly with PostgreSQL jsonb::text as though they were the same hash domain.

Flow identity maintenance and recovery

Flow identity maintenance uses the dedicated dataset maintenance flow-identity subworkflow, not another maintenance runner. The usual order is: capture for production read-only census and one database attestation, plan from the compatibility policy, review ledger, and live capture, freeze plus seal-approval to bind the exact execution bytes, run to submit the next durable ordinal serially and finalize only after derivatives are ready, then verify to independently re-read the terminal scope, source rows, public/support rows, affected processes, and owner-draft reference closure. If a response is ambiguous, the wrapper exits without its in-memory permit, or derivatives become ready later, continue only with freeze-recovery, seal-recovery-approval, and run-recovery; do not replay process writes automatically in the same invocation.

Pagination completeness and concurrency

--page-size is the requested maximum, from 1-5000; PostgREST may still return smaller pages because of a server-side cap. The CLI requests Prefer: count=exact, validates the exact total and returned range from each Content-Range, and advances the next offset by the number of rows actually returned. An accepted scan must keep strict id / version ordering, with no missing or duplicate identities, and records each table's requested page size, effective page size, page count, fetched rows, exact total, and aggregate entity counts.

This completeness proof means the CLI traversed the filtered result while table membership and ordering keys stayed stable. Because the read spans multiple HTTP requests, it is not a transaction-level or MVCC snapshot of one instant; avoid concurrent cleanup, deletion, or insertion for the same account while maintenance is running. plan binds the completeness proof into the immutable plan hash, apply reruns the complete account scan and drift checks before accepting approval or writing, and verify uses a fresh complete readback proof instead of trusting only the apply report.

Accepting process derivatives

rebuild-derivatives can target only one exact-version current-user draft process. The scope must declare action: "rebuild_derivatives", target_mode: "owner_draft", the expected current owner, expected state_code: 0, and the full component set extracted_md plus embedding_ft. It rebuilds only derived Markdown and embeddings; it does not change the primary process payload, owner, state, or modified_at, and it cannot target public/shared rows, foreign owners, non-draft rows, other tables, multiple rows, or partial component sets.

When apply runs for rebuild-derivatives, success means only that the guarded database RPC accepted and queued the request. It does not mean Markdown or embedding generation has completed. The CLI has no fallback to a direct Edge call, admin embedding-run, raw queue, SQL, service-role credentials, or raw REST mutation; replaying the same plan must return the same durable request proof. verify reads the durable request plus a fresh process derivative snapshot and reports only pending, passed, or failed. It passes only after both requested derivatives are current and the frozen primary-field preconditions still match; treat pending and failed as non-success states.

Every workflow completes only when fresh readback meets the plan and terminal-state requirements. For scope drift, expired approvals, ambiguous responses, or queued derivatives, preserve evidence and use supported recovery. Do not automatically repeat writes.