@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
|
@@ -10,6 +10,7 @@
|
|
|
10
10
|
// everything already in the index, not nothing.
|
|
11
11
|
|
|
12
12
|
import { spawnSync } from "node:child_process";
|
|
13
|
+
import { createHash } from "node:crypto";
|
|
13
14
|
import * as fs from "node:fs";
|
|
14
15
|
import * as os from "node:os";
|
|
15
16
|
import * as path from "node:path";
|
|
@@ -22,6 +23,7 @@ import {
|
|
|
22
23
|
UNJUSTIFIED_REASON,
|
|
23
24
|
gitEnv,
|
|
24
25
|
parse,
|
|
26
|
+
queryLedger,
|
|
25
27
|
mintTs,
|
|
26
28
|
resolveRepoSlug,
|
|
27
29
|
validate,
|
|
@@ -30,17 +32,43 @@ import {
|
|
|
30
32
|
type AppendLedger,
|
|
31
33
|
} from "../../ledgers/telemetry.js";
|
|
32
34
|
import { COMPACT_LEDGERS, compactLedgers, type CompactLedger } from "../../ledgers/compact.js";
|
|
35
|
+
import {
|
|
36
|
+
CORRECTION_REJECTED_ROW,
|
|
37
|
+
CORRECTION_SUCCEEDED_ROW,
|
|
38
|
+
actionHash,
|
|
39
|
+
appendHeld,
|
|
40
|
+
appendLine,
|
|
41
|
+
correctionScope,
|
|
42
|
+
ledgerIntent,
|
|
43
|
+
ledgerOperation,
|
|
44
|
+
ledgerOperationsFile,
|
|
45
|
+
pendingLedgerIntentsFor,
|
|
46
|
+
recordLedgerIntent,
|
|
47
|
+
recordLedgerOperation,
|
|
48
|
+
statusTimestamp,
|
|
49
|
+
withTargetLock,
|
|
50
|
+
writePrepared,
|
|
51
|
+
type AppendCheckpoint,
|
|
52
|
+
} from "../../ledgers/status.js";
|
|
33
53
|
import {
|
|
34
54
|
CommandError,
|
|
55
|
+
CorrectionExhausted,
|
|
35
56
|
EXIT,
|
|
57
|
+
INVOCATION_FLAG,
|
|
58
|
+
invocationDir,
|
|
36
59
|
isIgnoredPath,
|
|
37
60
|
isSharedBranch,
|
|
61
|
+
NoWriteRejection,
|
|
38
62
|
parseJson,
|
|
63
|
+
UncertainEffect,
|
|
64
|
+
wholeNumber,
|
|
39
65
|
type CommandSpec,
|
|
40
66
|
type FlagSpec,
|
|
67
|
+
type Invocation,
|
|
41
68
|
type RunContext,
|
|
42
69
|
} from "../lib.js";
|
|
43
|
-
import {
|
|
70
|
+
import { CORRECTION_LIMIT, spendCorrection, type CorrectionSpend } from "./counters.js";
|
|
71
|
+
import { readStatusRows, str } from "./status.js";
|
|
44
72
|
import {
|
|
45
73
|
NO_MARKERS_REASON,
|
|
46
74
|
outOfScope,
|
|
@@ -62,6 +90,9 @@ export const EXIT_NOT_BOOKKEEPING = 7;
|
|
|
62
90
|
/** append: a row was refused (supplied `ts`, wrong kind, invalid, unlisted writer). */
|
|
63
91
|
export const EXIT_ROW_REFUSED = 8;
|
|
64
92
|
|
|
93
|
+
/** Rows per `ledgers query` page unless --limit says otherwise. */
|
|
94
|
+
const QUERY_PAGE = 200;
|
|
95
|
+
|
|
65
96
|
const SCOPES = ["core", "full", "pr"] as const;
|
|
66
97
|
export type Scope = (typeof SCOPES)[number];
|
|
67
98
|
const MODES = ["stage", "commit", "commit-allow-empty"];
|
|
@@ -135,7 +166,7 @@ interface GitResult {
|
|
|
135
166
|
}
|
|
136
167
|
|
|
137
168
|
/** `git <args>` in `cwd`, never throwing and never trimming (NUL-delimited output). */
|
|
138
|
-
function gitRaw(
|
|
169
|
+
export function gitRaw(
|
|
139
170
|
cwd: string,
|
|
140
171
|
args: string[],
|
|
141
172
|
env: NodeJS.ProcessEnv = {},
|
|
@@ -250,6 +281,8 @@ export interface SharedCheckoutRecord {
|
|
|
250
281
|
}
|
|
251
282
|
|
|
252
283
|
const RECORD_DIR = "bkit/shared-checkout";
|
|
284
|
+
/** Where a stopped run's commit list is parked: a directory the record listing never reads. */
|
|
285
|
+
const PARKED_DIR = "bkit/shared-checkout-parked";
|
|
253
286
|
const RECORD_FID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
|
|
254
287
|
|
|
255
288
|
/** The checkout's top: git status and pathspecs are relative to it, whatever `cwd` is. */
|
|
@@ -368,6 +401,120 @@ export function removeRecord(cwd: string, fid: string): boolean {
|
|
|
368
401
|
return true;
|
|
369
402
|
}
|
|
370
403
|
|
|
404
|
+
/** `$(git rev-parse --git-path bkit/shared-checkout-parked/{fid}.json)`, absolute; null for a bad FID or outside a repo. */
|
|
405
|
+
function parkedFile(cwd: string, fid: string): string | null {
|
|
406
|
+
if (!RECORD_FID.test(fid) || fid.includes("..")) return null;
|
|
407
|
+
const res = gitRaw(cwd, ["rev-parse", "--git-path", `${PARKED_DIR}/${fid}.json`]);
|
|
408
|
+
return res.status === 0 && res.stdout.trim() !== "" ? path.resolve(cwd, res.stdout.trim()) : null;
|
|
409
|
+
}
|
|
410
|
+
|
|
411
|
+
/**
|
|
412
|
+
* Park `rec`'s start, commits and pushed list for `workflow` in this clone's git dir, so a
|
|
413
|
+
* resume of a run that stays open can rebuild its record without any remote.
|
|
414
|
+
*/
|
|
415
|
+
export function writeParkedCommits(cwd: string, workflow: string, rec: SharedCheckoutRecord): void {
|
|
416
|
+
const file = parkedFile(cwd, rec.fid);
|
|
417
|
+
if (file === null) throw new CommandError(EXIT_ROOT, `cannot park commits for "${rec.fid}"`);
|
|
418
|
+
fs.mkdirSync(path.dirname(file), { recursive: true });
|
|
419
|
+
const parked = {
|
|
420
|
+
workflow,
|
|
421
|
+
at: statusTimestamp(),
|
|
422
|
+
startSha: rec.startSha,
|
|
423
|
+
commits: rec.commits,
|
|
424
|
+
pushed: rec.pushed ?? [],
|
|
425
|
+
};
|
|
426
|
+
fs.writeFileSync(file, `${JSON.stringify(parked, null, 2)}\n`);
|
|
427
|
+
}
|
|
428
|
+
|
|
429
|
+
/** The FID's parked commit list for `workflow`; null when absent, unreadable or parked for another workflow. */
|
|
430
|
+
export function readParkedCommits(cwd: string, fid: string, workflow: string): RunCommits | null {
|
|
431
|
+
const file = parkedFile(cwd, fid);
|
|
432
|
+
if (file === null || !fs.existsSync(file)) return null;
|
|
433
|
+
const parsed = parseJson(fs.readFileSync(file, "utf-8"));
|
|
434
|
+
if (!parsed.ok || parsed.value === null || typeof parsed.value !== "object") return null;
|
|
435
|
+
const p = parsed.value as Record<string, unknown>;
|
|
436
|
+
if (p["workflow"] !== workflow) return null;
|
|
437
|
+
const ids = (v: unknown) =>
|
|
438
|
+
Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : [];
|
|
439
|
+
return {
|
|
440
|
+
startSha: typeof p["startSha"] === "string" ? p["startSha"] : "",
|
|
441
|
+
commits: ids(p["commits"]),
|
|
442
|
+
pushed: ids(p["pushed"]),
|
|
443
|
+
};
|
|
444
|
+
}
|
|
445
|
+
|
|
446
|
+
/** Remove the FID's parked commit list; false when there was none. */
|
|
447
|
+
export function removeParkedCommits(cwd: string, fid: string): boolean {
|
|
448
|
+
const file = parkedFile(cwd, fid);
|
|
449
|
+
if (file === null || !fs.existsSync(file)) return false;
|
|
450
|
+
fs.rmSync(file, { force: true });
|
|
451
|
+
return true;
|
|
452
|
+
}
|
|
453
|
+
|
|
454
|
+
/** The status row type that carries a run's commit list across the removal of its record. */
|
|
455
|
+
export const RUN_COMMITS_ROW = "run-commits";
|
|
456
|
+
|
|
457
|
+
/** What a `run-commits` row holds: the record fields a resumed run rebuilds its record from. */
|
|
458
|
+
export interface RunCommits {
|
|
459
|
+
startSha: string;
|
|
460
|
+
commits: string[];
|
|
461
|
+
pushed: string[];
|
|
462
|
+
}
|
|
463
|
+
|
|
464
|
+
/** Append a `run-commits` row for `rec` to the status log `file`. */
|
|
465
|
+
export function appendRunCommits(file: string, workflow: string, rec: SharedCheckoutRecord): void {
|
|
466
|
+
fs.appendFileSync(
|
|
467
|
+
file,
|
|
468
|
+
appendLine({
|
|
469
|
+
type: RUN_COMMITS_ROW,
|
|
470
|
+
workflow,
|
|
471
|
+
at: statusTimestamp(),
|
|
472
|
+
startSha: rec.startSha,
|
|
473
|
+
commits: rec.commits,
|
|
474
|
+
pushed: rec.pushed ?? [],
|
|
475
|
+
}),
|
|
476
|
+
);
|
|
477
|
+
}
|
|
478
|
+
|
|
479
|
+
/**
|
|
480
|
+
* The newest `run-commits` row of `workflow`'s open run in the status log `file`. Null
|
|
481
|
+
* when the log or the row is missing.
|
|
482
|
+
*/
|
|
483
|
+
export function readRunCommits(file: string, workflow: string): RunCommits | null {
|
|
484
|
+
if (!fs.existsSync(file)) return null;
|
|
485
|
+
return runCommitsIn(fs.readFileSync(file, "utf-8"), workflow);
|
|
486
|
+
}
|
|
487
|
+
|
|
488
|
+
/**
|
|
489
|
+
* The newest `run-commits` row of `workflow` in the status log `text`, among the rows after
|
|
490
|
+
* the last `workflow-started` row of that workflow, in file order. Null when there is none;
|
|
491
|
+
* a line that is not a JSON object is skipped.
|
|
492
|
+
*/
|
|
493
|
+
export function runCommitsIn(text: string, workflow: string): RunCommits | null {
|
|
494
|
+
const rows = text
|
|
495
|
+
.split("\n")
|
|
496
|
+
.flatMap((line) => {
|
|
497
|
+
const parsed = parseJson(line);
|
|
498
|
+
return parsed.ok && parsed.value !== null && typeof parsed.value === "object"
|
|
499
|
+
? [parsed.value as Record<string, unknown>]
|
|
500
|
+
: [];
|
|
501
|
+
})
|
|
502
|
+
.filter((row) => row["workflow"] === workflow);
|
|
503
|
+
const opened = rows.map((row) => row["type"]).lastIndexOf("workflow-started");
|
|
504
|
+
const row = rows
|
|
505
|
+
.slice(opened + 1)
|
|
506
|
+
.filter((r) => r["type"] === RUN_COMMITS_ROW)
|
|
507
|
+
.at(-1);
|
|
508
|
+
if (row === undefined) return null;
|
|
509
|
+
const ids = (v: unknown) =>
|
|
510
|
+
Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : [];
|
|
511
|
+
return {
|
|
512
|
+
startSha: typeof row["startSha"] === "string" ? row["startSha"] : "",
|
|
513
|
+
commits: ids(row["commits"]),
|
|
514
|
+
pushed: ids(row["pushed"]),
|
|
515
|
+
};
|
|
516
|
+
}
|
|
517
|
+
|
|
371
518
|
/** The FID's record, only while its branch is still the one checked out. */
|
|
372
519
|
export function activeRecord(cwd: string, fid: string): SharedCheckoutRecord | null {
|
|
373
520
|
const rec = readRecord(cwd, fid);
|
|
@@ -806,20 +953,82 @@ export const ledgersCommand: CommandSpec = {
|
|
|
806
953
|
required: true,
|
|
807
954
|
help: "file holding a JSON array of rows without schema, ts or bkit, or - for stdin",
|
|
808
955
|
},
|
|
956
|
+
{
|
|
957
|
+
...INVOCATION_FLAG,
|
|
958
|
+
help: `${INVOCATION_FLAG.help}; fills each row's by block (workflow, step, subagent, model, provenance) and refuses a row whose own by disagrees`,
|
|
959
|
+
},
|
|
960
|
+
{
|
|
961
|
+
name: "operation",
|
|
962
|
+
type: "string",
|
|
963
|
+
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",
|
|
964
|
+
},
|
|
965
|
+
{
|
|
966
|
+
name: "issue-operation",
|
|
967
|
+
type: "boolean",
|
|
968
|
+
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",
|
|
969
|
+
},
|
|
970
|
+
{
|
|
971
|
+
name: "correction-of",
|
|
972
|
+
type: "string",
|
|
973
|
+
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",
|
|
974
|
+
},
|
|
809
975
|
],
|
|
810
976
|
output: {
|
|
811
977
|
ledger: "the ledger appended to",
|
|
812
978
|
file: "its path, relative to --root",
|
|
813
979
|
appended: "rows written",
|
|
814
980
|
keys: "each row's key, in order (null when a row has none)",
|
|
981
|
+
receipt:
|
|
982
|
+
"with --operation: {operation, ledger, file, offset, bytes, rows[{key, ts}], replayed}; replayed is true when the original effect is returned",
|
|
983
|
+
correction:
|
|
984
|
+
"with --correction-of: {scope, operation, of, used, limit, substep, verified}; verified is true when the rows landed (or the original receipt was returned)",
|
|
815
985
|
},
|
|
816
986
|
exitCodes: {
|
|
817
|
-
[EXIT_STAGE]:
|
|
987
|
+
[EXIT_STAGE]:
|
|
988
|
+
"mkdir or append failed, the ledger is locked by another writer, or a prior attempt left an uncertain partial write",
|
|
818
989
|
[EXIT_ROW_REFUSED]:
|
|
819
990
|
"a row carries ts, has the wrong kind, fails validation, or names a writer not listed for its kind — nothing written",
|
|
820
991
|
},
|
|
821
992
|
run: (ctx) => append(ctx),
|
|
822
993
|
},
|
|
994
|
+
query: {
|
|
995
|
+
summary:
|
|
996
|
+
"Read one ledger's canonical winners (filtered after the fold), paged, with line diagnostics and coverage. Writes nothing.",
|
|
997
|
+
use: "by-hand",
|
|
998
|
+
flags: [
|
|
999
|
+
{ name: "root", type: "string", help: "checkout whose ledger to read (default: cwd)" },
|
|
1000
|
+
{
|
|
1001
|
+
name: "ledger",
|
|
1002
|
+
type: "string",
|
|
1003
|
+
required: true,
|
|
1004
|
+
help: Object.keys(APPEND_LEDGERS).join(" | "),
|
|
1005
|
+
},
|
|
1006
|
+
{ name: "key", type: "string", help: "only the winner with this key" },
|
|
1007
|
+
{ name: "status", type: "string", help: "only winners whose status is this (e.g. ACTIVE)" },
|
|
1008
|
+
{
|
|
1009
|
+
name: "limit",
|
|
1010
|
+
type: "string",
|
|
1011
|
+
help: `rows per page (default ${QUERY_PAGE}, at least 1)`,
|
|
1012
|
+
},
|
|
1013
|
+
{
|
|
1014
|
+
name: "cursor",
|
|
1015
|
+
type: "string",
|
|
1016
|
+
help: "nextCursor of the previous page; refused when the ledger or the filter changed",
|
|
1017
|
+
},
|
|
1018
|
+
],
|
|
1019
|
+
output: {
|
|
1020
|
+
ledger: "the ledger read",
|
|
1021
|
+
file: "its path, relative to --root",
|
|
1022
|
+
rows: "this page of fold winners, oldest ts first (equal ts by identity)",
|
|
1023
|
+
nextCursor: "pass as --cursor for the next page, or null on the last page",
|
|
1024
|
+
snapshot: "digest of the bytes read; every page of one scan shares it",
|
|
1025
|
+
total: "winners that pass the filter, across all pages",
|
|
1026
|
+
diagnostics: "each unreadable line: {line, reason}; on every page",
|
|
1027
|
+
coverage:
|
|
1028
|
+
"{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",
|
|
1029
|
+
},
|
|
1030
|
+
run: (ctx) => query(ctx),
|
|
1031
|
+
},
|
|
823
1032
|
triage: {
|
|
824
1033
|
summary:
|
|
825
1034
|
"Bucket each deferral row the FID declared by the four Deferral Reason tests, and write the unjustified ones.",
|
|
@@ -1221,14 +1430,23 @@ export function unionLedgers(src: string, dst: string): string[] {
|
|
|
1221
1430
|
const made = mkdirp(path.dirname(to));
|
|
1222
1431
|
if (made) throw new CommandError(EXIT_STAGE, `mkdir failed for ${path.dirname(to)}: ${made}`);
|
|
1223
1432
|
if (fs.existsSync(to) && fs.statSync(to).isFile()) {
|
|
1224
|
-
|
|
1225
|
-
|
|
1226
|
-
|
|
1227
|
-
|
|
1228
|
-
|
|
1229
|
-
|
|
1230
|
-
|
|
1231
|
-
|
|
1433
|
+
// Under the destination's target lock, so a pending ledger operation's bytes are never reordered.
|
|
1434
|
+
withTargetLock(to, () => {
|
|
1435
|
+
const pending = pendingLedgerIntentsFor(dst, rel);
|
|
1436
|
+
if (pending.length > 0)
|
|
1437
|
+
throw new CommandError(
|
|
1438
|
+
EXIT_STAGE,
|
|
1439
|
+
`${rel} has ledger operation(s) with bytes but no receipt (${pending.map((p) => p.operation).join(", ")}); replay them first`,
|
|
1440
|
+
);
|
|
1441
|
+
const existing = fs.readFileSync(to, "utf-8");
|
|
1442
|
+
const have = new Set(fileLines(existing));
|
|
1443
|
+
const fresh = fileLines(fs.readFileSync(from, "utf-8")).filter((l) => !have.has(l));
|
|
1444
|
+
const block = fresh.join("\n").replace(/\n+$/, "");
|
|
1445
|
+
// A destination missing its final newline would glue the first new row
|
|
1446
|
+
// onto its last one, leaving a line that is not JSON.
|
|
1447
|
+
const sep = existing !== "" && !existing.endsWith("\n") ? "\n" : "";
|
|
1448
|
+
if (block !== "") fs.appendFileSync(to, `${sep}${block}\n`);
|
|
1449
|
+
});
|
|
1232
1450
|
} else {
|
|
1233
1451
|
const copied = copy(from, to);
|
|
1234
1452
|
if (copied) throw new CommandError(EXIT_STAGE, `copy failed for ${rel}: ${copied}`);
|
|
@@ -1252,6 +1470,8 @@ export interface AppendResult {
|
|
|
1252
1470
|
file: string;
|
|
1253
1471
|
appended: number;
|
|
1254
1472
|
keys: Array<string | null>;
|
|
1473
|
+
/** Present when the call named an `operation`. */
|
|
1474
|
+
receipt?: LedgerReceipt;
|
|
1255
1475
|
}
|
|
1256
1476
|
|
|
1257
1477
|
/** The top section in its written order, then the row's own fields. */
|
|
@@ -1268,16 +1488,201 @@ const TOP_ORDER = [
|
|
|
1268
1488
|
"references",
|
|
1269
1489
|
];
|
|
1270
1490
|
|
|
1491
|
+
/** A row's `by` block when it is an object, else an empty one. */
|
|
1492
|
+
const byOfRow = (row: Record<string, unknown>): Record<string, unknown> =>
|
|
1493
|
+
row["by"] !== null && typeof row["by"] === "object" && !Array.isArray(row["by"])
|
|
1494
|
+
? (row["by"] as Record<string, unknown>)
|
|
1495
|
+
: {};
|
|
1496
|
+
|
|
1497
|
+
/** The `by` fields an invocation owns; a row may repeat them but never disagree. */
|
|
1498
|
+
const INVOCATION_BY_KEYS = [
|
|
1499
|
+
"workflow",
|
|
1500
|
+
"step",
|
|
1501
|
+
"subagent",
|
|
1502
|
+
"model",
|
|
1503
|
+
"modelSource",
|
|
1504
|
+
"configuredModel",
|
|
1505
|
+
"host",
|
|
1506
|
+
] as const;
|
|
1507
|
+
|
|
1508
|
+
/**
|
|
1509
|
+
* `row` with its `by` block completed from the verified invocation. A field the row
|
|
1510
|
+
* asserts that differs from the invocation's, or that the invocation cannot vouch for,
|
|
1511
|
+
* is refused rather than overwritten. A configured pin is recorded as `configuredModel`
|
|
1512
|
+
* only, never as the model that ran.
|
|
1513
|
+
*/
|
|
1514
|
+
function withInvocationBy(
|
|
1515
|
+
row: Record<string, unknown>,
|
|
1516
|
+
inv: Invocation,
|
|
1517
|
+
refuse: (why: string) => CommandError,
|
|
1518
|
+
): Record<string, unknown> {
|
|
1519
|
+
const unavailable = inv.observedModel === "unavailable";
|
|
1520
|
+
const expected: Record<string, string | undefined> = {
|
|
1521
|
+
workflow: inv.workflow ?? inv.standalone ?? undefined,
|
|
1522
|
+
step: inv.step ?? inv.declaredStep ?? undefined,
|
|
1523
|
+
subagent: inv.agent ?? undefined,
|
|
1524
|
+
model:
|
|
1525
|
+
inv.agent !== null && inv.observedModel !== null && !unavailable
|
|
1526
|
+
? inv.observedModel
|
|
1527
|
+
: undefined,
|
|
1528
|
+
modelSource:
|
|
1529
|
+
inv.agent === null || inv.observedModel === null
|
|
1530
|
+
? undefined
|
|
1531
|
+
: unavailable
|
|
1532
|
+
? "unavailable"
|
|
1533
|
+
: "observed",
|
|
1534
|
+
configuredModel: inv.agent !== null ? (inv.configuredModel ?? undefined) : undefined,
|
|
1535
|
+
host: inv.agent !== null ? (inv.host ?? undefined) : undefined,
|
|
1536
|
+
};
|
|
1537
|
+
const asserted = row["by"];
|
|
1538
|
+
if (
|
|
1539
|
+
asserted !== undefined &&
|
|
1540
|
+
(asserted === null || typeof asserted !== "object" || Array.isArray(asserted))
|
|
1541
|
+
)
|
|
1542
|
+
throw refuse("by must be an object");
|
|
1543
|
+
const by: Record<string, unknown> = { ...(asserted as Record<string, unknown> | undefined) };
|
|
1544
|
+
for (const key of INVOCATION_BY_KEYS) {
|
|
1545
|
+
if (by[key] !== undefined && by[key] !== expected[key]) {
|
|
1546
|
+
throw refuse(
|
|
1547
|
+
`conflict: by.${key}=${JSON.stringify(by[key])} disagrees with invocation ${inv.id} (${expected[key] === undefined ? "none" : JSON.stringify(expected[key])})`,
|
|
1548
|
+
);
|
|
1549
|
+
}
|
|
1550
|
+
if (by[key] === undefined && expected[key] !== undefined) by[key] = expected[key];
|
|
1551
|
+
}
|
|
1552
|
+
return { ...row, by };
|
|
1553
|
+
}
|
|
1554
|
+
|
|
1555
|
+
export interface LedgerReceipt {
|
|
1556
|
+
operation: string;
|
|
1557
|
+
ledger: string;
|
|
1558
|
+
file: string;
|
|
1559
|
+
offset: number;
|
|
1560
|
+
bytes: number;
|
|
1561
|
+
rows: Array<{ key: string | null; ts: number }>;
|
|
1562
|
+
replayed: boolean;
|
|
1563
|
+
}
|
|
1564
|
+
|
|
1565
|
+
export interface AppendOptions {
|
|
1566
|
+
/** Names the request: the same id and rows replay the original effect, never a second write. */
|
|
1567
|
+
operation?: string;
|
|
1568
|
+
/** The engine issues the operation id from the invocation and the request; exclusive with `operation`. */
|
|
1569
|
+
issueOperation?: boolean;
|
|
1570
|
+
/** Test seam: called at each durable checkpoint; a throw there simulates a lost response. */
|
|
1571
|
+
checkpoint?: AppendCheckpoint;
|
|
1572
|
+
}
|
|
1573
|
+
|
|
1574
|
+
/** `JSON.stringify` with object keys sorted at every depth: equal requests serialize equally. */
|
|
1575
|
+
export function canonicalJson(value: unknown): string {
|
|
1576
|
+
if (Array.isArray(value)) return `[${value.map((v) => canonicalJson(v)).join(",")}]`;
|
|
1577
|
+
if (value !== null && typeof value === "object") {
|
|
1578
|
+
const o = value as Record<string, unknown>;
|
|
1579
|
+
return `{${Object.keys(o)
|
|
1580
|
+
.filter((k) => o[k] !== undefined)
|
|
1581
|
+
.sort()
|
|
1582
|
+
.map((k) => `${JSON.stringify(k)}:${canonicalJson(o[k])}`)
|
|
1583
|
+
.join(",")}}`;
|
|
1584
|
+
}
|
|
1585
|
+
return JSON.stringify(value) ?? "null";
|
|
1586
|
+
}
|
|
1587
|
+
|
|
1588
|
+
/**
|
|
1589
|
+
* The operation id of an append request: the caller's `--operation`, else (with
|
|
1590
|
+
* `--issue-operation`) one issued from the invocation and the request, so retrying a lost
|
|
1591
|
+
* response gets the same id.
|
|
1592
|
+
*/
|
|
1593
|
+
export function appendOperationId(
|
|
1594
|
+
ledger: string,
|
|
1595
|
+
rows: unknown,
|
|
1596
|
+
invocation: Invocation | undefined,
|
|
1597
|
+
options: { operation?: string; issueOperation?: boolean },
|
|
1598
|
+
): string | undefined {
|
|
1599
|
+
if (options.operation !== undefined) return options.operation;
|
|
1600
|
+
if (options.issueOperation !== true || invocation === undefined) return undefined;
|
|
1601
|
+
const hash = actionHash(canonicalJson({ ledger, rows, invocation: invocation.id }));
|
|
1602
|
+
return `op-${invocation.id.slice(4, 16)}-${hash.slice(0, 12)}`;
|
|
1603
|
+
}
|
|
1604
|
+
|
|
1605
|
+
/**
|
|
1606
|
+
* The correction scope of an append by a workflow-run or a standalone (audit or utility)
|
|
1607
|
+
* invocation; null for any other caller.
|
|
1608
|
+
*/
|
|
1609
|
+
export function appendCorrectionScope(invocation: Invocation, ledger: string): string | null {
|
|
1610
|
+
const book = correctionBookKey(invocation);
|
|
1611
|
+
if (book === null) return null;
|
|
1612
|
+
return correctionScope({
|
|
1613
|
+
workflow: book.workflow,
|
|
1614
|
+
run: invocation.run,
|
|
1615
|
+
step: book.step,
|
|
1616
|
+
group: invocation.group,
|
|
1617
|
+
attempt: invocation.attempt,
|
|
1618
|
+
ledger,
|
|
1619
|
+
substep: "append",
|
|
1620
|
+
});
|
|
1621
|
+
}
|
|
1622
|
+
|
|
1623
|
+
/** The workflow and step a correction scope is cut from; the declared step for a standalone call. */
|
|
1624
|
+
function correctionBookKey(invocation: Invocation): { workflow: string; step: string } | null {
|
|
1625
|
+
if (invocation.scope === "run")
|
|
1626
|
+
return invocation.statusPath === null ||
|
|
1627
|
+
invocation.workflow === null ||
|
|
1628
|
+
invocation.step === null
|
|
1629
|
+
? null
|
|
1630
|
+
: { workflow: invocation.workflow, step: invocation.step };
|
|
1631
|
+
return invocation.standalone === null || invocation.declaredStep === null
|
|
1632
|
+
? null
|
|
1633
|
+
: { workflow: invocation.standalone, step: invocation.declaredStep };
|
|
1634
|
+
}
|
|
1635
|
+
|
|
1636
|
+
/**
|
|
1637
|
+
* Where the correction events of `invocation` live: the run's `status.jsonl`, or for a standalone
|
|
1638
|
+
* call the event file beside its outbox receipt. Null when the caller has no correction scope.
|
|
1639
|
+
*/
|
|
1640
|
+
function correctionBook(
|
|
1641
|
+
cwd: string,
|
|
1642
|
+
invocation: Invocation,
|
|
1643
|
+
): { file: string; workflow: string; step: string } | null {
|
|
1644
|
+
const key = correctionBookKey(invocation);
|
|
1645
|
+
if (key === null) return null;
|
|
1646
|
+
if (invocation.scope === "run")
|
|
1647
|
+
return invocation.statusPath === null ? null : { file: invocation.statusPath, ...key };
|
|
1648
|
+
const dir = invocationDir(cwd);
|
|
1649
|
+
if (dir === null) return null;
|
|
1650
|
+
const file = path.join(dir, `${invocation.id}.corrections.jsonl`);
|
|
1651
|
+
fs.appendFileSync(file, "");
|
|
1652
|
+
return { file, ...key };
|
|
1653
|
+
}
|
|
1654
|
+
|
|
1655
|
+
/** The `{key, ts}` of each row in prepared `block` bytes. */
|
|
1656
|
+
function receiptRows(block: string): LedgerReceipt["rows"] {
|
|
1657
|
+
const out: LedgerReceipt["rows"] = [];
|
|
1658
|
+
for (const line of block.split("\n")) {
|
|
1659
|
+
if (line.trim() === "") continue;
|
|
1660
|
+
const parsed = parseJson(line);
|
|
1661
|
+
if (!parsed.ok || parsed.value === null || typeof parsed.value !== "object") continue;
|
|
1662
|
+
const r = parsed.value as Record<string, unknown>;
|
|
1663
|
+
out.push({ key: typeof r["key"] === "string" ? r["key"] : null, ts: Number(r["ts"]) });
|
|
1664
|
+
}
|
|
1665
|
+
return out;
|
|
1666
|
+
}
|
|
1667
|
+
|
|
1271
1668
|
/**
|
|
1272
1669
|
* Append `rows` to one ledger. Every row is checked before any is written, so a
|
|
1273
1670
|
* refused row leaves the file byte-identical. Each row gets `schema` and a `ts`
|
|
1274
1671
|
* minted now (never supplied), `repo` when it lacks one and `bkit.version` from
|
|
1275
1672
|
* `.bkit/version`; an `AGED_KINDS` row also gets `firstTs` + `updates` carried
|
|
1276
1673
|
* forward from its entry's rows already in the ledger (supplied values replaced).
|
|
1277
|
-
* Never rewrites existing rows.
|
|
1278
|
-
*
|
|
1674
|
+
* Never rewrites existing rows. The write runs under the ledger's target lock; with
|
|
1675
|
+
* `options.operation` it also records the prepared bytes and a durable receipt, so a
|
|
1676
|
+
* lost response is reconciled by inspecting the ledger, never by appending again.
|
|
1677
|
+
* Throws a CommandError (USAGE / EXIT_ROW_REFUSED / EXIT_STAGE).
|
|
1279
1678
|
*/
|
|
1280
|
-
export function appendLedgerRows(
|
|
1679
|
+
export function appendLedgerRows(
|
|
1680
|
+
root: string,
|
|
1681
|
+
ledger: string,
|
|
1682
|
+
rows: unknown,
|
|
1683
|
+
invocation?: Invocation,
|
|
1684
|
+
options: AppendOptions = {},
|
|
1685
|
+
): AppendResult {
|
|
1281
1686
|
if (!Object.hasOwn(APPEND_LEDGERS, ledger)) {
|
|
1282
1687
|
throw new CommandError(
|
|
1283
1688
|
EXIT.USAGE,
|
|
@@ -1289,75 +1694,241 @@ export function appendLedgerRows(root: string, ledger: string, rows: unknown): A
|
|
|
1289
1694
|
if (!Array.isArray(rows)) throw new CommandError(EXIT.USAGE, "--rows must hold a JSON array");
|
|
1290
1695
|
if (rows.length === 0) throw new CommandError(EXIT.USAGE, "--rows holds no rows");
|
|
1291
1696
|
|
|
1292
|
-
let repo: string | undefined;
|
|
1293
|
-
let version: string | undefined;
|
|
1294
|
-
let last: number | undefined;
|
|
1295
1697
|
const abs = path.join(root, file);
|
|
1296
|
-
const prior: unknown[] = fs.existsSync(abs) ? parse(fs.readFileSync(abs, "utf-8")).events : [];
|
|
1297
|
-
const out: Array<Record<string, unknown>> = rows.map((raw, i) => {
|
|
1298
|
-
const refuse = (why: string) => new CommandError(EXIT_ROW_REFUSED, `row ${i + 1}: ${why}`);
|
|
1299
|
-
if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
|
|
1300
|
-
throw refuse("not a JSON object");
|
|
1301
|
-
}
|
|
1302
|
-
const r = raw as Record<string, unknown>;
|
|
1303
|
-
if (Object.hasOwn(r, "ts")) throw refuse("carries ts; ts is minted at append time");
|
|
1304
|
-
if (Object.hasOwn(r, "schema")) throw refuse("carries schema; it is set at append time");
|
|
1305
|
-
if (!takes.includes(String(r["kind"]))) {
|
|
1306
|
-
throw refuse(
|
|
1307
|
-
`kind must be ${takes.join(" | ")} in --ledger=${ledger} (got ${String(r["kind"])})`,
|
|
1308
|
-
);
|
|
1309
|
-
}
|
|
1310
|
-
if (Object.hasOwn(r, "bkit")) throw refuse("carries bkit; bkit.version is set at append time");
|
|
1311
|
-
repo ??= resolveRepoSlug(root) || "unknown/repo";
|
|
1312
|
-
version ??= readBkitVersion(path.join(root, ".bkit", "version"))?.pinnedVersion || "unknown";
|
|
1313
|
-
last = mintTs(last);
|
|
1314
|
-
const filled = withLineage(prior, {
|
|
1315
|
-
repo,
|
|
1316
|
-
...r,
|
|
1317
|
-
schema: SCHEMA,
|
|
1318
|
-
ts: last,
|
|
1319
|
-
bkit: { version },
|
|
1320
|
-
});
|
|
1321
|
-
const row: Record<string, unknown> = {};
|
|
1322
|
-
for (const k of TOP_ORDER) if (filled[k] !== undefined) row[k] = filled[k];
|
|
1323
|
-
for (const [k, v] of Object.entries(filled)) if (!(k in row)) row[k] = v;
|
|
1324
|
-
const v = validate(row);
|
|
1325
|
-
if (!v.ok) throw refuse(v.reason ?? "invalid");
|
|
1326
|
-
const who = writerProblem(row);
|
|
1327
|
-
if (who !== undefined) throw refuse(who);
|
|
1328
|
-
prior.push(row);
|
|
1329
|
-
return row;
|
|
1330
|
-
});
|
|
1331
|
-
|
|
1332
1698
|
const made = mkdirp(path.dirname(abs));
|
|
1333
1699
|
if (made) throw new CommandError(EXIT_STAGE, `mkdir failed for ${path.dirname(file)}: ${made}`);
|
|
1334
|
-
|
|
1335
|
-
//
|
|
1336
|
-
const
|
|
1337
|
-
|
|
1338
|
-
|
|
1339
|
-
|
|
1340
|
-
|
|
1341
|
-
|
|
1342
|
-
|
|
1700
|
+
// The operation store is private to this git repository, never a committed path; a repo-less
|
|
1701
|
+
// root has no place to keep a durable receipt, so an operation there is refused.
|
|
1702
|
+
const ops = ledgerOperationsFile(
|
|
1703
|
+
root,
|
|
1704
|
+
options.operation !== undefined || options.issueOperation === true,
|
|
1705
|
+
);
|
|
1706
|
+
// The request is the ledger and rows alone: an operation stays reconcilable after its
|
|
1707
|
+
// invocation goes stale, and replay writes the recorded bytes, never a re-derived `by`.
|
|
1708
|
+
const hash = actionHash(canonicalJson({ ledger, rows }));
|
|
1709
|
+
if (options.operation !== undefined && options.issueOperation === true)
|
|
1710
|
+
throw new CommandError(
|
|
1711
|
+
EXIT.USAGE,
|
|
1712
|
+
"--issue-operation and --operation are exclusive: the engine issues the id, or the caller names it",
|
|
1713
|
+
);
|
|
1714
|
+
if (options.issueOperation === true && invocation === undefined)
|
|
1715
|
+
throw new CommandError(
|
|
1716
|
+
EXIT.USAGE,
|
|
1717
|
+
"--issue-operation needs --invocation: the id is issued from that invocation's context",
|
|
1718
|
+
);
|
|
1719
|
+
const operation = appendOperationId(ledger, rows, invocation, options);
|
|
1720
|
+
// A rejection before any write is correctable only inside a workflow run (it has a scope to
|
|
1721
|
+
// spend from) and only when the operation can be named by the corrected retry.
|
|
1722
|
+
const scope = invocation === undefined ? null : appendCorrectionScope(invocation, ledger);
|
|
1723
|
+
const reject = (why: string, row: number) => {
|
|
1724
|
+
const message = `row ${row}: ${why}`;
|
|
1725
|
+
return scope !== null && operation !== undefined
|
|
1726
|
+
? new NoWriteRejection(EXIT_ROW_REFUSED, message, { scope, substep: "append" })
|
|
1727
|
+
: new CommandError(EXIT_ROW_REFUSED, message);
|
|
1343
1728
|
};
|
|
1344
|
-
}
|
|
1345
1729
|
|
|
1346
|
-
|
|
1347
|
-
|
|
1348
|
-
|
|
1730
|
+
const result = (landed: { offset: number; bytes: number }, block: string, replayed: boolean) => {
|
|
1731
|
+
const parsedRows = receiptRows(block);
|
|
1732
|
+
return {
|
|
1733
|
+
ledger: ledger as AppendLedger,
|
|
1734
|
+
file,
|
|
1735
|
+
appended: replayed ? 0 : parsedRows.length,
|
|
1736
|
+
keys: parsedRows.map((r) => r.key),
|
|
1737
|
+
...(operation === undefined
|
|
1738
|
+
? {}
|
|
1739
|
+
: {
|
|
1740
|
+
receipt: {
|
|
1741
|
+
operation,
|
|
1742
|
+
ledger,
|
|
1743
|
+
file,
|
|
1744
|
+
offset: landed.offset,
|
|
1745
|
+
bytes: landed.bytes,
|
|
1746
|
+
rows: parsedRows,
|
|
1747
|
+
replayed,
|
|
1748
|
+
},
|
|
1749
|
+
}),
|
|
1750
|
+
};
|
|
1751
|
+
};
|
|
1752
|
+
|
|
1753
|
+
const build = (text: string): string => {
|
|
1754
|
+
let repo: string | undefined;
|
|
1755
|
+
let version: string | undefined;
|
|
1756
|
+
let last: number | undefined;
|
|
1757
|
+
const prior: unknown[] = parse(text).events;
|
|
1758
|
+
const out: Array<Record<string, unknown>> = rows.map((raw, i) => {
|
|
1759
|
+
const refuse = (why: string) => new CommandError(EXIT_ROW_REFUSED, `row ${i + 1}: ${why}`);
|
|
1760
|
+
if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
|
|
1761
|
+
throw reject("not a JSON object", i + 1);
|
|
1762
|
+
}
|
|
1763
|
+
const r =
|
|
1764
|
+
invocation === undefined
|
|
1765
|
+
? (raw as Record<string, unknown>)
|
|
1766
|
+
: withInvocationBy(raw as Record<string, unknown>, invocation, refuse);
|
|
1767
|
+
if (invocation === undefined && byOfRow(r)["modelSource"] === "unavailable")
|
|
1768
|
+
throw refuse(
|
|
1769
|
+
"by.modelSource unavailable needs a validated --invocation; the engine records it, a caller cannot assert it",
|
|
1770
|
+
);
|
|
1771
|
+
if (Object.hasOwn(r, "ts")) throw reject("carries ts; ts is minted at append time", i + 1);
|
|
1772
|
+
if (Object.hasOwn(r, "schema"))
|
|
1773
|
+
throw reject("carries schema; it is set at append time", i + 1);
|
|
1774
|
+
if (!takes.includes(String(r["kind"]))) {
|
|
1775
|
+
throw reject(
|
|
1776
|
+
`kind must be ${takes.join(" | ")} in --ledger=${ledger} (got ${String(r["kind"])})`,
|
|
1777
|
+
i + 1,
|
|
1778
|
+
);
|
|
1779
|
+
}
|
|
1780
|
+
if (Object.hasOwn(r, "bkit"))
|
|
1781
|
+
throw reject("carries bkit; bkit.version is set at append time", i + 1);
|
|
1782
|
+
repo ??= resolveRepoSlug(root) || "unknown/repo";
|
|
1783
|
+
version ??= readBkitVersion(path.join(root, ".bkit", "version"))?.pinnedVersion || "unknown";
|
|
1784
|
+
last = mintTs(last);
|
|
1785
|
+
const filled = withLineage(prior, {
|
|
1786
|
+
repo,
|
|
1787
|
+
...r,
|
|
1788
|
+
schema: SCHEMA,
|
|
1789
|
+
ts: last,
|
|
1790
|
+
bkit: { version },
|
|
1791
|
+
});
|
|
1792
|
+
const row: Record<string, unknown> = {};
|
|
1793
|
+
for (const k of TOP_ORDER) if (filled[k] !== undefined) row[k] = filled[k];
|
|
1794
|
+
for (const [k, v] of Object.entries(filled)) if (!(k in row)) row[k] = v;
|
|
1795
|
+
const v = validate(row);
|
|
1796
|
+
if (!v.ok) throw reject(v.reason ?? "invalid", i + 1);
|
|
1797
|
+
const who = writerProblem(row);
|
|
1798
|
+
if (who !== undefined) throw refuse(who);
|
|
1799
|
+
prior.push(row);
|
|
1800
|
+
return row;
|
|
1801
|
+
});
|
|
1802
|
+
return out.map((r) => `${JSON.stringify(r)}\n`).join("");
|
|
1803
|
+
};
|
|
1804
|
+
|
|
1805
|
+
const stage = (err: unknown) =>
|
|
1806
|
+
err instanceof CommandError
|
|
1807
|
+
? err
|
|
1808
|
+
: new CommandError(EXIT_STAGE, `append failed: ${file} \u2014 ${(err as Error).message}`);
|
|
1809
|
+
|
|
1349
1810
|
try {
|
|
1350
|
-
|
|
1351
|
-
|
|
1352
|
-
|
|
1353
|
-
|
|
1354
|
-
|
|
1355
|
-
|
|
1356
|
-
|
|
1357
|
-
|
|
1358
|
-
|
|
1359
|
-
|
|
1360
|
-
|
|
1811
|
+
return withTargetLock(abs, () => {
|
|
1812
|
+
if (operation === undefined) {
|
|
1813
|
+
const landed = appendHeld(abs, build, { checkpoint: options.checkpoint });
|
|
1814
|
+
return result(landed, landed.block, false);
|
|
1815
|
+
}
|
|
1816
|
+
if (ops === null)
|
|
1817
|
+
throw new CommandError(
|
|
1818
|
+
EXIT.USAGE,
|
|
1819
|
+
`${root} is not inside a git repository: a ledger operation keeps its receipt in the git common dir`,
|
|
1820
|
+
);
|
|
1821
|
+
// The operation store is serialized by its own lock, taken after the target's, so two
|
|
1822
|
+
// ledgers' operations never interleave check and record.
|
|
1823
|
+
return withTargetLock(ops, () => {
|
|
1824
|
+
const known = ledgerOperation(ops, operation, hash);
|
|
1825
|
+
if (known.state === "conflict")
|
|
1826
|
+
throw new CommandError(
|
|
1827
|
+
EXIT_ROW_REFUSED,
|
|
1828
|
+
`operation ${operation} was already used for a different request; nothing written`,
|
|
1829
|
+
);
|
|
1830
|
+
if (known.state === "replay") {
|
|
1831
|
+
const d = (known.row as { detail?: { offset: number; bytes: number; block: string } })
|
|
1832
|
+
.detail;
|
|
1833
|
+
if (d === undefined)
|
|
1834
|
+
throw new CommandError(
|
|
1835
|
+
EXIT_STAGE,
|
|
1836
|
+
`operation ${operation} has a receipt without its effect`,
|
|
1837
|
+
);
|
|
1838
|
+
return result(d, d.block, true);
|
|
1839
|
+
}
|
|
1840
|
+
const intent = ledgerIntent(ops, operation);
|
|
1841
|
+
if (intent !== undefined && intent.hash !== hash)
|
|
1842
|
+
throw new CommandError(
|
|
1843
|
+
EXIT_ROW_REFUSED,
|
|
1844
|
+
`operation ${operation} was already used for a different request; nothing written`,
|
|
1845
|
+
);
|
|
1846
|
+
const receipt = (landed: { offset: number; bytes: number; block: string }) =>
|
|
1847
|
+
recordLedgerOperation(ops, {
|
|
1848
|
+
operation,
|
|
1849
|
+
hash,
|
|
1850
|
+
ref: `${file}@${landed.offset}+${landed.bytes}`,
|
|
1851
|
+
detail: { offset: landed.offset, bytes: landed.bytes, block: landed.block },
|
|
1852
|
+
});
|
|
1853
|
+
if (intent !== undefined) {
|
|
1854
|
+
const have = fs.existsSync(abs) ? fs.readFileSync(abs) : Buffer.alloc(0);
|
|
1855
|
+
const want = Buffer.from(intent.block);
|
|
1856
|
+
const seg = have.subarray(intent.offset, intent.offset + want.length);
|
|
1857
|
+
if (seg.equals(want)) {
|
|
1858
|
+
// The bytes landed whole; confirm them durable and receipt them.
|
|
1859
|
+
const fd = fs.openSync(abs, "r");
|
|
1860
|
+
try {
|
|
1861
|
+
fs.fsyncSync(fd);
|
|
1862
|
+
} finally {
|
|
1863
|
+
fs.closeSync(fd);
|
|
1864
|
+
}
|
|
1865
|
+
receipt(intent);
|
|
1866
|
+
options.checkpoint?.("receipted");
|
|
1867
|
+
return result(intent, intent.block, true);
|
|
1868
|
+
}
|
|
1869
|
+
// Whole lines decide "landed": rows share a byte prefix (`{"schema":3,"ts":...`), so a
|
|
1870
|
+
// foreign row is told apart by being a complete line that differs from ours.
|
|
1871
|
+
// Compare by content, without the newline and without one leading separator newline:
|
|
1872
|
+
// a torn prefix of our line that a later writer completed with its own newline is a
|
|
1873
|
+
// proper prefix of our first line, so it stays uncertain rather than foreign.
|
|
1874
|
+
const stripSeparator = (b: Buffer): Buffer => (b[0] === 0x0a ? b.subarray(1) : b);
|
|
1875
|
+
const firstLine = (b: Buffer): { line: Buffer; complete: boolean } => {
|
|
1876
|
+
const nl = b.indexOf(0x0a);
|
|
1877
|
+
return nl < 0
|
|
1878
|
+
? { line: b, complete: false }
|
|
1879
|
+
: { line: b.subarray(0, nl), complete: true };
|
|
1880
|
+
};
|
|
1881
|
+
const wantLine = firstLine(stripSeparator(want)).line;
|
|
1882
|
+
const haveLine = firstLine(stripSeparator(have.subarray(intent.offset)));
|
|
1883
|
+
const foreignWholeLine =
|
|
1884
|
+
haveLine.complete &&
|
|
1885
|
+
!(
|
|
1886
|
+
haveLine.line.length <= wantLine.length &&
|
|
1887
|
+
wantLine.subarray(0, haveLine.line.length).equals(haveLine.line)
|
|
1888
|
+
);
|
|
1889
|
+
let landedBytes = 0;
|
|
1890
|
+
while (
|
|
1891
|
+
landedBytes < seg.length &&
|
|
1892
|
+
landedBytes < want.length &&
|
|
1893
|
+
seg[landedBytes] === want[landedBytes]
|
|
1894
|
+
)
|
|
1895
|
+
landedBytes++;
|
|
1896
|
+
if (
|
|
1897
|
+
!foreignWholeLine &&
|
|
1898
|
+
(landedBytes > 0 || (seg.length > 0 && have.length === intent.offset + seg.length))
|
|
1899
|
+
)
|
|
1900
|
+
throw new UncertainEffect(
|
|
1901
|
+
EXIT_STAGE,
|
|
1902
|
+
`operation ${operation}: ${file} holds ${landedBytes} of ${want.length} prepared bytes at the recorded offset; the effect is uncertain, nothing was truncated or retried`,
|
|
1903
|
+
);
|
|
1904
|
+
if (have.length === intent.offset) {
|
|
1905
|
+
// Nothing landed: write the exact prepared bytes again.
|
|
1906
|
+
writePrepared(abs, intent.block, intent.offset);
|
|
1907
|
+
options.checkpoint?.("written");
|
|
1908
|
+
receipt(intent);
|
|
1909
|
+
options.checkpoint?.("receipted");
|
|
1910
|
+
return result(intent, intent.block, false);
|
|
1911
|
+
}
|
|
1912
|
+
// Another writer appended after the failed attempt and none of ours landed: prepare afresh.
|
|
1913
|
+
}
|
|
1914
|
+
const landed = appendHeld(abs, build, {
|
|
1915
|
+
checkpoint: options.checkpoint,
|
|
1916
|
+
prepared: (p) =>
|
|
1917
|
+
recordLedgerIntent(ops, {
|
|
1918
|
+
operation,
|
|
1919
|
+
hash,
|
|
1920
|
+
file,
|
|
1921
|
+
offset: p.offset,
|
|
1922
|
+
bytes: Buffer.byteLength(p.block),
|
|
1923
|
+
block: p.block,
|
|
1924
|
+
}),
|
|
1925
|
+
written: (p) => receipt(p),
|
|
1926
|
+
});
|
|
1927
|
+
return result(landed, landed.block, false);
|
|
1928
|
+
});
|
|
1929
|
+
});
|
|
1930
|
+
} catch (err) {
|
|
1931
|
+
throw stage(err);
|
|
1361
1932
|
}
|
|
1362
1933
|
}
|
|
1363
1934
|
|
|
@@ -1370,9 +1941,216 @@ function append(ctx: RunContext): number {
|
|
|
1370
1941
|
if (text.trim() === "") throw new CommandError(EXIT.USAGE, "--rows holds no rows");
|
|
1371
1942
|
const parsed = parseJson(text);
|
|
1372
1943
|
if (!parsed.ok) throw new CommandError(EXIT.USAGE, "--rows is not JSON");
|
|
1373
|
-
const
|
|
1374
|
-
|
|
1375
|
-
|
|
1944
|
+
const bound = ctx.invocation?.bookRoot;
|
|
1945
|
+
if (bound !== undefined && bound !== null && bound !== root)
|
|
1946
|
+
throw new CommandError(
|
|
1947
|
+
EXIT.USAGE,
|
|
1948
|
+
`conflict: --root ${root} is not the invocation's book root ${bound}`,
|
|
1949
|
+
);
|
|
1950
|
+
// A runless call has no book root of its own: its output scope is the checkout that issued it.
|
|
1951
|
+
if (ctx.invocation?.scope === "outbox") {
|
|
1952
|
+
const rel = path.relative(ctx.invocation.worktree, root);
|
|
1953
|
+
if (rel.startsWith("..") || path.isAbsolute(rel))
|
|
1954
|
+
throw new CommandError(
|
|
1955
|
+
EXIT.USAGE,
|
|
1956
|
+
`conflict: --root ${root} is outside the checkout ${ctx.invocation.worktree} that issued invocation ${ctx.invocation.id}`,
|
|
1957
|
+
);
|
|
1958
|
+
}
|
|
1959
|
+
const ledger = String(ctx.flags.ledger);
|
|
1960
|
+
const request = {
|
|
1961
|
+
operation: str(ctx.flags.operation),
|
|
1962
|
+
issueOperation: ctx.flags.issueOperation === true,
|
|
1963
|
+
};
|
|
1964
|
+
const run = ctx.invocation;
|
|
1965
|
+
const scope = run === undefined ? null : appendCorrectionScope(run, ledger);
|
|
1966
|
+
const operation = appendOperationId(ledger, parsed.value, run, request);
|
|
1967
|
+
const correctionOf = str(ctx.flags.correctionOf);
|
|
1968
|
+
let spend: CorrectionSpend | undefined;
|
|
1969
|
+
const book = run === undefined || scope === null ? null : correctionBook(ctx.cwd, run);
|
|
1970
|
+
if (correctionOf !== undefined) {
|
|
1971
|
+
if (run === undefined || scope === null || book === null)
|
|
1972
|
+
throw new CommandError(
|
|
1973
|
+
EXIT.USAGE,
|
|
1974
|
+
"--correction-of needs an --invocation with a correction scope: a workflow-run call, or a standalone audit or utility call",
|
|
1975
|
+
);
|
|
1976
|
+
if (operation === undefined || operation === correctionOf)
|
|
1977
|
+
throw new CommandError(
|
|
1978
|
+
EXIT.USAGE,
|
|
1979
|
+
"--correction-of needs a fresh --operation or --issue-operation: a corrected candidate has its own operation id",
|
|
1980
|
+
);
|
|
1981
|
+
const rejected = readStatusRows(book.file).some(
|
|
1982
|
+
(row) =>
|
|
1983
|
+
row.type === CORRECTION_REJECTED_ROW &&
|
|
1984
|
+
row.operation === correctionOf &&
|
|
1985
|
+
row.scope === scope &&
|
|
1986
|
+
row.workflow === book.workflow,
|
|
1987
|
+
);
|
|
1988
|
+
if (!rejected)
|
|
1989
|
+
throw new CommandError(
|
|
1990
|
+
EXIT.USAGE,
|
|
1991
|
+
`--correction-of=${correctionOf} names no rejected ${ledger} append in this step; only a guaranteed no-write rejection of this sub-step can be corrected`,
|
|
1992
|
+
);
|
|
1993
|
+
// An earlier operation on this ledger whose effect is unconfirmed is reconciled first.
|
|
1994
|
+
const target = Object.hasOwn(APPEND_LEDGERS, ledger)
|
|
1995
|
+
? APPEND_LEDGERS[ledger as AppendLedger].file
|
|
1996
|
+
: undefined;
|
|
1997
|
+
if (target !== undefined && pendingLedgerIntentsFor(root, target).length > 0)
|
|
1998
|
+
throw new UncertainEffect(
|
|
1999
|
+
EXIT_STAGE,
|
|
2000
|
+
`${target} holds an operation whose effect is unconfirmed; reconcile it before any corrected candidate — nothing was written`,
|
|
2001
|
+
);
|
|
2002
|
+
spend = spendCorrection(book.file, book.workflow, scope, operation, CORRECTION_LIMIT, {
|
|
2003
|
+
of: correctionOf,
|
|
2004
|
+
step: book.step,
|
|
2005
|
+
substep: "append",
|
|
2006
|
+
requestHash: actionHash(canonicalJson({ ledger, rows: parsed.value })),
|
|
2007
|
+
});
|
|
2008
|
+
if (!spend.allowed)
|
|
2009
|
+
throw new CorrectionExhausted(
|
|
2010
|
+
EXIT.NO,
|
|
2011
|
+
spend.conflict === true
|
|
2012
|
+
? `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`
|
|
2013
|
+
: `the correction budget of ${scope} is spent (${spend.used} of ${spend.limit}); nothing was written`,
|
|
2014
|
+
scope,
|
|
2015
|
+
);
|
|
2016
|
+
}
|
|
2017
|
+
let r: AppendResult;
|
|
2018
|
+
try {
|
|
2019
|
+
r = appendLedgerRows(root, ledger, parsed.value, ctx.invocation, request);
|
|
2020
|
+
} catch (err) {
|
|
2021
|
+
if (err instanceof NoWriteRejection && book !== null && operation !== undefined) {
|
|
2022
|
+
fs.appendFileSync(
|
|
2023
|
+
book.file,
|
|
2024
|
+
appendLine({
|
|
2025
|
+
type: CORRECTION_REJECTED_ROW,
|
|
2026
|
+
workflow: book.workflow,
|
|
2027
|
+
at: statusTimestamp(),
|
|
2028
|
+
scope: err.detail.scope,
|
|
2029
|
+
substep: err.detail.substep,
|
|
2030
|
+
operation,
|
|
2031
|
+
step: book.step,
|
|
2032
|
+
}),
|
|
2033
|
+
);
|
|
2034
|
+
// The last allowed retry was just used: the rejection is final, not correctable.
|
|
2035
|
+
if (spend !== undefined && spend.remaining === 0)
|
|
2036
|
+
throw new CommandError(err.code, err.message);
|
|
2037
|
+
}
|
|
2038
|
+
throw err;
|
|
2039
|
+
}
|
|
2040
|
+
ctx.log(
|
|
2041
|
+
r.receipt?.replayed === true
|
|
2042
|
+
? `operation ${r.receipt.operation} already appended to ${r.file}; nothing written`
|
|
2043
|
+
: `appended ${r.appended} row(s) to ${r.file}`,
|
|
2044
|
+
);
|
|
2045
|
+
if (spend === undefined || book === null || scope === null) {
|
|
2046
|
+
ctx.emit({ ...r });
|
|
2047
|
+
return EXIT.OK;
|
|
2048
|
+
}
|
|
2049
|
+
const verified =
|
|
2050
|
+
r.receipt?.replayed === true || r.appended === (parsed.value as unknown[]).length;
|
|
2051
|
+
const succeeded = readStatusRows(book.file).some(
|
|
2052
|
+
(row) => row.type === CORRECTION_SUCCEEDED_ROW && row.operation === operation,
|
|
2053
|
+
);
|
|
2054
|
+
if (verified && !succeeded)
|
|
2055
|
+
fs.appendFileSync(
|
|
2056
|
+
book.file,
|
|
2057
|
+
appendLine({
|
|
2058
|
+
type: CORRECTION_SUCCEEDED_ROW,
|
|
2059
|
+
workflow: book.workflow,
|
|
2060
|
+
at: statusTimestamp(),
|
|
2061
|
+
scope,
|
|
2062
|
+
substep: "append",
|
|
2063
|
+
operation,
|
|
2064
|
+
of: correctionOf,
|
|
2065
|
+
step: book.step,
|
|
2066
|
+
}),
|
|
2067
|
+
);
|
|
2068
|
+
ctx.emit({
|
|
2069
|
+
...r,
|
|
2070
|
+
correction: {
|
|
2071
|
+
scope,
|
|
2072
|
+
operation,
|
|
2073
|
+
of: correctionOf,
|
|
2074
|
+
used: spend.used,
|
|
2075
|
+
limit: spend.limit,
|
|
2076
|
+
substep: "append",
|
|
2077
|
+
verified,
|
|
2078
|
+
},
|
|
2079
|
+
});
|
|
2080
|
+
return EXIT.OK;
|
|
2081
|
+
}
|
|
2082
|
+
|
|
2083
|
+
/** Page cursor: the snapshot and filter it was cut from, and the offset of the next row. */
|
|
2084
|
+
function encodeCursor(c: { s: string; f: string; o: number }): string {
|
|
2085
|
+
return Buffer.from(JSON.stringify(c)).toString("base64url");
|
|
2086
|
+
}
|
|
2087
|
+
|
|
2088
|
+
function decodeCursor(text: string): { s: string; f: string; o: number } | null {
|
|
2089
|
+
const parsed = parseJson(Buffer.from(text, "base64url").toString("utf-8"));
|
|
2090
|
+
if (!parsed.ok || parsed.value === null || typeof parsed.value !== "object") return null;
|
|
2091
|
+
const v = parsed.value as Record<string, unknown>;
|
|
2092
|
+
return typeof v["s"] === "string" && typeof v["f"] === "string" && Number.isInteger(v["o"])
|
|
2093
|
+
? { s: v["s"], f: v["f"], o: v["o"] as number }
|
|
2094
|
+
: null;
|
|
2095
|
+
}
|
|
2096
|
+
|
|
2097
|
+
function query(ctx: RunContext): number {
|
|
2098
|
+
const root = rootOf(ctx);
|
|
2099
|
+
const ledger = String(ctx.flags.ledger);
|
|
2100
|
+
if (!Object.hasOwn(APPEND_LEDGERS, ledger)) {
|
|
2101
|
+
throw new CommandError(
|
|
2102
|
+
EXIT.USAGE,
|
|
2103
|
+
`--ledger must be one of ${Object.keys(APPEND_LEDGERS).join(", ")} (got '${ledger}')`,
|
|
2104
|
+
);
|
|
2105
|
+
}
|
|
2106
|
+
const { file } = APPEND_LEDGERS[ledger as AppendLedger];
|
|
2107
|
+
const filter = { key: str(ctx.flags.key), status: str(ctx.flags.status) };
|
|
2108
|
+
const limit = wholeNumber(ctx.flags.limit, "limit", QUERY_PAGE, 1);
|
|
2109
|
+
const filterId = JSON.stringify([filter.key ?? null, filter.status ?? null]);
|
|
2110
|
+
const cursorText = str(ctx.flags.cursor);
|
|
2111
|
+
const cursor = cursorText === undefined ? null : decodeCursor(cursorText);
|
|
2112
|
+
if (cursorText !== undefined && cursor === null)
|
|
2113
|
+
throw new CommandError(EXIT.USAGE, "--cursor is not a cursor from this command");
|
|
2114
|
+
|
|
2115
|
+
const abs = path.join(root, file);
|
|
2116
|
+
const read = readText(abs);
|
|
2117
|
+
const missing = !read.ok && !fs.existsSync(abs);
|
|
2118
|
+
const raw = read.ok ? read.text : "";
|
|
2119
|
+
const snapshot = createHash("sha256").update(raw).digest("hex").slice(0, 16);
|
|
2120
|
+
if (cursor !== null && (cursor.s !== snapshot || cursor.f !== filterId))
|
|
2121
|
+
throw new CommandError(
|
|
2122
|
+
EXIT.USAGE,
|
|
2123
|
+
"stale cursor: the ledger or the filter changed since this scan began; start again without --cursor",
|
|
2124
|
+
);
|
|
2125
|
+
const result = queryLedger(raw, filter);
|
|
2126
|
+
const offset = cursor?.o ?? 0;
|
|
2127
|
+
const page = result.rows.slice(offset, offset + limit);
|
|
2128
|
+
const next = offset + limit < result.rows.length ? offset + limit : null;
|
|
2129
|
+
const status = missing
|
|
2130
|
+
? "missing"
|
|
2131
|
+
: !read.ok
|
|
2132
|
+
? "unreadable"
|
|
2133
|
+
: result.diagnostics.length > 0
|
|
2134
|
+
? "partial"
|
|
2135
|
+
: next !== null
|
|
2136
|
+
? "incomplete"
|
|
2137
|
+
: "clean";
|
|
2138
|
+
ctx.emit({
|
|
2139
|
+
ledger,
|
|
2140
|
+
file,
|
|
2141
|
+
rows: page,
|
|
2142
|
+
nextCursor: next === null ? null : encodeCursor({ s: snapshot, f: filterId, o: next }),
|
|
2143
|
+
snapshot,
|
|
2144
|
+
total: result.rows.length,
|
|
2145
|
+
diagnostics: result.diagnostics,
|
|
2146
|
+
coverage: {
|
|
2147
|
+
status,
|
|
2148
|
+
clean: status === "clean",
|
|
2149
|
+
malformedLines: result.diagnostics.length,
|
|
2150
|
+
lines: result.lines,
|
|
2151
|
+
...(!read.ok && !missing ? { error: read.error } : {}),
|
|
2152
|
+
},
|
|
2153
|
+
});
|
|
1376
2154
|
return EXIT.OK;
|
|
1377
2155
|
}
|
|
1378
2156
|
|
|
@@ -1392,15 +2170,39 @@ export interface PlanRowsResult {
|
|
|
1392
2170
|
export function checkPlanRows(root: string, plan: string): PlanRowsResult {
|
|
1393
2171
|
const abs = path.resolve(root, plan);
|
|
1394
2172
|
if (!fs.existsSync(abs)) throw new CommandError(EXIT.USAGE, `--plan not found: ${plan}`);
|
|
1395
|
-
const
|
|
1396
|
-
|
|
1397
|
-
|
|
1398
|
-
|
|
2173
|
+
const r = readPlanRows(root, fs.readFileSync(abs, "utf-8"));
|
|
2174
|
+
if (r.unreadable !== undefined)
|
|
2175
|
+
throw new CommandError(EXIT_ROWS_MISSING, `${plan}: ${r.unreadable}`);
|
|
2176
|
+
return { keys: r.keys, missing: r.missing };
|
|
2177
|
+
}
|
|
2178
|
+
|
|
2179
|
+
export interface PlanRowsRead extends PlanRowsResult {
|
|
2180
|
+
/** 1-based line of the `**Ledger rows:**` line; 0 when the plan has none. */
|
|
2181
|
+
line: number;
|
|
2182
|
+
/** Why the line names no keys to check: absent, or still a placeholder. */
|
|
2183
|
+
unreadable?: string;
|
|
2184
|
+
}
|
|
2185
|
+
|
|
2186
|
+
/**
|
|
2187
|
+
* Read `text`'s `**Ledger rows:**` line and the keys no `decision` / `deferral`
|
|
2188
|
+
* row under `root` carries. An absent or placeholder line is `unreadable`.
|
|
2189
|
+
*/
|
|
2190
|
+
export function readPlanRows(root: string, text: string): PlanRowsRead {
|
|
2191
|
+
const match = LEDGER_ROWS_LINE.exec(text);
|
|
2192
|
+
const line = match?.[1]?.trim();
|
|
2193
|
+
if (match === null || line === undefined) {
|
|
2194
|
+
return { line: 0, keys: [], missing: [], unreadable: "no **Ledger rows:** line" };
|
|
1399
2195
|
}
|
|
2196
|
+
const at = text.slice(0, match.index).split("\n").length;
|
|
1400
2197
|
const keys = [...line.matchAll(/`([^`]+)`/g)].map((m) => m[1] ?? "");
|
|
1401
2198
|
if (keys.length === 0) {
|
|
1402
|
-
if (line.replace(/[."\s]/g, "") === "None") return { keys: [], missing: [] };
|
|
1403
|
-
|
|
2199
|
+
if (line.replace(/[."\s]/g, "") === "None") return { line: at, keys: [], missing: [] };
|
|
2200
|
+
return {
|
|
2201
|
+
line: at,
|
|
2202
|
+
keys: [],
|
|
2203
|
+
missing: [],
|
|
2204
|
+
unreadable: `**Ledger rows:** is unfilled (${line})`,
|
|
2205
|
+
};
|
|
1404
2206
|
}
|
|
1405
2207
|
const onDisk = new Set<string>();
|
|
1406
2208
|
for (const { file, kinds } of CHECKED_LEDGERS) {
|
|
@@ -1411,7 +2213,7 @@ export function checkPlanRows(root: string, plan: string): PlanRowsResult {
|
|
|
1411
2213
|
if ((kinds as readonly string[]).includes(e.kind) && typeof key === "string") onDisk.add(key);
|
|
1412
2214
|
}
|
|
1413
2215
|
}
|
|
1414
|
-
return { keys, missing: keys.filter((k) => !onDisk.has(k)) };
|
|
2216
|
+
return { line: at, keys, missing: keys.filter((k) => !onDisk.has(k)) };
|
|
1415
2217
|
}
|
|
1416
2218
|
|
|
1417
2219
|
function check(ctx: RunContext): number {
|
|
@@ -1466,18 +2268,21 @@ function compactOrError(
|
|
|
1466
2268
|
dryRun: boolean,
|
|
1467
2269
|
): ReturnType<typeof compactLedgers> | string {
|
|
1468
2270
|
try {
|
|
1469
|
-
|
|
1470
|
-
|
|
1471
|
-
|
|
1472
|
-
|
|
1473
|
-
|
|
1474
|
-
|
|
1475
|
-
|
|
1476
|
-
|
|
1477
|
-
|
|
1478
|
-
|
|
1479
|
-
|
|
1480
|
-
|
|
2271
|
+
const targets = ledgers.map((l) => COMPACT_LEDGERS[l]).sort();
|
|
2272
|
+
const locked = (i: number): ReturnType<typeof compactLedgers> => {
|
|
2273
|
+
if (i === targets.length) {
|
|
2274
|
+
for (const t of targets) {
|
|
2275
|
+
const pending = pendingLedgerIntentsFor(root, t);
|
|
2276
|
+
if (pending.length > 0)
|
|
2277
|
+
throw new Error(
|
|
2278
|
+
`${t} has ${pending.length} ledger operation(s) with bytes but no receipt (${pending.map((p) => p.operation).join(", ")}); replay them before compacting`,
|
|
2279
|
+
);
|
|
2280
|
+
}
|
|
2281
|
+
return compactLedgers(root, ledgers, dryRun);
|
|
2282
|
+
}
|
|
2283
|
+
return withTargetLock(path.join(root, targets[i]!), () => locked(i + 1));
|
|
2284
|
+
};
|
|
2285
|
+
return locked(0);
|
|
1481
2286
|
} catch (err) {
|
|
1482
2287
|
// Reported as the command's staging exit code, with the reason.
|
|
1483
2288
|
return (err as Error).message;
|