@cbartens/bkit 6.1.0 → 6.2.0
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.
- package/.bkit/README.md +14 -12
- package/.bkit/core/.agents/docs.md +1 -11
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +30 -9
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +25 -27
- package/.bkit/core/.agents/rules.md +22 -9
- package/.bkit/core/.bkit/README.md +13 -11
- package/.bkit/core/.bkit/authoring.md +58 -13
- package/.bkit/core/.bkit/cli.md +43 -33
- package/.bkit/core/.bkit/cloud.md +93 -30
- package/.bkit/core/.bkit/install.md +55 -16
- package/.bkit/core/.bkit/jsonl.md +24 -7
- package/.bkit/core/.bkit/pipeline.md +8 -8
- package/.bkit/core/.bkit/prompts.md +160 -43
- package/.bkit/core/.bkit/providers.md +99 -36
- package/.bkit/core/.bkit/templates.md +167 -37
- package/.bkit/core/.bkit/trackers.md +39 -6
- package/.bkit/core/.bkit/workflows.md +344 -136
- package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +50 -27
- package/.bkit/core/.claude/hooks/bkit-preflight.sh +11 -11
- package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +13 -8
- package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +14 -25
- package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +20 -9
- package/.bkit/core/.cursor/hooks/bkit-preflight.sh +8 -8
- package/.bkit/core/.opencode/plugin/bkit-gateguard.js +14 -4
- package/.bkit/core/.opencode/plugin/bkit-guardrails.js +114 -0
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +30 -6
- package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-cost.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-database.md +3 -3
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +3 -3
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +32 -2
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -3
- package/.bkit/core/docs/templates/bkit-audit-issues.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-llm.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-logs.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-models.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-security.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-testing.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
- package/.bkit/core/docs/templates/bkit-plan.md +38 -8
- package/.bkit/core/engine/checks/after/auth.ts +118 -47
- package/.bkit/core/engine/checks/after/github.ts +161 -37
- package/.bkit/core/engine/checks/after/index.ts +18 -3
- package/.bkit/core/engine/checks/after/tools.ts +245 -1
- package/.bkit/core/engine/checks/before/files.ts +59 -1
- package/.bkit/core/engine/checks/before/index.ts +8 -0
- package/.bkit/core/engine/checks/status-holes.ts +20 -26
- package/.bkit/core/engine/checks/tips/catalogue.ts +107 -10
- package/.bkit/core/engine/checks/tips/detect.ts +36 -3
- package/.bkit/core/engine/checks/tips/index.ts +1 -1
- package/.bkit/core/engine/cli.ts +13 -13
- package/.bkit/core/engine/commands/ci/ci.ts +124 -19
- package/.bkit/core/engine/commands/ci/push-gate.ts +101 -43
- package/.bkit/core/engine/commands/install/doctor.ts +5 -5
- package/.bkit/core/engine/commands/install/install.ts +28 -25
- package/.bkit/core/engine/commands/install/uninstall.ts +42 -30
- package/.bkit/core/engine/commands/install/upgrade.ts +14 -2
- package/.bkit/core/engine/commands/land.ts +2 -3
- package/.bkit/core/engine/commands/lib.ts +394 -39
- package/.bkit/core/engine/commands/registry.ts +1 -1
- package/.bkit/core/engine/commands/workflow/branches.ts +351 -78
- package/.bkit/core/engine/commands/workflow/challenge.ts +63 -14
- package/.bkit/core/engine/commands/workflow/context.ts +71 -10
- package/.bkit/core/engine/commands/workflow/counters.ts +298 -23
- package/.bkit/core/engine/commands/workflow/decisions.ts +260 -125
- package/.bkit/core/engine/commands/workflow/disk.ts +2 -1
- package/.bkit/core/engine/commands/workflow/feature-base.ts +66 -0
- package/.bkit/core/engine/commands/workflow/issues.ts +312 -17
- package/.bkit/core/engine/commands/workflow/junit.ts +204 -0
- package/.bkit/core/engine/commands/workflow/ledgers.ts +904 -99
- package/.bkit/core/engine/commands/workflow/locks.ts +186 -29
- package/.bkit/core/engine/commands/workflow/loops.ts +87 -0
- package/.bkit/core/engine/commands/workflow/open-decision.ts +251 -0
- package/.bkit/core/engine/commands/workflow/plan-blocks.ts +8 -0
- package/.bkit/core/engine/commands/workflow/plans.ts +1 -1
- package/.bkit/core/engine/commands/workflow/prs.ts +311 -16
- package/.bkit/core/engine/commands/workflow/repo.ts +1 -1
- package/.bkit/core/engine/commands/workflow/run-facts.ts +6 -0
- package/.bkit/core/engine/commands/workflow/runs.ts +877 -174
- package/.bkit/core/engine/commands/workflow/runtime.ts +12 -4
- package/.bkit/core/engine/commands/workflow/status.ts +324 -11
- package/.bkit/core/engine/commands/workflow/step-table.ts +41 -15
- package/.bkit/core/engine/commands/workflow/steps.ts +604 -29
- package/.bkit/core/engine/commands/workflow/summary-findings.ts +1 -1
- package/.bkit/core/engine/commands/workflow/summary.ts +314 -8
- package/.bkit/core/engine/commands/workflow/tasks.ts +400 -27
- package/.bkit/core/engine/commands/workflow/tests-base.ts +319 -0
- package/.bkit/core/engine/commands/workflow/tests-changed.ts +138 -74
- package/.bkit/core/engine/commands/workflow/tests-jump.ts +93 -0
- package/.bkit/core/engine/commands/workflow/tests.ts +815 -182
- package/.bkit/core/engine/commands/workflow/tracker.ts +1134 -137
- package/.bkit/core/engine/commands/workflow/workflows.ts +100 -72
- package/.bkit/core/engine/commands/workflow/worktrees.ts +421 -57
- package/.bkit/core/engine/install/cloud-env.ts +38 -10
- package/.bkit/core/engine/install/managed-block.ts +105 -0
- package/.bkit/core/engine/install/manifest.ts +7 -1
- package/.bkit/core/engine/install/modules/claude.ts +6 -2
- package/.bkit/core/engine/install/modules/cloud.ts +84 -95
- package/.bkit/core/engine/install/modules/codex.ts +10 -2
- package/.bkit/core/engine/install/modules/core.ts +202 -26
- package/.bkit/core/engine/install/modules/opencode.ts +18 -23
- package/.bkit/core/engine/install/network-allowlist.ts +8 -3
- package/.bkit/core/engine/install/project-docs.ts +650 -0
- package/.bkit/core/engine/install/template-copies.ts +58 -5
- package/.bkit/core/engine/install/write.ts +128 -7
- package/.bkit/core/engine/ledgers/journal.ts +18 -10
- package/.bkit/core/engine/ledgers/migrate.ts +20 -8
- package/.bkit/core/engine/ledgers/status.ts +604 -8
- package/.bkit/core/engine/ledgers/telemetry.ts +115 -13
- package/.bkit/core/engine/render/trackers.ts +46 -11
- package/.bkit/core/engine/shared/package-manager.ts +7 -3
- package/.bkit/core/engine/shared/settings.ts +12 -1
- package/.bkit/core/engine/shared/text.ts +14 -0
- package/.bkit/core/engine/tools/instructions-sources.ts +1 -0
- package/.bkit/core/engine/tools/instructions.ts +116 -20
- package/.bkit/core/hooks/antigravity-hook.js +20 -4
- package/.bkit/core/hooks/gateguard-edit-payload.js +8 -5
- package/.bkit/core/hooks/gateguard-engine.js +249 -23
- package/.bkit/core/hooks/guardrails-deny.js +167 -0
- package/.bkit/core/hooks/guardrails-read.js +3 -3
- package/.bkit/core/hooks/guardrails-shell.js +1122 -167
- package/.bkit/core/hooks/guardrails-tiers.js +247 -176
- package/.bkit/core/hooks/preflight-tracker.sh +219 -0
- package/.bkit/core/prompts/bkit-audit-generate.md +23 -6
- package/.bkit/core/prompts/bkit-build-challenge-1.md +5 -4
- package/.bkit/core/prompts/bkit-build-challenge-2.md +6 -5
- package/.bkit/core/prompts/bkit-build-install-skills.md +2 -2
- package/.bkit/core/prompts/bkit-build-plan-convert.md +21 -7
- package/.bkit/core/prompts/bkit-build-plan-current.md +5 -4
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +22 -17
- package/.bkit/core/prompts/bkit-build-plan-tasks.md +16 -12
- package/.bkit/core/prompts/bkit-build-plan-tests.md +14 -10
- package/.bkit/core/prompts/bkit-build-plan-verify.md +21 -8
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +10 -5
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +22 -6
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +19 -3
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +22 -6
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +10 -7
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +3 -3
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +4 -4
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +3 -3
- package/.bkit/core/prompts/bkit-design-generate.md +6 -4
- package/.bkit/core/prompts/bkit-design-organise.md +4 -3
- package/.bkit/core/prompts/bkit-design-review-1.md +5 -4
- package/.bkit/core/prompts/bkit-design-review-2.md +6 -5
- package/.bkit/core/prompts/bkit-design-spike.md +4 -3
- package/.bkit/core/prompts/bkit-design-update.md +6 -4
- package/.bkit/core/prompts/bkit-plan-generate.md +35 -14
- package/.bkit/core/prompts/bkit-plan-review-1.md +9 -7
- package/.bkit/core/prompts/bkit-plan-review-2.md +9 -7
- package/.bkit/core/prompts/bkit-plan-scope-check.md +8 -6
- package/.bkit/core/prompts/bkit-plan-update.md +22 -8
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +11 -8
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +9 -5
- package/.bkit/core/prompts/bkit-ship-update-docs.md +26 -4
- package/.bkit/core/prompts/bkit-utility-compress-markdown.md +3 -3
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +10 -7
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +8 -5
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +31 -7
- package/.bkit/core/prompts/bkit-utility-update-failures.md +8 -5
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +10 -7
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +4 -4
- package/.bkit/core/prompts/bkit-utility-update-tracker.md +4 -4
- package/.bkit/core/workflows/bkit-auto.md +23 -11
- package/.bkit/core/workflows/bkit-build.md +331 -100
- package/.bkit/core/workflows/bkit-debug.md +135 -64
- package/.bkit/core/workflows/bkit-design.md +58 -32
- package/.bkit/core/workflows/bkit-plan.md +73 -45
- package/.bkit/core/workflows/bkit-ship.md +233 -167
- package/.bkit/shared/.agents/plugins/bkit/hooks.json +1 -1
- package/.bkit/shared/.bkit/.env.example +5 -0
- package/.bkit/shared/.claude/bkit-cloud.md +7 -7
- package/.bkit/shared/.claude/settings.json +5 -1
- package/.bkit/shared/.cursor/bkit-cloud.md +1 -1
- package/.bkit/shared/.cursor/hooks.json +1 -1
- package/.bkit/shared/.opencode/opencode.json +11 -2
- package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +27 -0
- package/.bkit/templates/.cursor/Dockerfile +7 -7
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +1 -1
- package/.bkit/templates/.github/dependabot.yml +5 -0
- package/.bkit/templates/.github/renovate.json5 +5 -3
- package/.bkit/templates/.github/workflows/bkit-ci.yml +11 -11
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +525 -161
- package/.bkit/templates/.github/workflows/bkit-renovate.yml +2 -2
- package/.bkit/templates/.husky/pre-push +123 -6
- package/.bkit/templates/context/bkit-serena.md +1 -1
- package/.bkit/templates/context/bkit-vercel.md +103 -59
- package/.bkit/templates/docs/architecture.md +98 -0
- package/.bkit/templates/docs/capabilities.md +33 -37
- package/.bkit/templates/docs/components.md +142 -0
- package/.bkit/templates/docs/data-schema.md +87 -0
- package/.bkit/{shared → templates}/docs/deployments.md +128 -142
- package/.bkit/templates/docs/design.md +117 -0
- package/.bkit/templates/docs/noise.md +54 -0
- package/.bkit/templates/docs/observability.md +99 -0
- package/.bkit/templates/docs/security.md +137 -0
- package/.bkit/templates/docs/setup.md +93 -0
- package/.bkit/templates/docs/technology.md +70 -0
- package/.bkit/{shared → templates}/docs/testing.md +200 -87
- package/.bkit/templates/scripts/ci/bkit-check-accepted-divergences.mjs +1 -6
- package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +511 -103
- package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +314 -28
- package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +500 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +91 -62
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +59 -11
- package/.bkit/templates/slop-scan.config.json +2 -0
- package/CHANGELOG.md +79 -0
- package/DETAILS.md +661 -0
- package/README.md +73 -604
- package/dist/checks/after/auth.js +114 -46
- package/dist/checks/after/github.js +138 -35
- package/dist/checks/after/index.js +16 -4
- package/dist/checks/after/tools.js +224 -1
- package/dist/checks/before/files.js +59 -1
- package/dist/checks/before/index.js +7 -1
- package/dist/checks/status-holes.js +20 -21
- package/dist/checks/tips/catalogue.js +99 -10
- package/dist/checks/tips/detect.js +35 -3
- package/dist/checks/tips/index.js +1 -1
- package/dist/cli.js +13 -13
- package/dist/commands/ci/ci.js +113 -20
- package/dist/commands/ci/push-gate.js +79 -44
- package/dist/commands/install/doctor.js +5 -5
- package/dist/commands/install/install.js +23 -22
- package/dist/commands/install/uninstall.js +36 -30
- package/dist/commands/install/upgrade.js +10 -2
- package/dist/commands/land.js +2 -3
- package/dist/commands/lib.js +323 -25
- package/dist/commands/workflow/branches.js +312 -72
- package/dist/commands/workflow/challenge.js +66 -13
- package/dist/commands/workflow/context.js +46 -10
- package/dist/commands/workflow/counters.js +231 -23
- package/dist/commands/workflow/decisions.js +221 -106
- package/dist/commands/workflow/disk.js +2 -1
- package/dist/commands/workflow/feature-base.js +60 -0
- package/dist/commands/workflow/issues.js +243 -15
- package/dist/commands/workflow/junit.js +137 -0
- package/dist/commands/workflow/ledgers.js +726 -112
- package/dist/commands/workflow/locks.js +150 -29
- package/dist/commands/workflow/loops.js +67 -0
- package/dist/commands/workflow/open-decision.js +199 -0
- package/dist/commands/workflow/plan-blocks.js +6 -0
- package/dist/commands/workflow/plans.js +1 -1
- package/dist/commands/workflow/prs.js +272 -16
- package/dist/commands/workflow/repo.js +1 -1
- package/dist/commands/workflow/run-facts.js +6 -0
- package/dist/commands/workflow/runs.js +747 -155
- package/dist/commands/workflow/runtime.js +8 -4
- package/dist/commands/workflow/status.js +259 -13
- package/dist/commands/workflow/step-table.js +41 -15
- package/dist/commands/workflow/steps.js +530 -26
- package/dist/commands/workflow/summary-findings.js +1 -1
- package/dist/commands/workflow/summary.js +289 -8
- package/dist/commands/workflow/tasks.js +294 -27
- package/dist/commands/workflow/tests-base.js +266 -0
- package/dist/commands/workflow/tests-changed.js +130 -56
- package/dist/commands/workflow/tests-jump.js +77 -0
- package/dist/commands/workflow/tests.js +608 -131
- package/dist/commands/workflow/tracker.js +920 -112
- package/dist/commands/workflow/workflows.js +80 -59
- package/dist/commands/workflow/worktrees.js +387 -58
- package/dist/install/cloud-env.js +32 -10
- package/dist/install/managed-block.js +101 -0
- package/dist/install/manifest.js +7 -1
- package/dist/install/modules/claude.js +6 -2
- package/dist/install/modules/cloud.js +73 -86
- package/dist/install/modules/codex.js +9 -2
- package/dist/install/modules/core.js +190 -27
- package/dist/install/modules/opencode.js +18 -23
- package/dist/install/network-allowlist.js +8 -3
- package/dist/install/project-docs.js +551 -0
- package/dist/install/template-copies.js +55 -5
- package/dist/install/write.js +117 -5
- package/dist/ledgers/journal.js +10 -8
- package/dist/ledgers/migrate.js +20 -9
- package/dist/ledgers/status.js +461 -8
- package/dist/ledgers/telemetry.js +71 -13
- package/dist/render/trackers.js +21 -12
- package/dist/shared/package-manager.js +7 -2
- package/dist/shared/settings.js +8 -0
- package/dist/shared/text.js +13 -0
- package/dist/tools/instructions-sources.js +1 -0
- package/dist/tools/instructions.js +97 -24
- package/package.json +23 -15
- package/.bkit/core/hooks/preflight-linear.sh +0 -73
- package/.bkit/shared/docs/architecture.md +0 -16
- package/.bkit/shared/docs/data-schema.md +0 -16
- package/.bkit/shared/docs/design.md +0 -38
- package/.bkit/shared/docs/noise.md +0 -20
- package/.bkit/shared/docs/observability.md +0 -22
- package/.bkit/shared/docs/security.md +0 -62
- package/.bkit/shared/docs/setup.md +0 -52
- package/.bkit/shared/docs/technology.md +0 -15
- /package/.bkit/templates/{.lintstagedrc.json → lintstagedrc.example.json} +0 -0
- /package/.bkit/templates/{.prettierignore → prettierignore.example} +0 -0
|
@@ -9,15 +9,18 @@
|
|
|
9
9
|
// before `git commit`: `git commit --pathspec-from-file=<empty file>` commits
|
|
10
10
|
// everything already in the index, not nothing.
|
|
11
11
|
import { spawnSync } from "node:child_process";
|
|
12
|
+
import { createHash } from "node:crypto";
|
|
12
13
|
import * as fs from "node:fs";
|
|
13
14
|
import * as os from "node:os";
|
|
14
15
|
import * as path from "node:path";
|
|
15
16
|
import { readBkitVersion } from "../../install/version-file.js";
|
|
16
17
|
import { readBkitConfig } from "../../shared/settings.js";
|
|
17
|
-
import { APPEND_LEDGERS, SCHEMA, UNJUSTIFIED_REASON, gitEnv, parse, mintTs, resolveRepoSlug, validate, withLineage, writerProblem, } from "../../ledgers/telemetry.js";
|
|
18
|
+
import { APPEND_LEDGERS, SCHEMA, UNJUSTIFIED_REASON, gitEnv, parse, queryLedger, mintTs, resolveRepoSlug, validate, withLineage, writerProblem, } from "../../ledgers/telemetry.js";
|
|
18
19
|
import { COMPACT_LEDGERS, compactLedgers } from "../../ledgers/compact.js";
|
|
19
|
-
import {
|
|
20
|
-
import {
|
|
20
|
+
import { CORRECTION_REJECTED_ROW, CORRECTION_SUCCEEDED_ROW, actionHash, appendHeld, appendLine, correctionScope, ledgerIntent, ledgerOperation, ledgerOperationsFile, pendingLedgerIntentsFor, recordLedgerIntent, recordLedgerOperation, statusTimestamp, withTargetLock, writePrepared, } from "../../ledgers/status.js";
|
|
21
|
+
import { CommandError, CorrectionExhausted, EXIT, INVOCATION_FLAG, invocationDir, isIgnoredPath, isSharedBranch, NoWriteRejection, parseJson, UncertainEffect, wholeNumber, } from "../lib.js";
|
|
22
|
+
import { CORRECTION_LIMIT, spendCorrection } from "./counters.js";
|
|
23
|
+
import { readStatusRows, str } from "./status.js";
|
|
21
24
|
import { NO_MARKERS_REASON, outOfScope, parsePlanBlocks, reuseInventory, } from "./plan-blocks.js";
|
|
22
25
|
/** Root is not a directory or repo, git is too old, or a ref does not resolve. */
|
|
23
26
|
export const EXIT_ROOT = 3;
|
|
@@ -31,6 +34,8 @@ export const EXIT_EMPTY = 6;
|
|
|
31
34
|
export const EXIT_NOT_BOOKKEEPING = 7;
|
|
32
35
|
/** append: a row was refused (supplied `ts`, wrong kind, invalid, unlisted writer). */
|
|
33
36
|
export const EXIT_ROW_REFUSED = 8;
|
|
37
|
+
/** Rows per `ledgers query` page unless --limit says otherwise. */
|
|
38
|
+
const QUERY_PAGE = 200;
|
|
34
39
|
const SCOPES = ["core", "full", "pr"];
|
|
35
40
|
const MODES = ["stage", "commit", "commit-allow-empty"];
|
|
36
41
|
/** `package.json` globs as git pathspecs: `:(glob)` unless an entry carries its own magic. */
|
|
@@ -77,7 +82,7 @@ const UNION_PATHSPECS = [
|
|
|
77
82
|
":(exclude).bkit/issues.jsonl",
|
|
78
83
|
];
|
|
79
84
|
/** `git <args>` in `cwd`, never throwing and never trimming (NUL-delimited output). */
|
|
80
|
-
function gitRaw(cwd, args, env = {}, input) {
|
|
85
|
+
export function gitRaw(cwd, args, env = {}, input) {
|
|
81
86
|
const res = spawnSync("git", args, {
|
|
82
87
|
cwd,
|
|
83
88
|
encoding: "utf-8",
|
|
@@ -149,6 +154,8 @@ export const EXIT_ROWS_MISSING = 11;
|
|
|
149
154
|
/** commit --scope=pr: the checkout is on `dev`, `main` or a detached HEAD, so nothing is committed. */
|
|
150
155
|
export const EXIT_SHARED_BRANCH = 12;
|
|
151
156
|
const RECORD_DIR = "bkit/shared-checkout";
|
|
157
|
+
/** Where a stopped run's commit list is parked: a directory the record listing never reads. */
|
|
158
|
+
const PARKED_DIR = "bkit/shared-checkout-parked";
|
|
152
159
|
const RECORD_FID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
|
|
153
160
|
/** The checkout's top: git status and pathspecs are relative to it, whatever `cwd` is. */
|
|
154
161
|
function topOf(cwd) {
|
|
@@ -264,6 +271,108 @@ export function removeRecord(cwd, fid) {
|
|
|
264
271
|
fs.rmSync(file, { force: true });
|
|
265
272
|
return true;
|
|
266
273
|
}
|
|
274
|
+
/** `$(git rev-parse --git-path bkit/shared-checkout-parked/{fid}.json)`, absolute; null for a bad FID or outside a repo. */
|
|
275
|
+
function parkedFile(cwd, fid) {
|
|
276
|
+
if (!RECORD_FID.test(fid) || fid.includes(".."))
|
|
277
|
+
return null;
|
|
278
|
+
const res = gitRaw(cwd, ["rev-parse", "--git-path", `${PARKED_DIR}/${fid}.json`]);
|
|
279
|
+
return res.status === 0 && res.stdout.trim() !== "" ? path.resolve(cwd, res.stdout.trim()) : null;
|
|
280
|
+
}
|
|
281
|
+
/**
|
|
282
|
+
* Park `rec`'s start, commits and pushed list for `workflow` in this clone's git dir, so a
|
|
283
|
+
* resume of a run that stays open can rebuild its record without any remote.
|
|
284
|
+
*/
|
|
285
|
+
export function writeParkedCommits(cwd, workflow, rec) {
|
|
286
|
+
const file = parkedFile(cwd, rec.fid);
|
|
287
|
+
if (file === null)
|
|
288
|
+
throw new CommandError(EXIT_ROOT, `cannot park commits for "${rec.fid}"`);
|
|
289
|
+
fs.mkdirSync(path.dirname(file), { recursive: true });
|
|
290
|
+
const parked = {
|
|
291
|
+
workflow,
|
|
292
|
+
at: statusTimestamp(),
|
|
293
|
+
startSha: rec.startSha,
|
|
294
|
+
commits: rec.commits,
|
|
295
|
+
pushed: rec.pushed ?? [],
|
|
296
|
+
};
|
|
297
|
+
fs.writeFileSync(file, `${JSON.stringify(parked, null, 2)}\n`);
|
|
298
|
+
}
|
|
299
|
+
/** The FID's parked commit list for `workflow`; null when absent, unreadable or parked for another workflow. */
|
|
300
|
+
export function readParkedCommits(cwd, fid, workflow) {
|
|
301
|
+
const file = parkedFile(cwd, fid);
|
|
302
|
+
if (file === null || !fs.existsSync(file))
|
|
303
|
+
return null;
|
|
304
|
+
const parsed = parseJson(fs.readFileSync(file, "utf-8"));
|
|
305
|
+
if (!parsed.ok || parsed.value === null || typeof parsed.value !== "object")
|
|
306
|
+
return null;
|
|
307
|
+
const p = parsed.value;
|
|
308
|
+
if (p["workflow"] !== workflow)
|
|
309
|
+
return null;
|
|
310
|
+
const ids = (v) => Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
|
|
311
|
+
return {
|
|
312
|
+
startSha: typeof p["startSha"] === "string" ? p["startSha"] : "",
|
|
313
|
+
commits: ids(p["commits"]),
|
|
314
|
+
pushed: ids(p["pushed"]),
|
|
315
|
+
};
|
|
316
|
+
}
|
|
317
|
+
/** Remove the FID's parked commit list; false when there was none. */
|
|
318
|
+
export function removeParkedCommits(cwd, fid) {
|
|
319
|
+
const file = parkedFile(cwd, fid);
|
|
320
|
+
if (file === null || !fs.existsSync(file))
|
|
321
|
+
return false;
|
|
322
|
+
fs.rmSync(file, { force: true });
|
|
323
|
+
return true;
|
|
324
|
+
}
|
|
325
|
+
/** The status row type that carries a run's commit list across the removal of its record. */
|
|
326
|
+
export const RUN_COMMITS_ROW = "run-commits";
|
|
327
|
+
/** Append a `run-commits` row for `rec` to the status log `file`. */
|
|
328
|
+
export function appendRunCommits(file, workflow, rec) {
|
|
329
|
+
fs.appendFileSync(file, appendLine({
|
|
330
|
+
type: RUN_COMMITS_ROW,
|
|
331
|
+
workflow,
|
|
332
|
+
at: statusTimestamp(),
|
|
333
|
+
startSha: rec.startSha,
|
|
334
|
+
commits: rec.commits,
|
|
335
|
+
pushed: rec.pushed ?? [],
|
|
336
|
+
}));
|
|
337
|
+
}
|
|
338
|
+
/**
|
|
339
|
+
* The newest `run-commits` row of `workflow`'s open run in the status log `file`. Null
|
|
340
|
+
* when the log or the row is missing.
|
|
341
|
+
*/
|
|
342
|
+
export function readRunCommits(file, workflow) {
|
|
343
|
+
if (!fs.existsSync(file))
|
|
344
|
+
return null;
|
|
345
|
+
return runCommitsIn(fs.readFileSync(file, "utf-8"), workflow);
|
|
346
|
+
}
|
|
347
|
+
/**
|
|
348
|
+
* The newest `run-commits` row of `workflow` in the status log `text`, among the rows after
|
|
349
|
+
* the last `workflow-started` row of that workflow, in file order. Null when there is none;
|
|
350
|
+
* a line that is not a JSON object is skipped.
|
|
351
|
+
*/
|
|
352
|
+
export function runCommitsIn(text, workflow) {
|
|
353
|
+
const rows = text
|
|
354
|
+
.split("\n")
|
|
355
|
+
.flatMap((line) => {
|
|
356
|
+
const parsed = parseJson(line);
|
|
357
|
+
return parsed.ok && parsed.value !== null && typeof parsed.value === "object"
|
|
358
|
+
? [parsed.value]
|
|
359
|
+
: [];
|
|
360
|
+
})
|
|
361
|
+
.filter((row) => row["workflow"] === workflow);
|
|
362
|
+
const opened = rows.map((row) => row["type"]).lastIndexOf("workflow-started");
|
|
363
|
+
const row = rows
|
|
364
|
+
.slice(opened + 1)
|
|
365
|
+
.filter((r) => r["type"] === RUN_COMMITS_ROW)
|
|
366
|
+
.at(-1);
|
|
367
|
+
if (row === undefined)
|
|
368
|
+
return null;
|
|
369
|
+
const ids = (v) => Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
|
|
370
|
+
return {
|
|
371
|
+
startSha: typeof row["startSha"] === "string" ? row["startSha"] : "",
|
|
372
|
+
commits: ids(row["commits"]),
|
|
373
|
+
pushed: ids(row["pushed"]),
|
|
374
|
+
};
|
|
375
|
+
}
|
|
267
376
|
/** The FID's record, only while its branch is still the one checked out. */
|
|
268
377
|
export function activeRecord(cwd, fid) {
|
|
269
378
|
const rec = readRecord(cwd, fid);
|
|
@@ -647,19 +756,76 @@ export const ledgersCommand = {
|
|
|
647
756
|
required: true,
|
|
648
757
|
help: "file holding a JSON array of rows without schema, ts or bkit, or - for stdin",
|
|
649
758
|
},
|
|
759
|
+
{
|
|
760
|
+
...INVOCATION_FLAG,
|
|
761
|
+
help: `${INVOCATION_FLAG.help}; fills each row's by block (workflow, step, subagent, model, provenance) and refuses a row whose own by disagrees`,
|
|
762
|
+
},
|
|
763
|
+
{
|
|
764
|
+
name: "operation",
|
|
765
|
+
type: "string",
|
|
766
|
+
help: "operation id naming this request: the same id and rows replay the original receipt without writing; the same id with other rows is refused; a new id is a deliberate later update",
|
|
767
|
+
},
|
|
768
|
+
{
|
|
769
|
+
name: "issue-operation",
|
|
770
|
+
type: "boolean",
|
|
771
|
+
help: "let the engine issue the operation id from --invocation and the request, so a retried call after a lost response replays instead of appending again; exclusive with --operation",
|
|
772
|
+
},
|
|
773
|
+
{
|
|
774
|
+
name: "correction-of",
|
|
775
|
+
type: "string",
|
|
776
|
+
help: "the operation of an earlier guaranteed no-write rejection of this ledger append in this step: this call is its corrected retry (two per scope), under its own fresh --operation or --issue-operation",
|
|
777
|
+
},
|
|
650
778
|
],
|
|
651
779
|
output: {
|
|
652
780
|
ledger: "the ledger appended to",
|
|
653
781
|
file: "its path, relative to --root",
|
|
654
782
|
appended: "rows written",
|
|
655
783
|
keys: "each row's key, in order (null when a row has none)",
|
|
784
|
+
receipt: "with --operation: {operation, ledger, file, offset, bytes, rows[{key, ts}], replayed}; replayed is true when the original effect is returned",
|
|
785
|
+
correction: "with --correction-of: {scope, operation, of, used, limit, substep, verified}; verified is true when the rows landed (or the original receipt was returned)",
|
|
656
786
|
},
|
|
657
787
|
exitCodes: {
|
|
658
|
-
[EXIT_STAGE]: "mkdir or append failed",
|
|
788
|
+
[EXIT_STAGE]: "mkdir or append failed, the ledger is locked by another writer, or a prior attempt left an uncertain partial write",
|
|
659
789
|
[EXIT_ROW_REFUSED]: "a row carries ts, has the wrong kind, fails validation, or names a writer not listed for its kind — nothing written",
|
|
660
790
|
},
|
|
661
791
|
run: (ctx) => append(ctx),
|
|
662
792
|
},
|
|
793
|
+
query: {
|
|
794
|
+
summary: "Read one ledger's canonical winners (filtered after the fold), paged, with line diagnostics and coverage. Writes nothing.",
|
|
795
|
+
use: "by-hand",
|
|
796
|
+
flags: [
|
|
797
|
+
{ name: "root", type: "string", help: "checkout whose ledger to read (default: cwd)" },
|
|
798
|
+
{
|
|
799
|
+
name: "ledger",
|
|
800
|
+
type: "string",
|
|
801
|
+
required: true,
|
|
802
|
+
help: Object.keys(APPEND_LEDGERS).join(" | "),
|
|
803
|
+
},
|
|
804
|
+
{ name: "key", type: "string", help: "only the winner with this key" },
|
|
805
|
+
{ name: "status", type: "string", help: "only winners whose status is this (e.g. ACTIVE)" },
|
|
806
|
+
{
|
|
807
|
+
name: "limit",
|
|
808
|
+
type: "string",
|
|
809
|
+
help: `rows per page (default ${QUERY_PAGE}, at least 1)`,
|
|
810
|
+
},
|
|
811
|
+
{
|
|
812
|
+
name: "cursor",
|
|
813
|
+
type: "string",
|
|
814
|
+
help: "nextCursor of the previous page; refused when the ledger or the filter changed",
|
|
815
|
+
},
|
|
816
|
+
],
|
|
817
|
+
output: {
|
|
818
|
+
ledger: "the ledger read",
|
|
819
|
+
file: "its path, relative to --root",
|
|
820
|
+
rows: "this page of fold winners, oldest ts first (equal ts by identity)",
|
|
821
|
+
nextCursor: "pass as --cursor for the next page, or null on the last page",
|
|
822
|
+
snapshot: "digest of the bytes read; every page of one scan shares it",
|
|
823
|
+
total: "winners that pass the filter, across all pages",
|
|
824
|
+
diagnostics: "each unreadable line: {line, reason}; on every page",
|
|
825
|
+
coverage: "{status: clean|incomplete|partial|missing|unreadable, clean, malformedLines, lines}; clean is true only for a finished scan (nextCursor null) with no unreadable line, so a page with a nextCursor is incomplete",
|
|
826
|
+
},
|
|
827
|
+
run: (ctx) => query(ctx),
|
|
828
|
+
},
|
|
663
829
|
triage: {
|
|
664
830
|
summary: "Bucket each deferral row the FID declared by the four Deferral Reason tests, and write the unjustified ones.",
|
|
665
831
|
use: "workflow",
|
|
@@ -987,15 +1153,21 @@ export function unionLedgers(src, dst) {
|
|
|
987
1153
|
if (made)
|
|
988
1154
|
throw new CommandError(EXIT_STAGE, `mkdir failed for ${path.dirname(to)}: ${made}`);
|
|
989
1155
|
if (fs.existsSync(to) && fs.statSync(to).isFile()) {
|
|
990
|
-
|
|
991
|
-
|
|
992
|
-
|
|
993
|
-
|
|
994
|
-
|
|
995
|
-
|
|
996
|
-
|
|
997
|
-
|
|
998
|
-
|
|
1156
|
+
// Under the destination's target lock, so a pending ledger operation's bytes are never reordered.
|
|
1157
|
+
withTargetLock(to, () => {
|
|
1158
|
+
const pending = pendingLedgerIntentsFor(dst, rel);
|
|
1159
|
+
if (pending.length > 0)
|
|
1160
|
+
throw new CommandError(EXIT_STAGE, `${rel} has ledger operation(s) with bytes but no receipt (${pending.map((p) => p.operation).join(", ")}); replay them first`);
|
|
1161
|
+
const existing = fs.readFileSync(to, "utf-8");
|
|
1162
|
+
const have = new Set(fileLines(existing));
|
|
1163
|
+
const fresh = fileLines(fs.readFileSync(from, "utf-8")).filter((l) => !have.has(l));
|
|
1164
|
+
const block = fresh.join("\n").replace(/\n+$/, "");
|
|
1165
|
+
// A destination missing its final newline would glue the first new row
|
|
1166
|
+
// onto its last one, leaving a line that is not JSON.
|
|
1167
|
+
const sep = existing !== "" && !existing.endsWith("\n") ? "\n" : "";
|
|
1168
|
+
if (block !== "")
|
|
1169
|
+
fs.appendFileSync(to, `${sep}${block}\n`);
|
|
1170
|
+
});
|
|
999
1171
|
}
|
|
1000
1172
|
else {
|
|
1001
1173
|
const copied = copy(from, to);
|
|
@@ -1027,16 +1199,157 @@ const TOP_ORDER = [
|
|
|
1027
1199
|
"by",
|
|
1028
1200
|
"references",
|
|
1029
1201
|
];
|
|
1202
|
+
/** A row's `by` block when it is an object, else an empty one. */
|
|
1203
|
+
const byOfRow = (row) => row["by"] !== null && typeof row["by"] === "object" && !Array.isArray(row["by"])
|
|
1204
|
+
? row["by"]
|
|
1205
|
+
: {};
|
|
1206
|
+
/** The `by` fields an invocation owns; a row may repeat them but never disagree. */
|
|
1207
|
+
const INVOCATION_BY_KEYS = [
|
|
1208
|
+
"workflow",
|
|
1209
|
+
"step",
|
|
1210
|
+
"subagent",
|
|
1211
|
+
"model",
|
|
1212
|
+
"modelSource",
|
|
1213
|
+
"configuredModel",
|
|
1214
|
+
"host",
|
|
1215
|
+
];
|
|
1216
|
+
/**
|
|
1217
|
+
* `row` with its `by` block completed from the verified invocation. A field the row
|
|
1218
|
+
* asserts that differs from the invocation's, or that the invocation cannot vouch for,
|
|
1219
|
+
* is refused rather than overwritten. A configured pin is recorded as `configuredModel`
|
|
1220
|
+
* only, never as the model that ran.
|
|
1221
|
+
*/
|
|
1222
|
+
function withInvocationBy(row, inv, refuse) {
|
|
1223
|
+
const unavailable = inv.observedModel === "unavailable";
|
|
1224
|
+
const expected = {
|
|
1225
|
+
workflow: inv.workflow ?? inv.standalone ?? undefined,
|
|
1226
|
+
step: inv.step ?? inv.declaredStep ?? undefined,
|
|
1227
|
+
subagent: inv.agent ?? undefined,
|
|
1228
|
+
model: inv.agent !== null && inv.observedModel !== null && !unavailable
|
|
1229
|
+
? inv.observedModel
|
|
1230
|
+
: undefined,
|
|
1231
|
+
modelSource: inv.agent === null || inv.observedModel === null
|
|
1232
|
+
? undefined
|
|
1233
|
+
: unavailable
|
|
1234
|
+
? "unavailable"
|
|
1235
|
+
: "observed",
|
|
1236
|
+
configuredModel: inv.agent !== null ? (inv.configuredModel ?? undefined) : undefined,
|
|
1237
|
+
host: inv.agent !== null ? (inv.host ?? undefined) : undefined,
|
|
1238
|
+
};
|
|
1239
|
+
const asserted = row["by"];
|
|
1240
|
+
if (asserted !== undefined &&
|
|
1241
|
+
(asserted === null || typeof asserted !== "object" || Array.isArray(asserted)))
|
|
1242
|
+
throw refuse("by must be an object");
|
|
1243
|
+
const by = { ...asserted };
|
|
1244
|
+
for (const key of INVOCATION_BY_KEYS) {
|
|
1245
|
+
if (by[key] !== undefined && by[key] !== expected[key]) {
|
|
1246
|
+
throw refuse(`conflict: by.${key}=${JSON.stringify(by[key])} disagrees with invocation ${inv.id} (${expected[key] === undefined ? "none" : JSON.stringify(expected[key])})`);
|
|
1247
|
+
}
|
|
1248
|
+
if (by[key] === undefined && expected[key] !== undefined)
|
|
1249
|
+
by[key] = expected[key];
|
|
1250
|
+
}
|
|
1251
|
+
return { ...row, by };
|
|
1252
|
+
}
|
|
1253
|
+
/** `JSON.stringify` with object keys sorted at every depth: equal requests serialize equally. */
|
|
1254
|
+
export function canonicalJson(value) {
|
|
1255
|
+
if (Array.isArray(value))
|
|
1256
|
+
return `[${value.map((v) => canonicalJson(v)).join(",")}]`;
|
|
1257
|
+
if (value !== null && typeof value === "object") {
|
|
1258
|
+
const o = value;
|
|
1259
|
+
return `{${Object.keys(o)
|
|
1260
|
+
.filter((k) => o[k] !== undefined)
|
|
1261
|
+
.sort()
|
|
1262
|
+
.map((k) => `${JSON.stringify(k)}:${canonicalJson(o[k])}`)
|
|
1263
|
+
.join(",")}}`;
|
|
1264
|
+
}
|
|
1265
|
+
return JSON.stringify(value) ?? "null";
|
|
1266
|
+
}
|
|
1267
|
+
/**
|
|
1268
|
+
* The operation id of an append request: the caller's `--operation`, else (with
|
|
1269
|
+
* `--issue-operation`) one issued from the invocation and the request, so retrying a lost
|
|
1270
|
+
* response gets the same id.
|
|
1271
|
+
*/
|
|
1272
|
+
export function appendOperationId(ledger, rows, invocation, options) {
|
|
1273
|
+
if (options.operation !== undefined)
|
|
1274
|
+
return options.operation;
|
|
1275
|
+
if (options.issueOperation !== true || invocation === undefined)
|
|
1276
|
+
return undefined;
|
|
1277
|
+
const hash = actionHash(canonicalJson({ ledger, rows, invocation: invocation.id }));
|
|
1278
|
+
return `op-${invocation.id.slice(4, 16)}-${hash.slice(0, 12)}`;
|
|
1279
|
+
}
|
|
1280
|
+
/**
|
|
1281
|
+
* The correction scope of an append by a workflow-run or a standalone (audit or utility)
|
|
1282
|
+
* invocation; null for any other caller.
|
|
1283
|
+
*/
|
|
1284
|
+
export function appendCorrectionScope(invocation, ledger) {
|
|
1285
|
+
const book = correctionBookKey(invocation);
|
|
1286
|
+
if (book === null)
|
|
1287
|
+
return null;
|
|
1288
|
+
return correctionScope({
|
|
1289
|
+
workflow: book.workflow,
|
|
1290
|
+
run: invocation.run,
|
|
1291
|
+
step: book.step,
|
|
1292
|
+
group: invocation.group,
|
|
1293
|
+
attempt: invocation.attempt,
|
|
1294
|
+
ledger,
|
|
1295
|
+
substep: "append",
|
|
1296
|
+
});
|
|
1297
|
+
}
|
|
1298
|
+
/** The workflow and step a correction scope is cut from; the declared step for a standalone call. */
|
|
1299
|
+
function correctionBookKey(invocation) {
|
|
1300
|
+
if (invocation.scope === "run")
|
|
1301
|
+
return invocation.statusPath === null ||
|
|
1302
|
+
invocation.workflow === null ||
|
|
1303
|
+
invocation.step === null
|
|
1304
|
+
? null
|
|
1305
|
+
: { workflow: invocation.workflow, step: invocation.step };
|
|
1306
|
+
return invocation.standalone === null || invocation.declaredStep === null
|
|
1307
|
+
? null
|
|
1308
|
+
: { workflow: invocation.standalone, step: invocation.declaredStep };
|
|
1309
|
+
}
|
|
1310
|
+
/**
|
|
1311
|
+
* Where the correction events of `invocation` live: the run's `status.jsonl`, or for a standalone
|
|
1312
|
+
* call the event file beside its outbox receipt. Null when the caller has no correction scope.
|
|
1313
|
+
*/
|
|
1314
|
+
function correctionBook(cwd, invocation) {
|
|
1315
|
+
const key = correctionBookKey(invocation);
|
|
1316
|
+
if (key === null)
|
|
1317
|
+
return null;
|
|
1318
|
+
if (invocation.scope === "run")
|
|
1319
|
+
return invocation.statusPath === null ? null : { file: invocation.statusPath, ...key };
|
|
1320
|
+
const dir = invocationDir(cwd);
|
|
1321
|
+
if (dir === null)
|
|
1322
|
+
return null;
|
|
1323
|
+
const file = path.join(dir, `${invocation.id}.corrections.jsonl`);
|
|
1324
|
+
fs.appendFileSync(file, "");
|
|
1325
|
+
return { file, ...key };
|
|
1326
|
+
}
|
|
1327
|
+
/** The `{key, ts}` of each row in prepared `block` bytes. */
|
|
1328
|
+
function receiptRows(block) {
|
|
1329
|
+
const out = [];
|
|
1330
|
+
for (const line of block.split("\n")) {
|
|
1331
|
+
if (line.trim() === "")
|
|
1332
|
+
continue;
|
|
1333
|
+
const parsed = parseJson(line);
|
|
1334
|
+
if (!parsed.ok || parsed.value === null || typeof parsed.value !== "object")
|
|
1335
|
+
continue;
|
|
1336
|
+
const r = parsed.value;
|
|
1337
|
+
out.push({ key: typeof r["key"] === "string" ? r["key"] : null, ts: Number(r["ts"]) });
|
|
1338
|
+
}
|
|
1339
|
+
return out;
|
|
1340
|
+
}
|
|
1030
1341
|
/**
|
|
1031
1342
|
* Append `rows` to one ledger. Every row is checked before any is written, so a
|
|
1032
1343
|
* refused row leaves the file byte-identical. Each row gets `schema` and a `ts`
|
|
1033
1344
|
* minted now (never supplied), `repo` when it lacks one and `bkit.version` from
|
|
1034
1345
|
* `.bkit/version`; an `AGED_KINDS` row also gets `firstTs` + `updates` carried
|
|
1035
1346
|
* forward from its entry's rows already in the ledger (supplied values replaced).
|
|
1036
|
-
* Never rewrites existing rows.
|
|
1037
|
-
*
|
|
1347
|
+
* Never rewrites existing rows. The write runs under the ledger's target lock; with
|
|
1348
|
+
* `options.operation` it also records the prepared bytes and a durable receipt, so a
|
|
1349
|
+
* lost response is reconciled by inspecting the ledger, never by appending again.
|
|
1350
|
+
* Throws a CommandError (USAGE / EXIT_ROW_REFUSED / EXIT_STAGE).
|
|
1038
1351
|
*/
|
|
1039
|
-
export function appendLedgerRows(root, ledger, rows) {
|
|
1352
|
+
export function appendLedgerRows(root, ledger, rows, invocation, options = {}) {
|
|
1040
1353
|
if (!Object.hasOwn(APPEND_LEDGERS, ledger)) {
|
|
1041
1354
|
throw new CommandError(EXIT.USAGE, `--ledger must be one of ${Object.keys(APPEND_LEDGERS).join(", ")} (got '${ledger}')`);
|
|
1042
1355
|
}
|
|
@@ -1046,86 +1359,207 @@ export function appendLedgerRows(root, ledger, rows) {
|
|
|
1046
1359
|
throw new CommandError(EXIT.USAGE, "--rows must hold a JSON array");
|
|
1047
1360
|
if (rows.length === 0)
|
|
1048
1361
|
throw new CommandError(EXIT.USAGE, "--rows holds no rows");
|
|
1049
|
-
let repo;
|
|
1050
|
-
let version;
|
|
1051
|
-
let last;
|
|
1052
1362
|
const abs = path.join(root, file);
|
|
1053
|
-
const prior = fs.existsSync(abs) ? parse(fs.readFileSync(abs, "utf-8")).events : [];
|
|
1054
|
-
const out = rows.map((raw, i) => {
|
|
1055
|
-
const refuse = (why) => new CommandError(EXIT_ROW_REFUSED, `row ${i + 1}: ${why}`);
|
|
1056
|
-
if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
|
|
1057
|
-
throw refuse("not a JSON object");
|
|
1058
|
-
}
|
|
1059
|
-
const r = raw;
|
|
1060
|
-
if (Object.hasOwn(r, "ts"))
|
|
1061
|
-
throw refuse("carries ts; ts is minted at append time");
|
|
1062
|
-
if (Object.hasOwn(r, "schema"))
|
|
1063
|
-
throw refuse("carries schema; it is set at append time");
|
|
1064
|
-
if (!takes.includes(String(r["kind"]))) {
|
|
1065
|
-
throw refuse(`kind must be ${takes.join(" | ")} in --ledger=${ledger} (got ${String(r["kind"])})`);
|
|
1066
|
-
}
|
|
1067
|
-
if (Object.hasOwn(r, "bkit"))
|
|
1068
|
-
throw refuse("carries bkit; bkit.version is set at append time");
|
|
1069
|
-
repo ??= resolveRepoSlug(root) || "unknown/repo";
|
|
1070
|
-
version ??= readBkitVersion(path.join(root, ".bkit", "version"))?.pinnedVersion || "unknown";
|
|
1071
|
-
last = mintTs(last);
|
|
1072
|
-
const filled = withLineage(prior, {
|
|
1073
|
-
repo,
|
|
1074
|
-
...r,
|
|
1075
|
-
schema: SCHEMA,
|
|
1076
|
-
ts: last,
|
|
1077
|
-
bkit: { version },
|
|
1078
|
-
});
|
|
1079
|
-
const row = {};
|
|
1080
|
-
for (const k of TOP_ORDER)
|
|
1081
|
-
if (filled[k] !== undefined)
|
|
1082
|
-
row[k] = filled[k];
|
|
1083
|
-
for (const [k, v] of Object.entries(filled))
|
|
1084
|
-
if (!(k in row))
|
|
1085
|
-
row[k] = v;
|
|
1086
|
-
const v = validate(row);
|
|
1087
|
-
if (!v.ok)
|
|
1088
|
-
throw refuse(v.reason ?? "invalid");
|
|
1089
|
-
const who = writerProblem(row);
|
|
1090
|
-
if (who !== undefined)
|
|
1091
|
-
throw refuse(who);
|
|
1092
|
-
prior.push(row);
|
|
1093
|
-
return row;
|
|
1094
|
-
});
|
|
1095
1363
|
const made = mkdirp(path.dirname(abs));
|
|
1096
1364
|
if (made)
|
|
1097
1365
|
throw new CommandError(EXIT_STAGE, `mkdir failed for ${path.dirname(file)}: ${made}`);
|
|
1098
|
-
|
|
1099
|
-
//
|
|
1100
|
-
const
|
|
1101
|
-
|
|
1102
|
-
|
|
1103
|
-
|
|
1104
|
-
|
|
1105
|
-
|
|
1106
|
-
|
|
1107
|
-
|
|
1366
|
+
// The operation store is private to this git repository, never a committed path; a repo-less
|
|
1367
|
+
// root has no place to keep a durable receipt, so an operation there is refused.
|
|
1368
|
+
const ops = ledgerOperationsFile(root, options.operation !== undefined || options.issueOperation === true);
|
|
1369
|
+
// The request is the ledger and rows alone: an operation stays reconcilable after its
|
|
1370
|
+
// invocation goes stale, and replay writes the recorded bytes, never a re-derived `by`.
|
|
1371
|
+
const hash = actionHash(canonicalJson({ ledger, rows }));
|
|
1372
|
+
if (options.operation !== undefined && options.issueOperation === true)
|
|
1373
|
+
throw new CommandError(EXIT.USAGE, "--issue-operation and --operation are exclusive: the engine issues the id, or the caller names it");
|
|
1374
|
+
if (options.issueOperation === true && invocation === undefined)
|
|
1375
|
+
throw new CommandError(EXIT.USAGE, "--issue-operation needs --invocation: the id is issued from that invocation's context");
|
|
1376
|
+
const operation = appendOperationId(ledger, rows, invocation, options);
|
|
1377
|
+
// A rejection before any write is correctable only inside a workflow run (it has a scope to
|
|
1378
|
+
// spend from) and only when the operation can be named by the corrected retry.
|
|
1379
|
+
const scope = invocation === undefined ? null : appendCorrectionScope(invocation, ledger);
|
|
1380
|
+
const reject = (why, row) => {
|
|
1381
|
+
const message = `row ${row}: ${why}`;
|
|
1382
|
+
return scope !== null && operation !== undefined
|
|
1383
|
+
? new NoWriteRejection(EXIT_ROW_REFUSED, message, { scope, substep: "append" })
|
|
1384
|
+
: new CommandError(EXIT_ROW_REFUSED, message);
|
|
1108
1385
|
};
|
|
1109
|
-
|
|
1110
|
-
|
|
1111
|
-
|
|
1112
|
-
|
|
1386
|
+
const result = (landed, block, replayed) => {
|
|
1387
|
+
const parsedRows = receiptRows(block);
|
|
1388
|
+
return {
|
|
1389
|
+
ledger: ledger,
|
|
1390
|
+
file,
|
|
1391
|
+
appended: replayed ? 0 : parsedRows.length,
|
|
1392
|
+
keys: parsedRows.map((r) => r.key),
|
|
1393
|
+
...(operation === undefined
|
|
1394
|
+
? {}
|
|
1395
|
+
: {
|
|
1396
|
+
receipt: {
|
|
1397
|
+
operation,
|
|
1398
|
+
ledger,
|
|
1399
|
+
file,
|
|
1400
|
+
offset: landed.offset,
|
|
1401
|
+
bytes: landed.bytes,
|
|
1402
|
+
rows: parsedRows,
|
|
1403
|
+
replayed,
|
|
1404
|
+
},
|
|
1405
|
+
}),
|
|
1406
|
+
};
|
|
1407
|
+
};
|
|
1408
|
+
const build = (text) => {
|
|
1409
|
+
let repo;
|
|
1410
|
+
let version;
|
|
1411
|
+
let last;
|
|
1412
|
+
const prior = parse(text).events;
|
|
1413
|
+
const out = rows.map((raw, i) => {
|
|
1414
|
+
const refuse = (why) => new CommandError(EXIT_ROW_REFUSED, `row ${i + 1}: ${why}`);
|
|
1415
|
+
if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
|
|
1416
|
+
throw reject("not a JSON object", i + 1);
|
|
1417
|
+
}
|
|
1418
|
+
const r = invocation === undefined
|
|
1419
|
+
? raw
|
|
1420
|
+
: withInvocationBy(raw, invocation, refuse);
|
|
1421
|
+
if (invocation === undefined && byOfRow(r)["modelSource"] === "unavailable")
|
|
1422
|
+
throw refuse("by.modelSource unavailable needs a validated --invocation; the engine records it, a caller cannot assert it");
|
|
1423
|
+
if (Object.hasOwn(r, "ts"))
|
|
1424
|
+
throw reject("carries ts; ts is minted at append time", i + 1);
|
|
1425
|
+
if (Object.hasOwn(r, "schema"))
|
|
1426
|
+
throw reject("carries schema; it is set at append time", i + 1);
|
|
1427
|
+
if (!takes.includes(String(r["kind"]))) {
|
|
1428
|
+
throw reject(`kind must be ${takes.join(" | ")} in --ledger=${ledger} (got ${String(r["kind"])})`, i + 1);
|
|
1429
|
+
}
|
|
1430
|
+
if (Object.hasOwn(r, "bkit"))
|
|
1431
|
+
throw reject("carries bkit; bkit.version is set at append time", i + 1);
|
|
1432
|
+
repo ??= resolveRepoSlug(root) || "unknown/repo";
|
|
1433
|
+
version ??= readBkitVersion(path.join(root, ".bkit", "version"))?.pinnedVersion || "unknown";
|
|
1434
|
+
last = mintTs(last);
|
|
1435
|
+
const filled = withLineage(prior, {
|
|
1436
|
+
repo,
|
|
1437
|
+
...r,
|
|
1438
|
+
schema: SCHEMA,
|
|
1439
|
+
ts: last,
|
|
1440
|
+
bkit: { version },
|
|
1441
|
+
});
|
|
1442
|
+
const row = {};
|
|
1443
|
+
for (const k of TOP_ORDER)
|
|
1444
|
+
if (filled[k] !== undefined)
|
|
1445
|
+
row[k] = filled[k];
|
|
1446
|
+
for (const [k, v] of Object.entries(filled))
|
|
1447
|
+
if (!(k in row))
|
|
1448
|
+
row[k] = v;
|
|
1449
|
+
const v = validate(row);
|
|
1450
|
+
if (!v.ok)
|
|
1451
|
+
throw reject(v.reason ?? "invalid", i + 1);
|
|
1452
|
+
const who = writerProblem(row);
|
|
1453
|
+
if (who !== undefined)
|
|
1454
|
+
throw refuse(who);
|
|
1455
|
+
prior.push(row);
|
|
1456
|
+
return row;
|
|
1457
|
+
});
|
|
1458
|
+
return out.map((r) => `${JSON.stringify(r)}\n`).join("");
|
|
1459
|
+
};
|
|
1460
|
+
const stage = (err) => err instanceof CommandError
|
|
1461
|
+
? err
|
|
1462
|
+
: new CommandError(EXIT_STAGE, `append failed: ${file} \u2014 ${err.message}`);
|
|
1113
1463
|
try {
|
|
1114
|
-
|
|
1115
|
-
|
|
1116
|
-
|
|
1117
|
-
|
|
1118
|
-
|
|
1119
|
-
|
|
1120
|
-
|
|
1121
|
-
|
|
1122
|
-
|
|
1123
|
-
|
|
1124
|
-
|
|
1464
|
+
return withTargetLock(abs, () => {
|
|
1465
|
+
if (operation === undefined) {
|
|
1466
|
+
const landed = appendHeld(abs, build, { checkpoint: options.checkpoint });
|
|
1467
|
+
return result(landed, landed.block, false);
|
|
1468
|
+
}
|
|
1469
|
+
if (ops === null)
|
|
1470
|
+
throw new CommandError(EXIT.USAGE, `${root} is not inside a git repository: a ledger operation keeps its receipt in the git common dir`);
|
|
1471
|
+
// The operation store is serialized by its own lock, taken after the target's, so two
|
|
1472
|
+
// ledgers' operations never interleave check and record.
|
|
1473
|
+
return withTargetLock(ops, () => {
|
|
1474
|
+
const known = ledgerOperation(ops, operation, hash);
|
|
1475
|
+
if (known.state === "conflict")
|
|
1476
|
+
throw new CommandError(EXIT_ROW_REFUSED, `operation ${operation} was already used for a different request; nothing written`);
|
|
1477
|
+
if (known.state === "replay") {
|
|
1478
|
+
const d = known.row
|
|
1479
|
+
.detail;
|
|
1480
|
+
if (d === undefined)
|
|
1481
|
+
throw new CommandError(EXIT_STAGE, `operation ${operation} has a receipt without its effect`);
|
|
1482
|
+
return result(d, d.block, true);
|
|
1483
|
+
}
|
|
1484
|
+
const intent = ledgerIntent(ops, operation);
|
|
1485
|
+
if (intent !== undefined && intent.hash !== hash)
|
|
1486
|
+
throw new CommandError(EXIT_ROW_REFUSED, `operation ${operation} was already used for a different request; nothing written`);
|
|
1487
|
+
const receipt = (landed) => recordLedgerOperation(ops, {
|
|
1488
|
+
operation,
|
|
1489
|
+
hash,
|
|
1490
|
+
ref: `${file}@${landed.offset}+${landed.bytes}`,
|
|
1491
|
+
detail: { offset: landed.offset, bytes: landed.bytes, block: landed.block },
|
|
1492
|
+
});
|
|
1493
|
+
if (intent !== undefined) {
|
|
1494
|
+
const have = fs.existsSync(abs) ? fs.readFileSync(abs) : Buffer.alloc(0);
|
|
1495
|
+
const want = Buffer.from(intent.block);
|
|
1496
|
+
const seg = have.subarray(intent.offset, intent.offset + want.length);
|
|
1497
|
+
if (seg.equals(want)) {
|
|
1498
|
+
// The bytes landed whole; confirm them durable and receipt them.
|
|
1499
|
+
const fd = fs.openSync(abs, "r");
|
|
1500
|
+
try {
|
|
1501
|
+
fs.fsyncSync(fd);
|
|
1502
|
+
}
|
|
1503
|
+
finally {
|
|
1504
|
+
fs.closeSync(fd);
|
|
1505
|
+
}
|
|
1506
|
+
receipt(intent);
|
|
1507
|
+
options.checkpoint?.("receipted");
|
|
1508
|
+
return result(intent, intent.block, true);
|
|
1509
|
+
}
|
|
1510
|
+
// Whole lines decide "landed": rows share a byte prefix (`{"schema":3,"ts":...`), so a
|
|
1511
|
+
// foreign row is told apart by being a complete line that differs from ours.
|
|
1512
|
+
// Compare by content, without the newline and without one leading separator newline:
|
|
1513
|
+
// a torn prefix of our line that a later writer completed with its own newline is a
|
|
1514
|
+
// proper prefix of our first line, so it stays uncertain rather than foreign.
|
|
1515
|
+
const stripSeparator = (b) => (b[0] === 0x0a ? b.subarray(1) : b);
|
|
1516
|
+
const firstLine = (b) => {
|
|
1517
|
+
const nl = b.indexOf(0x0a);
|
|
1518
|
+
return nl < 0
|
|
1519
|
+
? { line: b, complete: false }
|
|
1520
|
+
: { line: b.subarray(0, nl), complete: true };
|
|
1521
|
+
};
|
|
1522
|
+
const wantLine = firstLine(stripSeparator(want)).line;
|
|
1523
|
+
const haveLine = firstLine(stripSeparator(have.subarray(intent.offset)));
|
|
1524
|
+
const foreignWholeLine = haveLine.complete &&
|
|
1525
|
+
!(haveLine.line.length <= wantLine.length &&
|
|
1526
|
+
wantLine.subarray(0, haveLine.line.length).equals(haveLine.line));
|
|
1527
|
+
let landedBytes = 0;
|
|
1528
|
+
while (landedBytes < seg.length &&
|
|
1529
|
+
landedBytes < want.length &&
|
|
1530
|
+
seg[landedBytes] === want[landedBytes])
|
|
1531
|
+
landedBytes++;
|
|
1532
|
+
if (!foreignWholeLine &&
|
|
1533
|
+
(landedBytes > 0 || (seg.length > 0 && have.length === intent.offset + seg.length)))
|
|
1534
|
+
throw new UncertainEffect(EXIT_STAGE, `operation ${operation}: ${file} holds ${landedBytes} of ${want.length} prepared bytes at the recorded offset; the effect is uncertain, nothing was truncated or retried`);
|
|
1535
|
+
if (have.length === intent.offset) {
|
|
1536
|
+
// Nothing landed: write the exact prepared bytes again.
|
|
1537
|
+
writePrepared(abs, intent.block, intent.offset);
|
|
1538
|
+
options.checkpoint?.("written");
|
|
1539
|
+
receipt(intent);
|
|
1540
|
+
options.checkpoint?.("receipted");
|
|
1541
|
+
return result(intent, intent.block, false);
|
|
1542
|
+
}
|
|
1543
|
+
// Another writer appended after the failed attempt and none of ours landed: prepare afresh.
|
|
1544
|
+
}
|
|
1545
|
+
const landed = appendHeld(abs, build, {
|
|
1546
|
+
checkpoint: options.checkpoint,
|
|
1547
|
+
prepared: (p) => recordLedgerIntent(ops, {
|
|
1548
|
+
operation,
|
|
1549
|
+
hash,
|
|
1550
|
+
file,
|
|
1551
|
+
offset: p.offset,
|
|
1552
|
+
bytes: Buffer.byteLength(p.block),
|
|
1553
|
+
block: p.block,
|
|
1554
|
+
}),
|
|
1555
|
+
written: (p) => receipt(p),
|
|
1556
|
+
});
|
|
1557
|
+
return result(landed, landed.block, false);
|
|
1558
|
+
});
|
|
1559
|
+
});
|
|
1125
1560
|
}
|
|
1126
|
-
|
|
1127
|
-
|
|
1128
|
-
fs.closeSync(fd);
|
|
1561
|
+
catch (err) {
|
|
1562
|
+
throw stage(err);
|
|
1129
1563
|
}
|
|
1130
1564
|
}
|
|
1131
1565
|
function append(ctx) {
|
|
@@ -1140,9 +1574,172 @@ function append(ctx) {
|
|
|
1140
1574
|
const parsed = parseJson(text);
|
|
1141
1575
|
if (!parsed.ok)
|
|
1142
1576
|
throw new CommandError(EXIT.USAGE, "--rows is not JSON");
|
|
1143
|
-
const
|
|
1144
|
-
|
|
1145
|
-
|
|
1577
|
+
const bound = ctx.invocation?.bookRoot;
|
|
1578
|
+
if (bound !== undefined && bound !== null && bound !== root)
|
|
1579
|
+
throw new CommandError(EXIT.USAGE, `conflict: --root ${root} is not the invocation's book root ${bound}`);
|
|
1580
|
+
// A runless call has no book root of its own: its output scope is the checkout that issued it.
|
|
1581
|
+
if (ctx.invocation?.scope === "outbox") {
|
|
1582
|
+
const rel = path.relative(ctx.invocation.worktree, root);
|
|
1583
|
+
if (rel.startsWith("..") || path.isAbsolute(rel))
|
|
1584
|
+
throw new CommandError(EXIT.USAGE, `conflict: --root ${root} is outside the checkout ${ctx.invocation.worktree} that issued invocation ${ctx.invocation.id}`);
|
|
1585
|
+
}
|
|
1586
|
+
const ledger = String(ctx.flags.ledger);
|
|
1587
|
+
const request = {
|
|
1588
|
+
operation: str(ctx.flags.operation),
|
|
1589
|
+
issueOperation: ctx.flags.issueOperation === true,
|
|
1590
|
+
};
|
|
1591
|
+
const run = ctx.invocation;
|
|
1592
|
+
const scope = run === undefined ? null : appendCorrectionScope(run, ledger);
|
|
1593
|
+
const operation = appendOperationId(ledger, parsed.value, run, request);
|
|
1594
|
+
const correctionOf = str(ctx.flags.correctionOf);
|
|
1595
|
+
let spend;
|
|
1596
|
+
const book = run === undefined || scope === null ? null : correctionBook(ctx.cwd, run);
|
|
1597
|
+
if (correctionOf !== undefined) {
|
|
1598
|
+
if (run === undefined || scope === null || book === null)
|
|
1599
|
+
throw new CommandError(EXIT.USAGE, "--correction-of needs an --invocation with a correction scope: a workflow-run call, or a standalone audit or utility call");
|
|
1600
|
+
if (operation === undefined || operation === correctionOf)
|
|
1601
|
+
throw new CommandError(EXIT.USAGE, "--correction-of needs a fresh --operation or --issue-operation: a corrected candidate has its own operation id");
|
|
1602
|
+
const rejected = readStatusRows(book.file).some((row) => row.type === CORRECTION_REJECTED_ROW &&
|
|
1603
|
+
row.operation === correctionOf &&
|
|
1604
|
+
row.scope === scope &&
|
|
1605
|
+
row.workflow === book.workflow);
|
|
1606
|
+
if (!rejected)
|
|
1607
|
+
throw new CommandError(EXIT.USAGE, `--correction-of=${correctionOf} names no rejected ${ledger} append in this step; only a guaranteed no-write rejection of this sub-step can be corrected`);
|
|
1608
|
+
// An earlier operation on this ledger whose effect is unconfirmed is reconciled first.
|
|
1609
|
+
const target = Object.hasOwn(APPEND_LEDGERS, ledger)
|
|
1610
|
+
? APPEND_LEDGERS[ledger].file
|
|
1611
|
+
: undefined;
|
|
1612
|
+
if (target !== undefined && pendingLedgerIntentsFor(root, target).length > 0)
|
|
1613
|
+
throw new UncertainEffect(EXIT_STAGE, `${target} holds an operation whose effect is unconfirmed; reconcile it before any corrected candidate — nothing was written`);
|
|
1614
|
+
spend = spendCorrection(book.file, book.workflow, scope, operation, CORRECTION_LIMIT, {
|
|
1615
|
+
of: correctionOf,
|
|
1616
|
+
step: book.step,
|
|
1617
|
+
substep: "append",
|
|
1618
|
+
requestHash: actionHash(canonicalJson({ ledger, rows: parsed.value })),
|
|
1619
|
+
});
|
|
1620
|
+
if (!spend.allowed)
|
|
1621
|
+
throw new CorrectionExhausted(EXIT.NO, spend.conflict === true
|
|
1622
|
+
? `operation ${operation} was already counted as a correction of ${scope} for different rows; a changed candidate needs a fresh operation id and spends the budget (${spend.used} of ${spend.limit}); nothing was written`
|
|
1623
|
+
: `the correction budget of ${scope} is spent (${spend.used} of ${spend.limit}); nothing was written`, scope);
|
|
1624
|
+
}
|
|
1625
|
+
let r;
|
|
1626
|
+
try {
|
|
1627
|
+
r = appendLedgerRows(root, ledger, parsed.value, ctx.invocation, request);
|
|
1628
|
+
}
|
|
1629
|
+
catch (err) {
|
|
1630
|
+
if (err instanceof NoWriteRejection && book !== null && operation !== undefined) {
|
|
1631
|
+
fs.appendFileSync(book.file, appendLine({
|
|
1632
|
+
type: CORRECTION_REJECTED_ROW,
|
|
1633
|
+
workflow: book.workflow,
|
|
1634
|
+
at: statusTimestamp(),
|
|
1635
|
+
scope: err.detail.scope,
|
|
1636
|
+
substep: err.detail.substep,
|
|
1637
|
+
operation,
|
|
1638
|
+
step: book.step,
|
|
1639
|
+
}));
|
|
1640
|
+
// The last allowed retry was just used: the rejection is final, not correctable.
|
|
1641
|
+
if (spend !== undefined && spend.remaining === 0)
|
|
1642
|
+
throw new CommandError(err.code, err.message);
|
|
1643
|
+
}
|
|
1644
|
+
throw err;
|
|
1645
|
+
}
|
|
1646
|
+
ctx.log(r.receipt?.replayed === true
|
|
1647
|
+
? `operation ${r.receipt.operation} already appended to ${r.file}; nothing written`
|
|
1648
|
+
: `appended ${r.appended} row(s) to ${r.file}`);
|
|
1649
|
+
if (spend === undefined || book === null || scope === null) {
|
|
1650
|
+
ctx.emit({ ...r });
|
|
1651
|
+
return EXIT.OK;
|
|
1652
|
+
}
|
|
1653
|
+
const verified = r.receipt?.replayed === true || r.appended === parsed.value.length;
|
|
1654
|
+
const succeeded = readStatusRows(book.file).some((row) => row.type === CORRECTION_SUCCEEDED_ROW && row.operation === operation);
|
|
1655
|
+
if (verified && !succeeded)
|
|
1656
|
+
fs.appendFileSync(book.file, appendLine({
|
|
1657
|
+
type: CORRECTION_SUCCEEDED_ROW,
|
|
1658
|
+
workflow: book.workflow,
|
|
1659
|
+
at: statusTimestamp(),
|
|
1660
|
+
scope,
|
|
1661
|
+
substep: "append",
|
|
1662
|
+
operation,
|
|
1663
|
+
of: correctionOf,
|
|
1664
|
+
step: book.step,
|
|
1665
|
+
}));
|
|
1666
|
+
ctx.emit({
|
|
1667
|
+
...r,
|
|
1668
|
+
correction: {
|
|
1669
|
+
scope,
|
|
1670
|
+
operation,
|
|
1671
|
+
of: correctionOf,
|
|
1672
|
+
used: spend.used,
|
|
1673
|
+
limit: spend.limit,
|
|
1674
|
+
substep: "append",
|
|
1675
|
+
verified,
|
|
1676
|
+
},
|
|
1677
|
+
});
|
|
1678
|
+
return EXIT.OK;
|
|
1679
|
+
}
|
|
1680
|
+
/** Page cursor: the snapshot and filter it was cut from, and the offset of the next row. */
|
|
1681
|
+
function encodeCursor(c) {
|
|
1682
|
+
return Buffer.from(JSON.stringify(c)).toString("base64url");
|
|
1683
|
+
}
|
|
1684
|
+
function decodeCursor(text) {
|
|
1685
|
+
const parsed = parseJson(Buffer.from(text, "base64url").toString("utf-8"));
|
|
1686
|
+
if (!parsed.ok || parsed.value === null || typeof parsed.value !== "object")
|
|
1687
|
+
return null;
|
|
1688
|
+
const v = parsed.value;
|
|
1689
|
+
return typeof v["s"] === "string" && typeof v["f"] === "string" && Number.isInteger(v["o"])
|
|
1690
|
+
? { s: v["s"], f: v["f"], o: v["o"] }
|
|
1691
|
+
: null;
|
|
1692
|
+
}
|
|
1693
|
+
function query(ctx) {
|
|
1694
|
+
const root = rootOf(ctx);
|
|
1695
|
+
const ledger = String(ctx.flags.ledger);
|
|
1696
|
+
if (!Object.hasOwn(APPEND_LEDGERS, ledger)) {
|
|
1697
|
+
throw new CommandError(EXIT.USAGE, `--ledger must be one of ${Object.keys(APPEND_LEDGERS).join(", ")} (got '${ledger}')`);
|
|
1698
|
+
}
|
|
1699
|
+
const { file } = APPEND_LEDGERS[ledger];
|
|
1700
|
+
const filter = { key: str(ctx.flags.key), status: str(ctx.flags.status) };
|
|
1701
|
+
const limit = wholeNumber(ctx.flags.limit, "limit", QUERY_PAGE, 1);
|
|
1702
|
+
const filterId = JSON.stringify([filter.key ?? null, filter.status ?? null]);
|
|
1703
|
+
const cursorText = str(ctx.flags.cursor);
|
|
1704
|
+
const cursor = cursorText === undefined ? null : decodeCursor(cursorText);
|
|
1705
|
+
if (cursorText !== undefined && cursor === null)
|
|
1706
|
+
throw new CommandError(EXIT.USAGE, "--cursor is not a cursor from this command");
|
|
1707
|
+
const abs = path.join(root, file);
|
|
1708
|
+
const read = readText(abs);
|
|
1709
|
+
const missing = !read.ok && !fs.existsSync(abs);
|
|
1710
|
+
const raw = read.ok ? read.text : "";
|
|
1711
|
+
const snapshot = createHash("sha256").update(raw).digest("hex").slice(0, 16);
|
|
1712
|
+
if (cursor !== null && (cursor.s !== snapshot || cursor.f !== filterId))
|
|
1713
|
+
throw new CommandError(EXIT.USAGE, "stale cursor: the ledger or the filter changed since this scan began; start again without --cursor");
|
|
1714
|
+
const result = queryLedger(raw, filter);
|
|
1715
|
+
const offset = cursor?.o ?? 0;
|
|
1716
|
+
const page = result.rows.slice(offset, offset + limit);
|
|
1717
|
+
const next = offset + limit < result.rows.length ? offset + limit : null;
|
|
1718
|
+
const status = missing
|
|
1719
|
+
? "missing"
|
|
1720
|
+
: !read.ok
|
|
1721
|
+
? "unreadable"
|
|
1722
|
+
: result.diagnostics.length > 0
|
|
1723
|
+
? "partial"
|
|
1724
|
+
: next !== null
|
|
1725
|
+
? "incomplete"
|
|
1726
|
+
: "clean";
|
|
1727
|
+
ctx.emit({
|
|
1728
|
+
ledger,
|
|
1729
|
+
file,
|
|
1730
|
+
rows: page,
|
|
1731
|
+
nextCursor: next === null ? null : encodeCursor({ s: snapshot, f: filterId, o: next }),
|
|
1732
|
+
snapshot,
|
|
1733
|
+
total: result.rows.length,
|
|
1734
|
+
diagnostics: result.diagnostics,
|
|
1735
|
+
coverage: {
|
|
1736
|
+
status,
|
|
1737
|
+
clean: status === "clean",
|
|
1738
|
+
malformedLines: result.diagnostics.length,
|
|
1739
|
+
lines: result.lines,
|
|
1740
|
+
...(!read.ok && !missing ? { error: read.error } : {}),
|
|
1741
|
+
},
|
|
1742
|
+
});
|
|
1146
1743
|
return EXIT.OK;
|
|
1147
1744
|
}
|
|
1148
1745
|
const LEDGER_ROWS_LINE = /^\*\*Ledger rows:\*\*(.*)$/m;
|
|
@@ -1156,16 +1753,32 @@ export function checkPlanRows(root, plan) {
|
|
|
1156
1753
|
const abs = path.resolve(root, plan);
|
|
1157
1754
|
if (!fs.existsSync(abs))
|
|
1158
1755
|
throw new CommandError(EXIT.USAGE, `--plan not found: ${plan}`);
|
|
1159
|
-
const
|
|
1160
|
-
|
|
1161
|
-
|
|
1162
|
-
|
|
1756
|
+
const r = readPlanRows(root, fs.readFileSync(abs, "utf-8"));
|
|
1757
|
+
if (r.unreadable !== undefined)
|
|
1758
|
+
throw new CommandError(EXIT_ROWS_MISSING, `${plan}: ${r.unreadable}`);
|
|
1759
|
+
return { keys: r.keys, missing: r.missing };
|
|
1760
|
+
}
|
|
1761
|
+
/**
|
|
1762
|
+
* Read `text`'s `**Ledger rows:**` line and the keys no `decision` / `deferral`
|
|
1763
|
+
* row under `root` carries. An absent or placeholder line is `unreadable`.
|
|
1764
|
+
*/
|
|
1765
|
+
export function readPlanRows(root, text) {
|
|
1766
|
+
const match = LEDGER_ROWS_LINE.exec(text);
|
|
1767
|
+
const line = match?.[1]?.trim();
|
|
1768
|
+
if (match === null || line === undefined) {
|
|
1769
|
+
return { line: 0, keys: [], missing: [], unreadable: "no **Ledger rows:** line" };
|
|
1163
1770
|
}
|
|
1771
|
+
const at = text.slice(0, match.index).split("\n").length;
|
|
1164
1772
|
const keys = [...line.matchAll(/`([^`]+)`/g)].map((m) => m[1] ?? "");
|
|
1165
1773
|
if (keys.length === 0) {
|
|
1166
1774
|
if (line.replace(/[."\s]/g, "") === "None")
|
|
1167
|
-
return { keys: [], missing: [] };
|
|
1168
|
-
|
|
1775
|
+
return { line: at, keys: [], missing: [] };
|
|
1776
|
+
return {
|
|
1777
|
+
line: at,
|
|
1778
|
+
keys: [],
|
|
1779
|
+
missing: [],
|
|
1780
|
+
unreadable: `**Ledger rows:** is unfilled (${line})`,
|
|
1781
|
+
};
|
|
1169
1782
|
}
|
|
1170
1783
|
const onDisk = new Set();
|
|
1171
1784
|
for (const { file, kinds } of CHECKED_LEDGERS) {
|
|
@@ -1178,7 +1791,7 @@ export function checkPlanRows(root, plan) {
|
|
|
1178
1791
|
onDisk.add(key);
|
|
1179
1792
|
}
|
|
1180
1793
|
}
|
|
1181
|
-
return { keys, missing: keys.filter((k) => !onDisk.has(k)) };
|
|
1794
|
+
return { line: at, keys, missing: keys.filter((k) => !onDisk.has(k)) };
|
|
1182
1795
|
}
|
|
1183
1796
|
function check(ctx) {
|
|
1184
1797
|
const root = rootOf(ctx);
|
|
@@ -1224,18 +1837,19 @@ function mkdirp(dir) {
|
|
|
1224
1837
|
/** {@link compactLedgers}; its results, or the error text. A failed temp write or rename leaves the ledger untouched. */
|
|
1225
1838
|
function compactOrError(root, ledgers, dryRun) {
|
|
1226
1839
|
try {
|
|
1227
|
-
|
|
1228
|
-
|
|
1229
|
-
|
|
1230
|
-
|
|
1231
|
-
|
|
1232
|
-
|
|
1233
|
-
}
|
|
1234
|
-
|
|
1235
|
-
|
|
1236
|
-
|
|
1237
|
-
|
|
1238
|
-
|
|
1840
|
+
const targets = ledgers.map((l) => COMPACT_LEDGERS[l]).sort();
|
|
1841
|
+
const locked = (i) => {
|
|
1842
|
+
if (i === targets.length) {
|
|
1843
|
+
for (const t of targets) {
|
|
1844
|
+
const pending = pendingLedgerIntentsFor(root, t);
|
|
1845
|
+
if (pending.length > 0)
|
|
1846
|
+
throw new Error(`${t} has ${pending.length} ledger operation(s) with bytes but no receipt (${pending.map((p) => p.operation).join(", ")}); replay them before compacting`);
|
|
1847
|
+
}
|
|
1848
|
+
return compactLedgers(root, ledgers, dryRun);
|
|
1849
|
+
}
|
|
1850
|
+
return withTargetLock(path.join(root, targets[i]), () => locked(i + 1));
|
|
1851
|
+
};
|
|
1852
|
+
return locked(0);
|
|
1239
1853
|
}
|
|
1240
1854
|
catch (err) {
|
|
1241
1855
|
// Reported as the command's staging exit code, with the reason.
|