@holmes-lab/holmes-kit 0.38.0 → 0.40.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/CHANGELOG.md +370 -6
- package/README.md +58 -40
- package/dist/.build-id +1 -1
- package/dist/holmes/admission/core/admission-policy.d.ts +37 -0
- package/dist/holmes/admission/core/admission-policy.js +147 -0
- package/dist/holmes/admission/core/bounded-reader.d.ts +56 -0
- package/dist/holmes/admission/core/bounded-reader.js +135 -0
- package/dist/holmes/admission/core/change-classifier.d.ts +34 -0
- package/dist/holmes/admission/core/change-classifier.js +278 -0
- package/dist/holmes/admission/core/config-loader.d.ts +30 -0
- package/dist/holmes/admission/core/config-loader.js +145 -0
- package/dist/holmes/admission/core/event-judgement.d.ts +37 -0
- package/dist/holmes/admission/core/event-judgement.js +251 -0
- package/dist/holmes/admission/core/path-rules.d.ts +35 -0
- package/dist/holmes/admission/core/path-rules.js +88 -0
- package/dist/holmes/admission/core/pin.d.ts +7 -0
- package/dist/holmes/admission/core/pin.js +29 -0
- package/dist/holmes/admission/core/ports.d.ts +48 -0
- package/dist/holmes/admission/core/ports.js +11 -0
- package/dist/holmes/admission/core/range-resolver.d.ts +32 -0
- package/dist/holmes/admission/core/range-resolver.js +51 -0
- package/dist/holmes/admission/core/self-containment.d.ts +1 -0
- package/dist/holmes/admission/core/self-containment.js +125 -0
- package/dist/holmes/admission/core/signature-source.d.ts +9 -0
- package/dist/holmes/admission/core/signature-source.js +4 -0
- package/dist/holmes/admission/core/transition-planner.d.ts +15 -0
- package/dist/holmes/admission/core/transition-planner.js +14 -0
- package/dist/holmes/admission/core/verdict.d.ts +38 -0
- package/dist/holmes/admission/core/verdict.js +17 -0
- package/dist/holmes/admission/core/wiring.d.ts +44 -0
- package/dist/holmes/admission/core/wiring.js +618 -0
- package/dist/holmes/admission/forge/git-object-port.d.ts +4 -0
- package/dist/holmes/admission/forge/git-object-port.js +132 -0
- package/dist/holmes/assoc/assoc-arm.d.ts +1 -1
- package/dist/holmes/assoc/assoc-arm.js +1 -1
- package/dist/holmes/cli/agents.d.ts +8 -0
- package/dist/holmes/cli/agents.js +9 -5
- package/dist/holmes/cli/approve-cli.d.ts +2 -0
- package/dist/holmes/cli/approve-cli.js +392 -0
- package/dist/holmes/cli/approve-ref.d.ts +13 -7
- package/dist/holmes/cli/approve-ref.js +30 -10
- package/dist/holmes/cli/approve-status.d.ts +26 -2
- package/dist/holmes/cli/approve-status.js +98 -18
- package/dist/holmes/cli/approve-watch.d.ts +5 -0
- package/dist/holmes/cli/approve-watch.js +10 -5
- package/dist/holmes/cli/approve.d.ts +50 -13
- package/dist/holmes/cli/approve.js +260 -67
- package/dist/holmes/cli/attest.js +2 -1
- package/dist/holmes/cli/autonomy.d.ts +4 -1
- package/dist/holmes/cli/autonomy.js +17 -10
- package/dist/holmes/cli/codex-oracle.d.ts +11 -0
- package/dist/holmes/cli/codex-oracle.js +5 -1
- package/dist/holmes/cli/codex-toml.d.ts +10 -0
- package/dist/holmes/cli/codex-toml.js +36 -2
- package/dist/holmes/cli/doctor-boundary.d.ts +76 -0
- package/dist/holmes/cli/doctor-boundary.js +308 -0
- package/dist/holmes/cli/doctor-locks.d.ts +15 -0
- package/dist/holmes/cli/doctor-locks.js +119 -0
- package/dist/holmes/cli/doctor.d.ts +2 -0
- package/dist/holmes/cli/doctor.js +45 -5
- package/dist/holmes/cli/flags.d.ts +23 -0
- package/dist/holmes/cli/flags.js +89 -0
- package/dist/holmes/cli/index.d.ts +5 -1
- package/dist/holmes/cli/index.js +206 -424
- package/dist/holmes/cli/init.js +33 -0
- package/dist/holmes/cli/lock-recover.d.ts +5 -0
- package/dist/holmes/cli/lock-recover.js +126 -0
- package/dist/holmes/cli/mcp-processes.d.ts +32 -0
- package/dist/holmes/cli/mcp-processes.js +132 -0
- package/dist/holmes/cli/release-docs.js +1 -1
- package/dist/holmes/cli/run-exec.d.ts +141 -0
- package/dist/holmes/cli/run-exec.js +1435 -0
- package/dist/holmes/cli/run-provision.d.ts +8 -0
- package/dist/holmes/cli/run-provision.js +325 -0
- package/dist/holmes/cli/run-wiring.d.ts +69 -0
- package/dist/holmes/cli/run-wiring.js +270 -0
- package/dist/holmes/cli/run.d.ts +26 -0
- package/dist/holmes/cli/run.js +364 -83
- package/dist/holmes/cli/runtime-binding-approval.js +32 -19
- package/dist/holmes/cli/screen-safe.d.ts +3 -92
- package/dist/holmes/cli/screen-safe.js +18 -756
- package/dist/holmes/config/config.d.ts +2 -0
- package/dist/holmes/config/config.js +5 -2
- package/dist/holmes/cpg/foundation/language-matrix.js +2 -2
- package/dist/holmes/cpg/import-resolver.js +1 -1
- package/dist/holmes/governance/approval-decisions.d.ts +47 -0
- package/dist/holmes/governance/approval-decisions.js +29 -0
- package/dist/holmes/governance/approval-grants.d.ts +220 -1
- package/dist/holmes/governance/approval-grants.js +612 -33
- package/dist/holmes/governance/approval-queue.d.ts +31 -0
- package/dist/holmes/governance/approval-queue.js +122 -11
- package/dist/holmes/governance/approval-spend.d.ts +95 -0
- package/dist/holmes/governance/approval-spend.js +191 -0
- package/dist/holmes/governance/autonomous-shell.d.ts +61 -0
- package/dist/holmes/governance/autonomous-shell.js +332 -0
- package/dist/holmes/governance/autonomy.d.ts +5 -0
- package/dist/holmes/governance/autonomy.js +16 -11
- package/dist/holmes/governance/constitution.d.ts +5 -0
- package/dist/holmes/governance/constitution.js +32 -12
- package/dist/holmes/governance/full-autonomy.d.ts +10 -0
- package/dist/holmes/governance/full-autonomy.js +103 -7
- package/dist/holmes/governance/harness-catalog.d.ts +103 -0
- package/dist/holmes/governance/harness-catalog.js +348 -0
- package/dist/holmes/governance/human-channel.d.ts +38 -0
- package/dist/holmes/governance/human-channel.js +49 -0
- package/dist/holmes/governance/install-manifest.d.ts +22 -0
- package/dist/holmes/governance/install-manifest.js +160 -0
- package/dist/holmes/governance/ledger-rechain.js +2 -0
- package/dist/holmes/governance/ledger-store.conformance.d.ts +7 -1
- package/dist/holmes/governance/ledger-store.conformance.js +66 -0
- package/dist/holmes/governance/ledger-store.d.ts +88 -11
- package/dist/holmes/governance/ledger-store.js +186 -8
- package/dist/holmes/governance/provenance-chain.d.ts +16 -4
- package/dist/holmes/governance/provenance-chain.js +19 -4
- package/dist/holmes/governance/provenance-ledger.d.ts +6 -3
- package/dist/holmes/governance/provenance-ledger.js +53 -18
- package/dist/holmes/governance/push-gate-runner.js +11 -7
- package/dist/holmes/governance/recorded-pairs.d.ts +96 -0
- package/dist/holmes/governance/recorded-pairs.js +522 -0
- package/dist/holmes/governance/replica-id.d.ts +1 -1
- package/dist/holmes/governance/replica-id.js +1 -1
- package/dist/holmes/governance/spec-seam.d.ts +59 -0
- package/dist/holmes/governance/spec-seam.js +587 -0
- package/dist/holmes/governance/spend-kinds.d.ts +16 -0
- package/dist/holmes/governance/spend-kinds.js +18 -0
- package/dist/holmes/governance/tool-actions.js +2 -0
- package/dist/holmes/guardrail/decision-ledger.d.ts +2 -1
- package/dist/holmes/guardrail/decision-ledger.js +2 -1
- package/dist/holmes/guardrail/impact-gate.d.ts +1 -0
- package/dist/holmes/guardrail/impact-gate.js +1 -1
- package/dist/holmes/guardrail/line-continuation.d.ts +8 -0
- package/dist/holmes/guardrail/line-continuation.js +39 -0
- package/dist/holmes/guardrail/operator-person.d.ts +28 -4
- package/dist/holmes/guardrail/operator-person.js +57 -11
- package/dist/holmes/guardrail/refusal-codes.d.ts +8 -3
- package/dist/holmes/guardrail/refusal-codes.js +70 -10
- package/dist/holmes/guardrail/risk-classifier.d.ts +15 -9
- package/dist/holmes/guardrail/risk-classifier.js +245 -15
- package/dist/holmes/guardrail/risk-gate.d.ts +2 -8
- package/dist/holmes/guardrail/risk-gate.js +7 -34
- package/dist/holmes/guardrail/risk-types.d.ts +10 -0
- package/dist/holmes/guardrail/run-plan-scope.js +3 -1
- package/dist/holmes/guardrail/run-refusals.d.ts +6 -1
- package/dist/holmes/guardrail/run-refusals.js +36 -14
- package/dist/holmes/guardrail/run-stages.d.ts +10 -0
- package/dist/holmes/guardrail/run-stages.js +46 -6
- package/dist/holmes/guardrail/scope-judgment.js +1 -1
- package/dist/holmes/guardrail/shell-words.js +24 -3
- package/dist/holmes/guardrail/unresolved-write.d.ts +40 -0
- package/dist/holmes/guardrail/unresolved-write.js +556 -0
- package/dist/holmes/guardrail/write-target.d.ts +3 -0
- package/dist/holmes/guardrail/write-target.js +26 -5
- package/dist/holmes/hooks/pre-tool-use.d.ts +105 -1
- package/dist/holmes/hooks/pre-tool-use.js +1167 -168
- package/dist/holmes/hooks/rtm-refresh-child.d.ts +1 -1
- package/dist/holmes/hooks/rtm-refresh-child.js +1 -1
- package/dist/holmes/hooks/session-start.d.ts +5 -0
- package/dist/holmes/hooks/session-start.js +29 -1
- package/dist/holmes/hooks/stop.d.ts +23 -0
- package/dist/holmes/hooks/stop.js +88 -33
- package/dist/holmes/mcp/approval-adapters.js +3 -1
- package/dist/holmes/mcp/approval-commit.js +3 -2
- package/dist/holmes/mcp/approval-policy.d.ts +2 -1
- package/dist/holmes/mcp/approval-policy.js +3 -1
- package/dist/holmes/mcp/handlers/adoption.d.ts +1 -1
- package/dist/holmes/mcp/handlers/approval-ask.d.ts +14 -0
- package/dist/holmes/mcp/handlers/approval-ask.js +31 -6
- package/dist/holmes/mcp/handlers/entity-integration.d.ts +3 -3
- package/dist/holmes/mcp/handlers/entity-integration.js +29 -11
- package/dist/holmes/mcp/handlers/entity-renumber.d.ts +4 -4
- package/dist/holmes/mcp/handlers/entity-renumber.js +29 -11
- package/dist/holmes/mcp/handlers/entity-store.d.ts +2 -2
- package/dist/holmes/mcp/handlers/entity-store.js +133 -59
- package/dist/holmes/mcp/handlers/operator-inspection.d.ts +9 -5
- package/dist/holmes/mcp/handlers/operator-inspection.js +79 -16
- package/dist/holmes/mcp/handlers/phase-queries.d.ts +1 -1
- package/dist/holmes/mcp/handlers/requirement-triage.d.ts +4 -4
- package/dist/holmes/mcp/handlers/review-evidence.d.ts +2 -2
- package/dist/holmes/mcp/handlers/review-evidence.js +35 -11
- package/dist/holmes/mcp/handlers/review-queries.d.ts +5 -0
- package/dist/holmes/mcp/handlers/review-queries.js +8 -1
- package/dist/holmes/mcp/handlers/review-verdict.d.ts +3 -0
- package/dist/holmes/mcp/handlers/review-verdict.js +10 -3
- package/dist/holmes/mcp/handlers/risk-assessment.d.ts +7 -2
- package/dist/holmes/mcp/handlers/risk-assessment.js +34 -12
- package/dist/holmes/mcp/handlers/runtime-binding-tool.d.ts +2 -2
- package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +6 -1
- package/dist/holmes/mcp/handlers/slice-orchestration.js +14 -1
- package/dist/holmes/mcp/handlers/spec-approval.d.ts +15 -3
- package/dist/holmes/mcp/handlers/spec-approval.js +32 -5
- package/dist/holmes/mcp/handlers/spec-authoring.d.ts +2 -2
- package/dist/holmes/mcp/handlers/spec-authoring.js +19 -2
- package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts +11 -38
- package/dist/holmes/mcp/handlers/spec-lifecycle.js +441 -94
- package/dist/holmes/mcp/handlers/spec-queries.d.ts +2 -2
- package/dist/holmes/mcp/handlers/taint-screening.d.ts +1 -1
- package/dist/holmes/mcp/handlers/taint-screening.js +2 -2
- package/dist/holmes/mcp/handlers/test-execution.d.ts +1 -1
- package/dist/holmes/mcp/handlers/workspace-preflight.d.ts +5 -0
- package/dist/holmes/mcp/handlers/workspace-preflight.js +10 -2
- package/dist/holmes/mcp/handlers/workspace-queries.d.ts +2 -2
- package/dist/holmes/mcp/handlers.d.ts +99 -79
- package/dist/holmes/mcp/handlers.js +93 -25
- package/dist/holmes/mcp/harness-attestation.d.ts +78 -5
- package/dist/holmes/mcp/harness-attestation.js +325 -53
- package/dist/holmes/mcp/maintenance-analyze.d.ts +1 -1
- package/dist/holmes/mcp/maintenance-analyze.js +9 -9
- package/dist/holmes/mcp/maintenance-evidence.js +31 -2
- package/dist/holmes/mcp/requirement-triage-evidence.js +22 -13
- package/dist/holmes/mcp/server-staleness.d.ts +43 -0
- package/dist/holmes/mcp/server-staleness.js +158 -0
- package/dist/holmes/mcp/server.js +34 -9
- package/dist/holmes/mcp/spec-id-guard.js +1 -1
- package/dist/holmes/mcp/tool-schemas.d.ts +13 -0
- package/dist/holmes/mcp/tool-schemas.js +42 -2
- package/dist/holmes/project/act-root.d.ts +19 -0
- package/dist/holmes/project/act-root.js +100 -0
- package/dist/holmes/project/baseline.js +4 -3
- package/dist/holmes/project/bounded-group.d.ts +47 -0
- package/dist/holmes/project/bounded-group.js +140 -0
- package/dist/holmes/project/bounded-io.d.ts +50 -2
- package/dist/holmes/project/bounded-io.js +138 -6
- package/dist/holmes/project/change-source.js +2 -2
- package/dist/holmes/project/instance-id.d.ts +10 -0
- package/dist/holmes/project/instance-id.js +233 -0
- package/dist/holmes/project/machine-identity.d.ts +25 -0
- package/dist/holmes/project/machine-identity.js +133 -0
- package/dist/holmes/project/owned-lock.d.ts +84 -0
- package/dist/holmes/project/owned-lock.js +263 -0
- package/dist/holmes/project/plain-lock-fs.d.ts +2 -0
- package/dist/holmes/project/plain-lock-fs.js +126 -0
- package/dist/holmes/project/request-lock.d.ts +85 -0
- package/dist/holmes/project/request-lock.js +459 -0
- package/dist/holmes/project/root.d.ts +12 -4
- package/dist/holmes/project/root.js +26 -7
- package/dist/holmes/project/run-records.d.ts +19 -0
- package/dist/holmes/project/run-records.js +94 -12
- package/dist/holmes/project/screen-text.d.ts +94 -0
- package/dist/holmes/project/screen-text.js +763 -0
- package/dist/holmes/project/spend-lock.d.ts +82 -0
- package/dist/holmes/project/spend-lock.js +413 -0
- package/dist/holmes/project/workspace-preflight.d.ts +5 -0
- package/dist/holmes/project/workspace-preflight.js +24 -1
- package/dist/holmes/refresh/freshness-coordinator.d.ts +1 -1
- package/dist/holmes/refresh/freshness-coordinator.js +1 -1
- package/dist/holmes/review/condition-hunk-replay.js +4 -2
- package/dist/holmes/review/confidence-calibration.d.ts +1 -1
- package/dist/holmes/review/confidence-calibration.js +1 -1
- package/dist/holmes/review/content-verify.js +1 -1
- package/dist/holmes/review/hop-ablation.d.ts +4 -4
- package/dist/holmes/review/hop-ablation.js +5 -5
- package/dist/holmes/review/point-in-time-replay.js +12 -3
- package/dist/holmes/review/rank-diagnosis.d.ts +2 -2
- package/dist/holmes/review/rank-diagnosis.js +1 -1
- package/dist/holmes/review/replay-corpus.d.ts +10 -4
- package/dist/holmes/review/replay-corpus.js +25 -9
- package/dist/holmes/review/requirement-triage.js +2 -2
- package/dist/holmes/review/semantic-arm.d.ts +3 -3
- package/dist/holmes/review/semantic-arm.js +3 -3
- package/dist/holmes/review/test-outcomes.js +3 -1
- package/dist/holmes/review/test-runner.d.ts +11 -0
- package/dist/holmes/review/test-runner.js +31 -10
- package/dist/holmes/review/test-selection-breadth.js +2 -2
- package/dist/holmes/review/verdicts.d.ts +109 -7
- package/dist/holmes/review/verdicts.js +653 -34
- package/dist/holmes/rtm/anchor-census.d.ts +9 -0
- package/dist/holmes/rtm/anchor-census.js +151 -0
- package/dist/holmes/rtm/anchor-ids.d.ts +25 -1
- package/dist/holmes/rtm/anchor-ids.js +45 -2
- package/dist/holmes/rtm/comment-ranges.d.ts +2 -0
- package/dist/holmes/rtm/comment-ranges.js +104 -0
- package/dist/holmes/rtm/counted-tests.d.ts +1 -0
- package/dist/holmes/rtm/counted-tests.js +63 -0
- package/dist/holmes/rtm/impact-advisory.d.ts +1 -1
- package/dist/holmes/rtm/known-defects.js +1 -1
- package/dist/holmes/rtm/localize.js +1 -1
- package/dist/holmes/rtm/taint-benchmark.d.ts +1 -1
- package/dist/holmes/rtm/taint-vocabulary.d.ts +1 -1
- package/dist/holmes/rtm/test-scope.d.ts +31 -0
- package/dist/holmes/rtm/test-scope.js +166 -5
- package/dist/holmes/rtm/trace-gaps.js +1 -1
- package/dist/holmes/runtime/dispatch.d.ts +10 -0
- package/dist/holmes/runtime/dispatch.js +12 -1
- package/dist/holmes/semantic/cloud-usage.d.ts +1 -1
- package/dist/holmes/semantic/cloud-usage.js +1 -1
- package/dist/holmes/semantic/unreadable-paths.d.ts +1 -1
- package/dist/holmes/semantic/unreadable-paths.js +1 -1
- package/dist/holmes/spec/approval-blockers.js +1 -1
- package/dist/holmes/spec/entity-store.d.ts +6 -1
- package/dist/holmes/spec/entity-store.js +16 -2
- package/dist/holmes/spec/entity-transaction.d.ts +7 -2
- package/dist/holmes/spec/entity-transaction.js +87 -170
- package/dist/holmes/spec/spec-store.d.ts +12 -6
- package/dist/holmes/spec/spec-store.js +4 -2
- package/dist/holmes/spec/spec-types.js +1 -1
- package/dist/holmes/spec/succession-guard.d.ts +56 -0
- package/dist/holmes/spec/succession-guard.js +187 -0
- package/dist/holmes/spec/succession.d.ts +70 -0
- package/dist/holmes/spec/succession.js +171 -0
- package/dist/holmes/spec/transition-policy.d.ts +2 -2
- package/docs/install-guide.md +9 -3
- package/docs/language-support.md +78 -0
- package/package.json +4 -3
- package/playbooks/author-slice/PLAYBOOK.md +1 -1
- package/playbooks/promote-slice/PLAYBOOK.md +5 -1
- package/playbooks/publish/PLAYBOOK.md +45 -33
- package/dist/holmes/review/manual-baseline.d.ts +0 -209
- package/dist/holmes/review/manual-baseline.js +0 -2847
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
export interface SeamGrant {
|
|
2
|
+
path: string;
|
|
3
|
+
blob: string | null;
|
|
4
|
+
}
|
|
5
|
+
export interface SeamState {
|
|
6
|
+
tips: string[];
|
|
7
|
+
granted: SeamGrant[];
|
|
8
|
+
accepted: SeamGrant[];
|
|
9
|
+
history: Record<string, unknown> | null;
|
|
10
|
+
}
|
|
11
|
+
export interface Unexplained {
|
|
12
|
+
where: 'index' | 'commit' | 'scan';
|
|
13
|
+
path?: string;
|
|
14
|
+
commit?: string;
|
|
15
|
+
detail?: string;
|
|
16
|
+
}
|
|
17
|
+
/** At most this many commits new since the recorded tips are read; more is itself unexplained. */
|
|
18
|
+
export declare const SEAM_MAX_COMMITS = 200;
|
|
19
|
+
/**
|
|
20
|
+
* The spec-store changes no granted staging act accounts for: in the index, in the commits new since the recorded tips,
|
|
21
|
+
* and any history file that moved since the baseline. A ledger with no baseline is initialised and explains nothing.
|
|
22
|
+
*/
|
|
23
|
+
export declare function unexplainedSpecChanges(root: string, specsDir: string): Unexplained[];
|
|
24
|
+
/** Records a baseline of the tips now and the granted pairs still staged, when either differs from the last one. */
|
|
25
|
+
export declare function advanceSpecSeam(root: string, specsDir: string): void;
|
|
26
|
+
/**
|
|
27
|
+
* @implements A-SPEC-792.32 — the one calculator of what a staging approval approved: git's object id of these bytes
|
|
28
|
+
* (`sha1("blob <len>\0" + bytes)`), computed in process, so no clean filter or attribute of the work tree runs.
|
|
29
|
+
*/
|
|
30
|
+
export declare function blobOf(bytes: Buffer, format?: 'sha1' | 'sha256'): string;
|
|
31
|
+
/** The repository's object format (a SHA-256 repository names its blobs by SHA-256). */
|
|
32
|
+
export declare function objectFormatOf(root: string): 'sha1' | 'sha256';
|
|
33
|
+
/** @implements A-SPEC-792.32 — the bytes a grant may name: a regular file without an execute bit (git mode 100644). */
|
|
34
|
+
export declare function grantableBytes(abs: string): Buffer | null;
|
|
35
|
+
export interface WorktreeChange {
|
|
36
|
+
path: string;
|
|
37
|
+
deleted: boolean;
|
|
38
|
+
untracked: boolean;
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* @implements A-SPEC-792.32 — what `git add` of these root-relative prefixes (every path when null) would change,
|
|
42
|
+
* without `git status`: a racily clean entry makes status re-hash the file through its clean filter, which ran the
|
|
43
|
+
* agent's filter command inside the hook (measured 2026-10-26). The index is read as recorded and each tracked file is
|
|
44
|
+
* compared by `blobOf` of its bytes and its mode; an untracked file is listed by `ls-files -o`. A filter, autocrlf or a
|
|
45
|
+
* mode the comparison does not follow reads as a change, which fails closed.
|
|
46
|
+
*/
|
|
47
|
+
export declare function worktreeChanges(root: string, prefixes: string[] | null): WorktreeChange[];
|
|
48
|
+
/** @implements A-SPEC-792.32 — writes exactly these (path, blob) pairs of the spec store as a grant, nothing else. */
|
|
49
|
+
export declare function recordProvenGrant(root: string, specsDir: string, proven: Array<{
|
|
50
|
+
path: string;
|
|
51
|
+
blob: string | null;
|
|
52
|
+
}>): void;
|
|
53
|
+
/**
|
|
54
|
+
* A granted spec-staging act (the person path): the path and blob of each changed spec file the command's `git add` or
|
|
55
|
+
* `git stage` segments name. @implements A-SPEC-792.32 — a command that names no spec path grants none (the
|
|
56
|
+
* every-changed-spec fallback is gone), and the blob is `blobOf` over a regular non-executable file, never a hash
|
|
57
|
+
* through git.
|
|
58
|
+
*/
|
|
59
|
+
export declare function recordGrantedStaging(root: string, specsDir: string, command: string, cwd: string): void;
|
|
@@ -0,0 +1,587 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
|
|
3
|
+
if (k2 === undefined) k2 = k;
|
|
4
|
+
var desc = Object.getOwnPropertyDescriptor(m, k);
|
|
5
|
+
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
|
6
|
+
desc = { enumerable: true, get: function() { return m[k]; } };
|
|
7
|
+
}
|
|
8
|
+
Object.defineProperty(o, k2, desc);
|
|
9
|
+
}) : (function(o, m, k, k2) {
|
|
10
|
+
if (k2 === undefined) k2 = k;
|
|
11
|
+
o[k2] = m[k];
|
|
12
|
+
}));
|
|
13
|
+
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
|
|
14
|
+
Object.defineProperty(o, "default", { enumerable: true, value: v });
|
|
15
|
+
}) : function(o, v) {
|
|
16
|
+
o["default"] = v;
|
|
17
|
+
});
|
|
18
|
+
var __importStar = (this && this.__importStar) || (function () {
|
|
19
|
+
var ownKeys = function(o) {
|
|
20
|
+
ownKeys = Object.getOwnPropertyNames || function (o) {
|
|
21
|
+
var ar = [];
|
|
22
|
+
for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
|
|
23
|
+
return ar;
|
|
24
|
+
};
|
|
25
|
+
return ownKeys(o);
|
|
26
|
+
};
|
|
27
|
+
return function (mod) {
|
|
28
|
+
if (mod && mod.__esModule) return mod;
|
|
29
|
+
var result = {};
|
|
30
|
+
if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
|
|
31
|
+
__setModuleDefault(result, mod);
|
|
32
|
+
return result;
|
|
33
|
+
};
|
|
34
|
+
})();
|
|
35
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
|
+
exports.SEAM_MAX_COMMITS = void 0;
|
|
37
|
+
exports.unexplainedSpecChanges = unexplainedSpecChanges;
|
|
38
|
+
exports.advanceSpecSeam = advanceSpecSeam;
|
|
39
|
+
exports.blobOf = blobOf;
|
|
40
|
+
exports.objectFormatOf = objectFormatOf;
|
|
41
|
+
exports.grantableBytes = grantableBytes;
|
|
42
|
+
exports.worktreeChanges = worktreeChanges;
|
|
43
|
+
exports.recordProvenGrant = recordProvenGrant;
|
|
44
|
+
exports.recordGrantedStaging = recordGrantedStaging;
|
|
45
|
+
// @implements A-SPEC-792.13, A-SPEC-792.14, A-SPEC-222.10, A-SPEC-222.12, A-SPEC-222.13, A-SPEC-222.15, A-SPEC-794.46
|
|
46
|
+
/**
|
|
47
|
+
* Spec staging judged by its result. A shell act can stage or commit spec-store changes in a form no text detector
|
|
48
|
+
* reads (an alias, an interpreter, a quoted verb); what it leaves behind is the same: an index entry or a new commit
|
|
49
|
+
* holding spec content. Each such change must be one a granted staging act recorded, or the Stop gate blocks.
|
|
50
|
+
*
|
|
51
|
+
* @implements A-SPEC-792.14 — the seam keeps nothing the agent can write: its baseline (ref tips, history files and the
|
|
52
|
+
* still-staged grants) and each grant are provenance-ledger events, and only a ledger with no baseline is a first start.
|
|
53
|
+
* A remote-tracking ref vouches for nothing.
|
|
54
|
+
*/
|
|
55
|
+
const crypto = __importStar(require("node:crypto"));
|
|
56
|
+
const fs = __importStar(require("node:fs"));
|
|
57
|
+
const path = __importStar(require("node:path"));
|
|
58
|
+
const bounded_io_1 = require("../project/bounded-io");
|
|
59
|
+
const ledger_store_1 = require("./ledger-store");
|
|
60
|
+
/** @implements A-SPEC-792.15 — at most this many accepted (path, blob) pairs ride a baseline. */
|
|
61
|
+
const ACCEPTED_KEPT = 2000;
|
|
62
|
+
/** At most this many commits new since the recorded tips are read; more is itself unexplained. */
|
|
63
|
+
exports.SEAM_MAX_COMMITS = 200;
|
|
64
|
+
const ZERO = /^0+$/;
|
|
65
|
+
const BASELINE = 'spec-seam-baseline';
|
|
66
|
+
const GRANT = 'spec-seam-grant';
|
|
67
|
+
/** A git child that did not answer; `answer` says whether there is a repository at all. */
|
|
68
|
+
class SeamGitError extends Error {
|
|
69
|
+
answer;
|
|
70
|
+
constructor(answer, message) {
|
|
71
|
+
super(message);
|
|
72
|
+
this.answer = answer;
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* git in the judgments' environment (A-SPEC-102.26: no inherited GIT_*, no replace objects, no grafts file) without
|
|
77
|
+
* fsmonitor, through the bounded child of A-SPEC-734 (a root whose git timed out answers at once).
|
|
78
|
+
*/
|
|
79
|
+
function git(root, args, input) {
|
|
80
|
+
// @implements A-SPEC-792.43 — the judgment's values pinned after gitOnce's shared environment, which drops them
|
|
81
|
+
const r = (0, bounded_io_1.gitOnce)(root, ['-c', 'core.fsmonitor=false', ...args], 'repo', { pinned: (0, bounded_io_1.judgmentPins)(), ...(input === undefined ? {} : { input }) });
|
|
82
|
+
if (r.status === 0 && r.error === undefined)
|
|
83
|
+
return r.stdout;
|
|
84
|
+
throw new SeamGitError((0, bounded_io_1.gitAnswerOf)(r, root), `git ${args[0]}: ${String(r.stderr ?? r.error?.message ?? '').split('\n')[0].slice(0, 120)}`);
|
|
85
|
+
}
|
|
86
|
+
const noRepository = (e) => e instanceof SeamGitError && e.answer === 'no-repository';
|
|
87
|
+
/** The store's path from the top of the work tree, '/'-separated. */
|
|
88
|
+
// A-SPEC-222.15 (low): the top of the work tree is read once per root, not three times per judgement
|
|
89
|
+
const topMemo = new Map();
|
|
90
|
+
function storeRel(root, specsDir) {
|
|
91
|
+
let top = topMemo.get(root);
|
|
92
|
+
if (top === undefined) {
|
|
93
|
+
top = fs.realpathSync(git(root, ['rev-parse', '--show-toplevel']).trim());
|
|
94
|
+
if (topMemo.size > 64)
|
|
95
|
+
topMemo.clear();
|
|
96
|
+
topMemo.set(root, top);
|
|
97
|
+
}
|
|
98
|
+
return path.relative(top, fs.realpathSync(specsDir)).split(path.sep).join('/');
|
|
99
|
+
}
|
|
100
|
+
/** @implements A-SPEC-792.14 — the store in any case: on a case-folding disk `.ax/Specs` is the same directory. */
|
|
101
|
+
const storeSpec = (rel) => `:(icase)${rel}`;
|
|
102
|
+
const ledgerOf = (root) => new ledger_store_1.FileLedgerStore(path.join(root, '.ax', 'ledger'));
|
|
103
|
+
/**
|
|
104
|
+
* @implements A-SPEC-222.12 (N1) — another replica's ledger file (any `provenance*.jsonl` but this writer's own, the
|
|
105
|
+
* legacy file included), as git names it from the top: the trusted-events port counts such a file once it is in HEAD,
|
|
106
|
+
* so the seam explains it like a spec file. Null without a ledger directory.
|
|
107
|
+
*/
|
|
108
|
+
function foreignLedger(root) {
|
|
109
|
+
const dir = path.join(root, '.ax', 'ledger');
|
|
110
|
+
if (!fs.existsSync(dir))
|
|
111
|
+
return null;
|
|
112
|
+
const rel = storeRel(root, dir);
|
|
113
|
+
let own = null;
|
|
114
|
+
try {
|
|
115
|
+
own = ledgerOf(root).replicaId();
|
|
116
|
+
}
|
|
117
|
+
catch {
|
|
118
|
+
own = null;
|
|
119
|
+
}
|
|
120
|
+
const prefix = `${rel.toLowerCase()}/`;
|
|
121
|
+
return { rel, is: (p) => {
|
|
122
|
+
if (!p.toLowerCase().startsWith(prefix))
|
|
123
|
+
return false;
|
|
124
|
+
const m = /^provenance(?:\.([^/]+))?\.jsonl$/i.exec(p.slice(prefix.length));
|
|
125
|
+
return m !== null && !(own !== null && m[1] === own);
|
|
126
|
+
} };
|
|
127
|
+
}
|
|
128
|
+
const grantInput = (g, tag = 'grant') => `${tag}:${g.path}\t${g.blob ?? '-'}`;
|
|
129
|
+
const grantOf = (input, tag = 'grant') => {
|
|
130
|
+
const m = new RegExp(`^${tag}:(.*)\\t([0-9a-f]+|-)$`).exec(input);
|
|
131
|
+
return m ? { path: m[1], blob: m[2] === '-' ? null : m[2] } : null;
|
|
132
|
+
};
|
|
133
|
+
/** The last baseline and the grants after it; null when the ledger holds no baseline (a first start). Throws when unreadable. */
|
|
134
|
+
function readState(root) {
|
|
135
|
+
// @implements A-SPEC-222.10 — H-C: the seam's baseline and grants explain spec changes, so they come from trusted
|
|
136
|
+
// events only (a chainless grant line in an untracked replica explained a hand-written spec)
|
|
137
|
+
const { TrustedLedgerStore } = require('./recorded-pairs');
|
|
138
|
+
const store = new TrustedLedgerStore(path.join(root, '.ax', 'ledger'));
|
|
139
|
+
// @implements A-SPEC-222.12 — H1: an untrusted record is never "a first start". With this writer's chain broken, or a
|
|
140
|
+
// baseline only in rows the port does not trust, the seam throws: its callers report a scan finding and write nothing
|
|
141
|
+
// (a re-baseline here explained a hand-written spec commit, and stayed after the chain was repaired)
|
|
142
|
+
if (store.ownChainBroken())
|
|
143
|
+
throw new Error('this writer\'s ledger chain does not verify, so the spec seam\'s record is not trusted — repair it from a terminal with `holmes-kit ledger rechain` (review an uncommitted ledger first: it is re-chained whole)');
|
|
144
|
+
// @implements A-SPEC-222.13 — and never shorter than it was: against HEAD for a committed ledger (the Stop rollback
|
|
145
|
+
// check's judgement), and against the seam's own mark outside the ledger for one not committed (a cut, emptied or
|
|
146
|
+
// deleted ledger read as a first start and explained a hand-written spec commit)
|
|
147
|
+
const { ownLedgerShortened, CommittedReadError } = require('./recorded-pairs');
|
|
148
|
+
// @implements A-SPEC-222.15 (low) — an unreadable replica id is said as it is (it read as a shortened ledger and told
|
|
149
|
+
// the legacy file to be restored)
|
|
150
|
+
let own;
|
|
151
|
+
try {
|
|
152
|
+
own = store.replicaId();
|
|
153
|
+
}
|
|
154
|
+
catch {
|
|
155
|
+
throw new Error('this writer\'s replica id could not be read — retry when it can; nothing needs restoring');
|
|
156
|
+
}
|
|
157
|
+
// @implements A-SPEC-222.14 — recovery names this writer's own file only (the whole directory dropped other files'
|
|
158
|
+
// uncommitted rows and raised the mark refusal next), says what a restore loses, and names the mark
|
|
159
|
+
// A-SPEC-222.15 (item 5): the mark's recovery removes this branch's entry, not the file every branch's evidence is in
|
|
160
|
+
const ownRel = `.ax/ledger/provenance.${own}.jsonl`;
|
|
161
|
+
const branch = branchOf(root);
|
|
162
|
+
const entryAdvice = `a person who reviewed the ledger removes this branch's entry ${JSON.stringify(branch)} from ${SEAM_MARK_REL}`;
|
|
163
|
+
const markAdvice = `if the seam then names its mark, ${entryAdvice}`;
|
|
164
|
+
let shortened;
|
|
165
|
+
try {
|
|
166
|
+
shortened = ownLedgerShortened(root);
|
|
167
|
+
}
|
|
168
|
+
catch (e) {
|
|
169
|
+
// @implements A-SPEC-222.14 (M1) — an unread HEAD is not a shortened ledger: nothing is to be restored
|
|
170
|
+
if (e instanceof CommittedReadError)
|
|
171
|
+
throw new Error(`HEAD could not be read (${e.message}) — retry when git answers; nothing needs restoring`);
|
|
172
|
+
throw e;
|
|
173
|
+
}
|
|
174
|
+
if (shortened)
|
|
175
|
+
throw new Error(`this writer's ledger is shorter than HEAD holds it (cut, emptied or deleted), so the spec seam's record is not trusted — restore this writer's own file from git (git checkout -- ${ownRel}); rows HEAD does not hold are lost, and ${markAdvice}`);
|
|
176
|
+
const ownRows = store.loadAllRaw().filter((e) => e.replicaId === own);
|
|
177
|
+
const holds = (m) => m.replica === own && ownRows.some((e) => e.seq === m.seq && e.hash === m.hash);
|
|
178
|
+
judgedBranch = { root, branch };
|
|
179
|
+
const mark = readSeamMark(root, branch, holds);
|
|
180
|
+
if (mark !== null && mark.replica === own && !holds(mark)) {
|
|
181
|
+
throw new Error(`this writer's ledger no longer holds the spec seam's last record on this branch (seq ${mark.seq}), so it was cut, emptied, deleted or rewritten — restore ${ownRel} if it was cut; after a review, a rechain or another rewrite you made, ${entryAdvice} (A-SPEC-222.15)`);
|
|
182
|
+
}
|
|
183
|
+
const evs = store.loadAll();
|
|
184
|
+
let at = -1;
|
|
185
|
+
for (let i = evs.length - 1; i >= 0; i--)
|
|
186
|
+
if (evs[i].kind === BASELINE) {
|
|
187
|
+
at = i;
|
|
188
|
+
break;
|
|
189
|
+
}
|
|
190
|
+
if (at < 0) {
|
|
191
|
+
if (store.loadAllRaw().some((e) => e.kind === BASELINE))
|
|
192
|
+
throw new Error('the spec seam\'s baseline is only in ledger rows that are not trusted — its record is not re-made; repair or commit the replica that holds it');
|
|
193
|
+
return null;
|
|
194
|
+
}
|
|
195
|
+
const inputs = evs[at].inputs ?? [];
|
|
196
|
+
const tips = inputs.filter((x) => x.startsWith('tip:')).map((x) => x.slice(4));
|
|
197
|
+
const hist = inputs.find((x) => x.startsWith('history:'));
|
|
198
|
+
const granted = [];
|
|
199
|
+
for (const e of [evs[at], ...evs.slice(at + 1).filter((x) => x.kind === GRANT)]) {
|
|
200
|
+
for (const x of e.inputs ?? []) {
|
|
201
|
+
const g = grantOf(x);
|
|
202
|
+
if (g && !granted.some((y) => y.path === g.path && y.blob === g.blob))
|
|
203
|
+
granted.push(g);
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
const accepted = inputs.map((x) => grantOf(x, 'accepted')).filter((g) => g !== null);
|
|
207
|
+
let history = null;
|
|
208
|
+
try {
|
|
209
|
+
history = hist ? JSON.parse(hist.slice(8)) : null;
|
|
210
|
+
}
|
|
211
|
+
catch {
|
|
212
|
+
history = null;
|
|
213
|
+
}
|
|
214
|
+
return { tips, granted, accepted, history };
|
|
215
|
+
}
|
|
216
|
+
function appendEvent(root, kind, summary, inputs) {
|
|
217
|
+
const store = ledgerOf(root);
|
|
218
|
+
const evt = store.append({ ts: new Date().toISOString(), actor: 'holmes-spec-seam', kind, summary, inputs });
|
|
219
|
+
try {
|
|
220
|
+
writeSeamMark(root, { replica: store.replicaId(), seq: evt.seq, hash: evt.hash });
|
|
221
|
+
}
|
|
222
|
+
catch { /* unmarked: a later read takes the ledger as it is */ }
|
|
223
|
+
}
|
|
224
|
+
/**
|
|
225
|
+
* @implements A-SPEC-222.13 — the seam's mark outside the ledger: this writer's replica and the last record the seam
|
|
226
|
+
* wrote. The ledger must still hold it.
|
|
227
|
+
* @implements A-SPEC-222.14 — this is tamper EVIDENCE against mistakes and ordinary tool paths, not prevention: code
|
|
228
|
+
* running as the same user can defeat the mark and the ledger together. The defence is a key the agent cannot read
|
|
229
|
+
* (planned for 0.41). A mark is kept per branch:
|
|
230
|
+
* another branch's ledger need not hold this one's record.
|
|
231
|
+
* @implements A-SPEC-222.15 (item 4) — the key is git's own answer, so a project in a subdirectory, a reftable
|
|
232
|
+
* repository and each detached commit have their own (the git directory's HEAD file gave one constant there). A flat
|
|
233
|
+
* mark from 222.13 moves to the current branch when the ledger holds its row and is dropped when it does not (read as
|
|
234
|
+
* this branch's, it stuck after an upgrade made on another). Keys of branches that no longer exist are dropped on write.
|
|
235
|
+
*/
|
|
236
|
+
const SEAM_MARK_REL = '.ax/state/spec-seam-mark.json';
|
|
237
|
+
const SEAM_MARK = path.join('.ax', 'state', 'spec-seam-mark.json');
|
|
238
|
+
const markOf = (m) => {
|
|
239
|
+
const r = m;
|
|
240
|
+
return r !== null && typeof r === 'object' && typeof r.replica === 'string' && typeof r.seq === 'number' && typeof r.hash === 'string' ? { replica: r.replica, seq: r.seq, hash: r.hash } : null;
|
|
241
|
+
};
|
|
242
|
+
/** The ref HEAD names (`refs/heads/feat`), `detached:<commit>`, or `unborn` with no commit and no ref. */
|
|
243
|
+
function branchOf(root) {
|
|
244
|
+
// one child: the commit, then the ref HEAD names (`HEAD` when detached); an unborn HEAD fails it
|
|
245
|
+
const r = (0, bounded_io_1.gitOnce)(root, ['-c', 'core.fsmonitor=false', 'rev-parse', 'HEAD', '--symbolic-full-name', 'HEAD'], 'repo', { pinned: (0, bounded_io_1.judgmentPins)() });
|
|
246
|
+
const [commit, ref] = r.status === 0 && r.error === undefined ? String(r.stdout).trim().split('\n').map((s) => s.trim()) : [];
|
|
247
|
+
if (!commit || !ref)
|
|
248
|
+
return 'unborn';
|
|
249
|
+
return ref === 'HEAD' ? `detached:${commit}` : ref;
|
|
250
|
+
}
|
|
251
|
+
function readMarks(root) {
|
|
252
|
+
try {
|
|
253
|
+
return JSON.parse(fs.readFileSync(path.join(root, SEAM_MARK), 'utf8'));
|
|
254
|
+
}
|
|
255
|
+
catch {
|
|
256
|
+
return {};
|
|
257
|
+
}
|
|
258
|
+
}
|
|
259
|
+
function writeMarks(root, branches) {
|
|
260
|
+
const file = path.join(root, SEAM_MARK);
|
|
261
|
+
fs.mkdirSync(path.dirname(file), { recursive: true });
|
|
262
|
+
const tmp = `${file}.${process.pid}.tmp`;
|
|
263
|
+
fs.writeFileSync(tmp, `${JSON.stringify({ branches })}\n`);
|
|
264
|
+
fs.renameSync(tmp, file);
|
|
265
|
+
}
|
|
266
|
+
function readSeamMark(root, branch, holds) {
|
|
267
|
+
const m = readMarks(root);
|
|
268
|
+
if (typeof m.branches === 'object' && m.branches !== null)
|
|
269
|
+
return markOf(m.branches[branch]);
|
|
270
|
+
const flat = markOf(m);
|
|
271
|
+
if (flat === null)
|
|
272
|
+
return null;
|
|
273
|
+
const kept = holds(flat);
|
|
274
|
+
try {
|
|
275
|
+
writeMarks(root, kept ? { [branch]: flat } : {});
|
|
276
|
+
}
|
|
277
|
+
catch { /* moved on the next write */ }
|
|
278
|
+
return kept ? flat : null;
|
|
279
|
+
}
|
|
280
|
+
/** The branch the last readState judged, taken once by the write that follows it in the same judgement (one git child). */
|
|
281
|
+
let judgedBranch = null;
|
|
282
|
+
const MARK_KEYS_KEPT = 16;
|
|
283
|
+
function writeSeamMark(root, mark) {
|
|
284
|
+
const m = readMarks(root);
|
|
285
|
+
const old = (typeof m.branches === 'object' && m.branches !== null ? m.branches : {});
|
|
286
|
+
const branch = judgedBranch?.root === root ? judgedBranch.branch : branchOf(root);
|
|
287
|
+
judgedBranch = null;
|
|
288
|
+
const branches = { ...old };
|
|
289
|
+
// keys of branches that no longer exist are dropped once the map grows (a git child only then)
|
|
290
|
+
if (Object.keys(old).length >= MARK_KEYS_KEPT) {
|
|
291
|
+
let live = null;
|
|
292
|
+
try {
|
|
293
|
+
live = new Set(git(root, ['for-each-ref', '--format=%(refname)', 'refs/heads']).split('\n').filter(Boolean));
|
|
294
|
+
}
|
|
295
|
+
catch {
|
|
296
|
+
live = null;
|
|
297
|
+
}
|
|
298
|
+
if (live !== null)
|
|
299
|
+
for (const k of Object.keys(branches))
|
|
300
|
+
if (!live.has(k))
|
|
301
|
+
delete branches[k];
|
|
302
|
+
}
|
|
303
|
+
branches[branch] = mark;
|
|
304
|
+
writeMarks(root, branches);
|
|
305
|
+
}
|
|
306
|
+
function writeBaseline(root, tips, granted, accepted = []) {
|
|
307
|
+
const { historyFiles } = require('../review/verdicts');
|
|
308
|
+
appendEvent(root, BASELINE, `spec seam baseline: ${tips.length} tip(s), ${granted.length} grant(s) kept, ${accepted.length} accepted`, [...tips.map((t) => `tip:${t}`), `history:${JSON.stringify(historyFiles(root))}`, ...granted.map((g) => grantInput(g)), ...accepted.map((g) => grantInput(g, 'accepted'))]);
|
|
309
|
+
}
|
|
310
|
+
/** HEAD and the tip of every local branch and tag, now. */
|
|
311
|
+
function tipsNow(root) {
|
|
312
|
+
const refs = git(root, ['for-each-ref', '--format=%(objectname)', 'refs/heads', 'refs/tags']).split('\n').filter(Boolean);
|
|
313
|
+
let head = [];
|
|
314
|
+
try {
|
|
315
|
+
head = [git(root, ['rev-parse', '--verify', '-q', 'HEAD']).trim()].filter(Boolean);
|
|
316
|
+
}
|
|
317
|
+
catch { /* unborn */ }
|
|
318
|
+
return [...new Set([...head, ...refs])];
|
|
319
|
+
}
|
|
320
|
+
/** `{ path, blob, mode }` of a `--raw -z` listing; blob null for a deletion; mode is the new side's. */
|
|
321
|
+
function rawEntries(text) {
|
|
322
|
+
const parts = text.split('\0');
|
|
323
|
+
const out = [];
|
|
324
|
+
for (let i = 0; i + 1 < parts.length; i += 2) {
|
|
325
|
+
const meta = parts[i].replace(/^\n/, '').split(' ');
|
|
326
|
+
if (meta.length < 5 || !meta[0].startsWith(':'))
|
|
327
|
+
break;
|
|
328
|
+
out.push({ path: parts[i + 1], blob: ZERO.test(meta[3]) ? null : meta[3], mode: meta[1] });
|
|
329
|
+
}
|
|
330
|
+
return out;
|
|
331
|
+
}
|
|
332
|
+
// @implements A-SPEC-792.15 — granted, or accepted before: content once approved stays explained when its commit is rewritten
|
|
333
|
+
// @implements A-SPEC-792.30 — a present entry is granted only as a regular file (mode 100644): a link's blob is its text
|
|
334
|
+
const granted = (s, e) => (e.blob === null || e.mode === undefined || e.mode === '100644')
|
|
335
|
+
&& [...s.granted, ...s.accepted].some((g) => g.path === e.path && g.blob === e.blob);
|
|
336
|
+
/** The spec-store entries the index changes against HEAD (the empty tree when HEAD is unborn). */
|
|
337
|
+
function stagedEntries(root, rel) {
|
|
338
|
+
return rawEntries(git(root, ['diff', '--cached', '--raw', '-z', '--no-renames', '--no-abbrev', '--', storeSpec(rel)]));
|
|
339
|
+
}
|
|
340
|
+
/**
|
|
341
|
+
* The spec-store changes no granted staging act accounts for: in the index, in the commits new since the recorded tips,
|
|
342
|
+
* and any history file that moved since the baseline. A ledger with no baseline is initialised and explains nothing.
|
|
343
|
+
*/
|
|
344
|
+
function unexplainedSpecChanges(root, specsDir) {
|
|
345
|
+
let state;
|
|
346
|
+
try {
|
|
347
|
+
if (!fs.existsSync(specsDir))
|
|
348
|
+
return [];
|
|
349
|
+
storeRel(root, specsDir); // no repository: nothing is staged or committed
|
|
350
|
+
state = readState(root);
|
|
351
|
+
if (state === null) {
|
|
352
|
+
writeBaseline(root, tipsNow(root), []);
|
|
353
|
+
return [];
|
|
354
|
+
}
|
|
355
|
+
}
|
|
356
|
+
catch (e) {
|
|
357
|
+
if (noRepository(e))
|
|
358
|
+
return [];
|
|
359
|
+
// A-SPEC-222.14 (low a): 120 characters cut the recovery away; A-SPEC-222.15: the branch entry made it longer
|
|
360
|
+
return [{ where: 'scan', detail: `the spec seam could not be read (${String(e.message ?? e).split('\n')[0].slice(0, 800)})` }];
|
|
361
|
+
}
|
|
362
|
+
const s = state;
|
|
363
|
+
try {
|
|
364
|
+
const rel = storeRel(root, specsDir);
|
|
365
|
+
const out = stagedEntries(root, rel).filter((e) => !granted(s, e)).map((e) => ({ where: 'index', path: e.path }));
|
|
366
|
+
// @implements A-SPEC-222.12 (N1) — and another replica's ledger file in the index
|
|
367
|
+
const fl = foreignLedger(root);
|
|
368
|
+
if (fl)
|
|
369
|
+
out.push(...stagedEntries(root, fl.rel).filter((e) => fl.is(e.path) && !granted(s, e)).map((e) => ({ where: 'index', path: e.path })));
|
|
370
|
+
const ledgerSide = (p) => fl !== null && p.toLowerCase().startsWith(`${fl.rel.toLowerCase()}/`);
|
|
371
|
+
// @implements A-SPEC-792.14 — a shallow file or alternates added since the baseline can hide commits from the scan
|
|
372
|
+
const { historyMoved } = require('../review/verdicts');
|
|
373
|
+
const moved = s.history === null ? ['shallow', 'grafts', 'alternates', 'http_alternates'] : historyMoved(root, s.history);
|
|
374
|
+
if (moved.length > 0)
|
|
375
|
+
out.push({ where: 'scan', detail: `the repository's ${moved.join(' and ')} file changed since the spec seam's baseline` });
|
|
376
|
+
let head = false;
|
|
377
|
+
try {
|
|
378
|
+
git(root, ['rev-parse', '--verify', '-q', 'HEAD']);
|
|
379
|
+
head = true;
|
|
380
|
+
}
|
|
381
|
+
catch { /* unborn */ }
|
|
382
|
+
const listed = git(root, ['rev-list', `--max-count=${exports.SEAM_MAX_COMMITS + 1}`, '--ignore-missing', '--stdin', ...(head ? ['HEAD'] : []), '--branches', '--tags'], `--not\n${s.tips.join('\n')}\n`).split('\n').filter(Boolean);
|
|
383
|
+
if (listed.length > exports.SEAM_MAX_COMMITS)
|
|
384
|
+
return [...out, { where: 'scan', detail: `more than ${exports.SEAM_MAX_COMMITS} commits are new since the spec seam was recorded` }];
|
|
385
|
+
for (const c of listed) {
|
|
386
|
+
const parents = git(root, ['rev-list', '--parents', '-n', '1', c]).trim().split(' ').slice(1);
|
|
387
|
+
const specs = [storeSpec(rel), ...(fl ? [storeSpec(fl.rel)] : [])];
|
|
388
|
+
const diff = parents.length === 0
|
|
389
|
+
? git(root, ['diff-tree', '--root', '-r', '--no-commit-id', '--no-renames', '--raw', '-z', '--no-abbrev', c, '--', ...specs])
|
|
390
|
+
: git(root, ['diff-tree', '-r', '--no-commit-id', '--no-renames', '--raw', '-z', '--no-abbrev', parents[0], c, '--', ...specs]);
|
|
391
|
+
for (const e of rawEntries(diff)) {
|
|
392
|
+
if (ledgerSide(e.path) && !fl.is(e.path))
|
|
393
|
+
continue; // this writer's own chain, or another ledger record
|
|
394
|
+
if (granted(s, e))
|
|
395
|
+
continue;
|
|
396
|
+
// a merge carries its parents' content: a blob one of them holds at that path is not new here
|
|
397
|
+
const fromParent = parents.slice(1).some((p) => {
|
|
398
|
+
const at = git(root, ['ls-tree', '-z', p, '--', e.path]).split('\0').filter(Boolean)[0];
|
|
399
|
+
const blob = at ? at.split(/\s+/)[2] : null;
|
|
400
|
+
return blob === e.blob;
|
|
401
|
+
});
|
|
402
|
+
if (!fromParent)
|
|
403
|
+
out.push({ where: 'commit', commit: c, path: e.path });
|
|
404
|
+
}
|
|
405
|
+
}
|
|
406
|
+
return out;
|
|
407
|
+
}
|
|
408
|
+
catch (e) {
|
|
409
|
+
if (noRepository(e))
|
|
410
|
+
return [];
|
|
411
|
+
return [{ where: 'scan', detail: `git could not list the spec store's changes (${String(e.message ?? e).split('\n')[0].slice(0, 120)})` }];
|
|
412
|
+
}
|
|
413
|
+
}
|
|
414
|
+
/** Records a baseline of the tips now and the granted pairs still staged, when either differs from the last one. */
|
|
415
|
+
function advanceSpecSeam(root, specsDir) {
|
|
416
|
+
const s = readState(root);
|
|
417
|
+
const tips = tipsNow(root);
|
|
418
|
+
const staged = stagedEntries(root, storeRel(root, specsDir));
|
|
419
|
+
const isStaged = (g) => staged.some((e) => e.path === g.path && e.blob === g.blob);
|
|
420
|
+
const keep = s === null ? [] : s.granted.filter(isStaged);
|
|
421
|
+
// @implements A-SPEC-792.15 — a grant no longer staged was committed (or dropped): its content stays accepted
|
|
422
|
+
const accepted = [];
|
|
423
|
+
for (const g of [...(s?.accepted ?? []), ...(s?.granted ?? []).filter((x) => !isStaged(x))]) {
|
|
424
|
+
if (!accepted.some((a) => a.path === g.path && a.blob === g.blob))
|
|
425
|
+
accepted.push(g);
|
|
426
|
+
}
|
|
427
|
+
const acceptedKept = accepted.slice(-ACCEPTED_KEPT);
|
|
428
|
+
const { historyFiles } = require('../review/verdicts');
|
|
429
|
+
const same = s !== null && JSON.stringify([...s.tips].sort()) === JSON.stringify([...tips].sort())
|
|
430
|
+
&& JSON.stringify(s.granted) === JSON.stringify(keep) && JSON.stringify(s.accepted) === JSON.stringify(acceptedKept)
|
|
431
|
+
&& JSON.stringify(s.history) === JSON.stringify(historyFiles(root));
|
|
432
|
+
if (!same)
|
|
433
|
+
writeBaseline(root, tips, keep, acceptedKept);
|
|
434
|
+
}
|
|
435
|
+
/**
|
|
436
|
+
* @implements A-SPEC-792.32 — the one calculator of what a staging approval approved: git's object id of these bytes
|
|
437
|
+
* (`sha1("blob <len>\0" + bytes)`), computed in process, so no clean filter or attribute of the work tree runs.
|
|
438
|
+
*/
|
|
439
|
+
function blobOf(bytes, format = 'sha1') {
|
|
440
|
+
return crypto.createHash(format).update(Buffer.concat([Buffer.from(`blob ${bytes.length}\0`), bytes])).digest('hex');
|
|
441
|
+
}
|
|
442
|
+
/** The repository's object format (a SHA-256 repository names its blobs by SHA-256). */
|
|
443
|
+
function objectFormatOf(root) {
|
|
444
|
+
try {
|
|
445
|
+
return git(root, ['rev-parse', '--show-object-format']).trim() === 'sha256' ? 'sha256' : 'sha1';
|
|
446
|
+
}
|
|
447
|
+
catch {
|
|
448
|
+
return 'sha1';
|
|
449
|
+
}
|
|
450
|
+
}
|
|
451
|
+
/** @implements A-SPEC-792.32 — the bytes a grant may name: a regular file without an execute bit (git mode 100644). */
|
|
452
|
+
function grantableBytes(abs) {
|
|
453
|
+
try {
|
|
454
|
+
const st = fs.lstatSync(abs);
|
|
455
|
+
return st.isFile() && (st.mode & 0o111) === 0 ? fs.readFileSync(abs) : null;
|
|
456
|
+
}
|
|
457
|
+
catch {
|
|
458
|
+
return null;
|
|
459
|
+
}
|
|
460
|
+
}
|
|
461
|
+
/**
|
|
462
|
+
* @implements A-SPEC-792.32 — what `git add` of these root-relative prefixes (every path when null) would change,
|
|
463
|
+
* without `git status`: a racily clean entry makes status re-hash the file through its clean filter, which ran the
|
|
464
|
+
* agent's filter command inside the hook (measured 2026-10-26). The index is read as recorded and each tracked file is
|
|
465
|
+
* compared by `blobOf` of its bytes and its mode; an untracked file is listed by `ls-files -o`. A filter, autocrlf or a
|
|
466
|
+
* mode the comparison does not follow reads as a change, which fails closed.
|
|
467
|
+
*/
|
|
468
|
+
function worktreeChanges(root, prefixes) {
|
|
469
|
+
const norm = (p) => p.split(path.sep).join('/').replace(/^\.\/+/, '').replace(/\/+$/, '');
|
|
470
|
+
const pre = prefixes === null ? null : prefixes.map(norm);
|
|
471
|
+
const within = (p) => pre === null || pre.some((x) => x === '' || x === '.' || p === x || p.startsWith(`${x}/`));
|
|
472
|
+
const out = [];
|
|
473
|
+
const fmt = objectFormatOf(root);
|
|
474
|
+
const index = git(root, ['ls-files', '-s', '-z']).split('\0').filter(Boolean);
|
|
475
|
+
for (const line of index) {
|
|
476
|
+
const tab = line.indexOf('\t');
|
|
477
|
+
const [mode, blob] = line.slice(0, tab).split(' ');
|
|
478
|
+
const rel = line.slice(tab + 1);
|
|
479
|
+
if (!within(rel))
|
|
480
|
+
continue;
|
|
481
|
+
const abs = path.join(root, rel);
|
|
482
|
+
let st;
|
|
483
|
+
try {
|
|
484
|
+
st = fs.lstatSync(abs);
|
|
485
|
+
}
|
|
486
|
+
catch {
|
|
487
|
+
out.push({ path: rel, deleted: true, untracked: false });
|
|
488
|
+
continue;
|
|
489
|
+
}
|
|
490
|
+
if (!st.isFile()) {
|
|
491
|
+
if (mode !== '120000' || !st.isSymbolicLink())
|
|
492
|
+
out.push({ path: rel, deleted: false, untracked: false });
|
|
493
|
+
else if (blobOf(Buffer.from(fs.readlinkSync(abs)), fmt) !== blob)
|
|
494
|
+
out.push({ path: rel, deleted: false, untracked: false });
|
|
495
|
+
continue;
|
|
496
|
+
}
|
|
497
|
+
const now = (st.mode & 0o111) !== 0 ? '100755' : '100644';
|
|
498
|
+
if (now !== mode || blobOf(fs.readFileSync(abs), fmt) !== blob)
|
|
499
|
+
out.push({ path: rel, deleted: false, untracked: false });
|
|
500
|
+
}
|
|
501
|
+
for (const rel of git(root, ['ls-files', '-o', '-z', '--exclude-standard']).split('\0').filter(Boolean)) {
|
|
502
|
+
if (within(rel))
|
|
503
|
+
out.push({ path: rel, deleted: false, untracked: true });
|
|
504
|
+
}
|
|
505
|
+
return out;
|
|
506
|
+
}
|
|
507
|
+
/**
|
|
508
|
+
* @implements A-SPEC-792.32 — the pathspecs of a command's `git add` / `git stage` segments only: a `git status`
|
|
509
|
+
* segment's words never widen what was granted (N3).
|
|
510
|
+
*/
|
|
511
|
+
function addPathspecs(command) {
|
|
512
|
+
const out = [];
|
|
513
|
+
for (const seg of command.split(/&&|\|\||[;|\n]/)) {
|
|
514
|
+
const w = seg.trim().split(/\s+/).map((x) => x.replace(/^['"]|['"]$/g, '')).filter(Boolean);
|
|
515
|
+
if (w[0] !== 'git')
|
|
516
|
+
continue;
|
|
517
|
+
let i = 1;
|
|
518
|
+
while (i < w.length && w[i].startsWith('-'))
|
|
519
|
+
i++;
|
|
520
|
+
if (w[i] !== 'add' && w[i] !== 'stage')
|
|
521
|
+
continue;
|
|
522
|
+
for (const x of w.slice(i + 1))
|
|
523
|
+
if (!x.startsWith('-'))
|
|
524
|
+
out.push(x);
|
|
525
|
+
}
|
|
526
|
+
return out;
|
|
527
|
+
}
|
|
528
|
+
/** @implements A-SPEC-792.32 — writes exactly these (path, blob) pairs of the spec store as a grant, nothing else. */
|
|
529
|
+
function recordProvenGrant(root, specsDir, proven) {
|
|
530
|
+
const rel = storeRel(root, specsDir);
|
|
531
|
+
const mine = proven.filter((p) => p.path === rel || p.path.startsWith(`${rel}/`));
|
|
532
|
+
if (readState(root) === null)
|
|
533
|
+
writeBaseline(root, tipsNow(root), []);
|
|
534
|
+
if (mine.length > 0)
|
|
535
|
+
appendEvent(root, GRANT, `spec staging granted: ${mine.length} file(s)`, mine.map((g) => grantInput(g)));
|
|
536
|
+
}
|
|
537
|
+
/**
|
|
538
|
+
* A granted spec-staging act (the person path): the path and blob of each changed spec file the command's `git add` or
|
|
539
|
+
* `git stage` segments name. @implements A-SPEC-792.32 — a command that names no spec path grants none (the
|
|
540
|
+
* every-changed-spec fallback is gone), and the blob is `blobOf` over a regular non-executable file, never a hash
|
|
541
|
+
* through git.
|
|
542
|
+
*/
|
|
543
|
+
function recordGrantedStaging(root, specsDir, command, cwd) {
|
|
544
|
+
const rel = storeRel(root, specsDir);
|
|
545
|
+
const store = path.join(root, rel);
|
|
546
|
+
const inside = (t, r) => t === r || t.startsWith(r + path.sep);
|
|
547
|
+
// @implements A-SPEC-222.12 (N1) — a person's staging of another replica's ledger file is granted too: the files its
|
|
548
|
+
// add segments reach, or every such change when it names none (`git add -A`, `git commit -a`)
|
|
549
|
+
const fl = foreignLedger(root);
|
|
550
|
+
if (fl) {
|
|
551
|
+
const named = addPathspecs(command).map((w) => path.resolve(cwd, w));
|
|
552
|
+
const reached = worktreeChanges(root, [fl.rel]).filter((c) => fl.is(c.path)
|
|
553
|
+
&& (named.length === 0 || named.some((sp) => inside(path.join(root, c.path), sp) || inside(sp, path.join(root, c.path)))));
|
|
554
|
+
const fmt = objectFormatOf(root);
|
|
555
|
+
const grants = [];
|
|
556
|
+
for (const c of reached) {
|
|
557
|
+
if (c.deleted) {
|
|
558
|
+
grants.push({ path: c.path, blob: null });
|
|
559
|
+
continue;
|
|
560
|
+
}
|
|
561
|
+
const bytes = grantableBytes(path.join(root, c.path));
|
|
562
|
+
if (bytes !== null)
|
|
563
|
+
grants.push({ path: c.path, blob: blobOf(bytes, fmt) });
|
|
564
|
+
}
|
|
565
|
+
if (grants.length > 0) {
|
|
566
|
+
if (readState(root) === null)
|
|
567
|
+
writeBaseline(root, tipsNow(root), []);
|
|
568
|
+
appendEvent(root, GRANT, `another replica's ledger staging granted: ${grants.length} file(s)`, grants.map((g) => grantInput(g)));
|
|
569
|
+
}
|
|
570
|
+
}
|
|
571
|
+
const specs = addPathspecs(command).map((w) => path.resolve(cwd, w)).filter((abs) => inside(abs, store) || inside(store, abs));
|
|
572
|
+
if (specs.length === 0)
|
|
573
|
+
return;
|
|
574
|
+
const changed = worktreeChanges(root, [rel]).filter((c) => specs.some((sp) => inside(path.join(root, c.path), sp) || inside(sp, path.join(root, c.path))));
|
|
575
|
+
const add = [];
|
|
576
|
+
const fmt = objectFormatOf(root);
|
|
577
|
+
for (const c of changed) {
|
|
578
|
+
if (c.deleted) {
|
|
579
|
+
add.push({ path: c.path, blob: null });
|
|
580
|
+
continue;
|
|
581
|
+
}
|
|
582
|
+
const bytes = grantableBytes(path.join(root, c.path));
|
|
583
|
+
if (bytes !== null)
|
|
584
|
+
add.push({ path: c.path, blob: blobOf(bytes, fmt) });
|
|
585
|
+
}
|
|
586
|
+
recordProvenGrant(root, specsDir, add);
|
|
587
|
+
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The ledger kinds a nonce is spent and revoked under, by namespace. Every reader and writer of these rows names the
|
|
3
|
+
* kind through this table, so a new namespace (the queue redesign planned for 0.41 may add one) is a row here, not a branch in each
|
|
4
|
+
* reader. In 0.40.0 the one namespace is `grant`, whose kinds are the ones the ledger has always held.
|
|
5
|
+
*/
|
|
6
|
+
export declare const SPEND_NAMESPACES: {
|
|
7
|
+
readonly grant: {
|
|
8
|
+
readonly consumed: "nonce-consumed";
|
|
9
|
+
readonly revoked: "nonce-revoked";
|
|
10
|
+
};
|
|
11
|
+
};
|
|
12
|
+
export type SpendNamespace = keyof typeof SPEND_NAMESPACES;
|
|
13
|
+
/** The ledger kind of a spend in `ns`. */
|
|
14
|
+
export declare function spendKind(ns?: SpendNamespace): string;
|
|
15
|
+
/** The ledger kind of a revocation in `ns`. */
|
|
16
|
+
export declare function revokeKind(ns?: SpendNamespace): string;
|