@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,96 @@
|
|
|
1
|
+
import { FileLedgerStore } from './ledger-store';
|
|
2
|
+
import { type ProvenanceEvent } from './provenance-chain';
|
|
3
|
+
import { type RecordedPair } from '../spec/succession';
|
|
4
|
+
type StoreEvent = ReturnType<FileLedgerStore['loadAll']>[number];
|
|
5
|
+
export interface IgnoredEvent {
|
|
6
|
+
file: string;
|
|
7
|
+
seq?: number;
|
|
8
|
+
kind?: string;
|
|
9
|
+
why: string;
|
|
10
|
+
}
|
|
11
|
+
export interface TrustDeps {
|
|
12
|
+
/** Every chain's replica id (null for the legacy chain). */
|
|
13
|
+
chains(): Array<string | null>;
|
|
14
|
+
ownReplica(): string | null;
|
|
15
|
+
/** The events of ledger files as they stand in HEAD (`rels` from the root, '/'-separated); null when one is not there. */
|
|
16
|
+
heads(rels: string[]): Map<string, ProvenanceEvent[] | null>;
|
|
17
|
+
/** The replica ids whose chain does not verify in the worktree. */
|
|
18
|
+
broken(): Set<string | null>;
|
|
19
|
+
/** Every event in the worktree. */
|
|
20
|
+
events(): StoreEvent[];
|
|
21
|
+
/** The ledger key, when one is set: verification of a HEAD blob checks keyed hashes as the store does. */
|
|
22
|
+
key?(): string | undefined;
|
|
23
|
+
}
|
|
24
|
+
/** Every literal actor production code appends as a tool (the reader census holds the list to the code). */
|
|
25
|
+
export declare const TOOL_ACTORS: readonly ["holmes-kit", "holmes-kit init", "holmes-spec-seam", "spec_renumber", "spec_reconcile"];
|
|
26
|
+
/** @implements A-SPEC-222.14 — the ref HEAD names (`refs/heads/feat`), `detached` for a commit, null with no `.git` here. */
|
|
27
|
+
export declare function headRefOf(root: string): string | null;
|
|
28
|
+
export declare function headCommitOf(root: string): string | null;
|
|
29
|
+
/** @implements A-SPEC-222.13 — HEAD could not be read: never "absent", so every reader fails closed on it. */
|
|
30
|
+
export declare class CommittedReadError extends Error {
|
|
31
|
+
constructor(m: string);
|
|
32
|
+
}
|
|
33
|
+
export declare function committedLedgerTexts(root: string, rels: string[]): Map<string, string | null>;
|
|
34
|
+
/** Whether a row's actor and authorization are a tool's or a well-formed person's (M-1). */
|
|
35
|
+
export declare function trustedActor(e: {
|
|
36
|
+
actor?: unknown;
|
|
37
|
+
authorization?: unknown;
|
|
38
|
+
}): boolean;
|
|
39
|
+
/** Every trusted event across the ledger's chains, and every event or chain that was ignored with its reason. */
|
|
40
|
+
export declare function trustedLedgerEvents(root: string, deps?: TrustDeps): {
|
|
41
|
+
events: StoreEvent[];
|
|
42
|
+
ignored: IgnoredEvent[];
|
|
43
|
+
};
|
|
44
|
+
export declare function ownLedgerShortened(root: string, ledgerDir?: string): boolean;
|
|
45
|
+
/** A-SPEC-222.10 (H-B) — the seals a trusted `spec-approved` event recorded, as `[id, digest]`. */
|
|
46
|
+
export declare function approvedSeals(events: ReadonlyArray<{
|
|
47
|
+
kind?: string;
|
|
48
|
+
inputs?: unknown;
|
|
49
|
+
}>): (id: string, digest: string) => boolean;
|
|
50
|
+
/**
|
|
51
|
+
* The successor pairs and seals the trusted events record, and the ignored rows or chains that could have recorded
|
|
52
|
+
* one: a chain ignored whole could hold any record, so it is named; an ignored row is named when it is of a succession
|
|
53
|
+
* kind or a seal.
|
|
54
|
+
*/
|
|
55
|
+
export declare function recordedPairsPort(root: string, deps?: TrustDeps): {
|
|
56
|
+
recorded: RecordedPair;
|
|
57
|
+
approved: (id: string, digest: string) => boolean;
|
|
58
|
+
ignored: IgnoredEvent[];
|
|
59
|
+
};
|
|
60
|
+
/**
|
|
61
|
+
* A-SPEC-222.10 (H-C) — a ledger store whose reads are the trusted events only; appends and every other operation are
|
|
62
|
+
* the file store's. Readers that need trust construct this instead of FileLedgerStore (the reader census holds it).
|
|
63
|
+
*/
|
|
64
|
+
export declare class TrustedLedgerStore extends FileLedgerStore {
|
|
65
|
+
private readonly ledgerDir;
|
|
66
|
+
private readonly id;
|
|
67
|
+
private memo;
|
|
68
|
+
constructor(dir: string, givenId?: string);
|
|
69
|
+
/**
|
|
70
|
+
* @implements A-SPEC-222.12 (low a, b) — the trusted read, memoised per instance until a chain file's size or mtime or
|
|
71
|
+
* HEAD changes (untrusted() and repeated audits reuse it); the store it reads carries this instance's replica id.
|
|
72
|
+
*/
|
|
73
|
+
private read;
|
|
74
|
+
loadAll(): StoreEvent[];
|
|
75
|
+
/**
|
|
76
|
+
* @implements A-SPEC-222.12 (H1) — whether this writer's own chain was ignored as not verifying: a reader that would
|
|
77
|
+
* otherwise take "no trusted events" for "nothing recorded yet" fails closed on it.
|
|
78
|
+
*/
|
|
79
|
+
ownChainBroken(): boolean;
|
|
80
|
+
/**
|
|
81
|
+
* Every row, trusted or not, for a check that only refuses: a conflicting row, even an untrusted one, stops an act
|
|
82
|
+
* (fail-closed), while what an act takes as granted or already done comes from `loadAll()` only.
|
|
83
|
+
*/
|
|
84
|
+
loadAllRaw(): StoreEvent[];
|
|
85
|
+
/** The rows among `rows` (read with loadAllRaw) that are not trusted: for an audit, each one is a conflict. */
|
|
86
|
+
untrusted(rows: StoreEvent[]): StoreEvent[];
|
|
87
|
+
/**
|
|
88
|
+
* @implements A-SPEC-222.12 (L1) — an audit refusal that names the replica files holding the untrusted rows and the
|
|
89
|
+
* way out, so one row is not a refusal with no recovery: commit that replica's file (a person stages another replica),
|
|
90
|
+
* or, for an old replica of this machine whose hostname changed, commit or remove it.
|
|
91
|
+
*/
|
|
92
|
+
untrustedReason(rows: StoreEvent[]): string;
|
|
93
|
+
}
|
|
94
|
+
/** One line naming ignored ledger entries, for a refusal or an unproven reason (at most three named). */
|
|
95
|
+
export declare function describeIgnored(ignored: IgnoredEvent[]): string;
|
|
96
|
+
export {};
|
|
@@ -0,0 +1,522 @@
|
|
|
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.TrustedLedgerStore = exports.CommittedReadError = exports.TOOL_ACTORS = void 0;
|
|
37
|
+
exports.headRefOf = headRefOf;
|
|
38
|
+
exports.headCommitOf = headCommitOf;
|
|
39
|
+
exports.committedLedgerTexts = committedLedgerTexts;
|
|
40
|
+
exports.trustedActor = trustedActor;
|
|
41
|
+
exports.trustedLedgerEvents = trustedLedgerEvents;
|
|
42
|
+
exports.ownLedgerShortened = ownLedgerShortened;
|
|
43
|
+
exports.approvedSeals = approvedSeals;
|
|
44
|
+
exports.recordedPairsPort = recordedPairsPort;
|
|
45
|
+
exports.describeIgnored = describeIgnored;
|
|
46
|
+
// @implements A-SPEC-222.9, A-SPEC-222.10, A-SPEC-222.12, A-SPEC-222.13
|
|
47
|
+
/**
|
|
48
|
+
* The ledger events a successor, a seal or a provenance proof may be taken from (H1 of the 2026-10-25 review, SD1
|
|
49
|
+
* finding 2; A-SPEC-222.10 H-A, H-C, M-1): one port for every reader that needs trust, so none opens the ledger itself.
|
|
50
|
+
* It reads through the ledger store (A-SPEC-150), never past it. An event counts only when all three hold:
|
|
51
|
+
* - it is in this writer's own replica file, or it stands in the `HEAD:` blob of another replica's file (the worktree
|
|
52
|
+
* and the index of another replica are never read: a staged file, or a row appended after the commit, is not HEAD);
|
|
53
|
+
* - its chain verifies (this writer's file in the worktree, another's as committed); a chain that does not is ignored
|
|
54
|
+
* whole;
|
|
55
|
+
* - its actor is a tool, or its authorization is exactly `<its actor>:<12 hex>` as authorizationRef writes it; an
|
|
56
|
+
* `unattested:` actor or authorization never counts.
|
|
57
|
+
* Everything else is ignored and named, so the refusal that follows can say why. Residual risk, stated in the spec:
|
|
58
|
+
* without an out-of-band secret, code running as the same user can append a well-formed row to this writer's own file,
|
|
59
|
+
* and a commit (an act an agent can take) puts a forged replica into HEAD.
|
|
60
|
+
*/
|
|
61
|
+
const fs = __importStar(require("node:fs"));
|
|
62
|
+
const path = __importStar(require("node:path"));
|
|
63
|
+
const ledger_store_1 = require("./ledger-store");
|
|
64
|
+
const provenance_chain_1 = require("./provenance-chain");
|
|
65
|
+
const bounded_io_1 = require("../project/bounded-io");
|
|
66
|
+
const succession_1 = require("../spec/succession");
|
|
67
|
+
/** Every literal actor production code appends as a tool (the reader census holds the list to the code). */
|
|
68
|
+
exports.TOOL_ACTORS = ['holmes-kit', 'holmes-kit init', 'holmes-spec-seam', 'spec_renumber', 'spec_reconcile'];
|
|
69
|
+
const TOOL_ACTOR = new RegExp(`^(?:${exports.TOOL_ACTORS.map((a) => a.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')}|full-autonomy:.+)$`);
|
|
70
|
+
const SUCCESSION_KINDS = new Set(['spec-retired', 'spec-superseded']);
|
|
71
|
+
const fileName = (replicaId) => (replicaId === null ? 'provenance.jsonl' : `provenance.${replicaId}.jsonl`);
|
|
72
|
+
/** The project root a ledger directory belongs to: `<root>/.ax/ledger` gives `<root>`, any other directory itself. */
|
|
73
|
+
function rootOfLedger(dir) {
|
|
74
|
+
const abs = path.resolve(dir);
|
|
75
|
+
return path.basename(abs) === 'ledger' && path.basename(path.dirname(abs)) === '.ax' ? path.resolve(abs, '..', '..') : abs;
|
|
76
|
+
}
|
|
77
|
+
const OID = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/;
|
|
78
|
+
/**
|
|
79
|
+
* @implements A-SPEC-222.12 (M1) — the commit HEAD names, read from the git directory's own files with no child: a
|
|
80
|
+
* `.git` directory or a linked worktree's `.git` file (`gitdir:`), the worktree's `commondir`, and a loose ref or
|
|
81
|
+
* `packed-refs`. Only at a root that holds `.git` (the paths are then the repository's own); null otherwise.
|
|
82
|
+
*/
|
|
83
|
+
/** @implements A-SPEC-222.14 — the worktree's git directory, its common directory and the HEAD line, read once. */
|
|
84
|
+
function gitDirsOf(root) {
|
|
85
|
+
try {
|
|
86
|
+
const dotGit = path.join(root, '.git');
|
|
87
|
+
const st = fs.lstatSync(dotGit);
|
|
88
|
+
let gitDir;
|
|
89
|
+
if (st.isDirectory())
|
|
90
|
+
gitDir = dotGit;
|
|
91
|
+
else if (st.isFile()) {
|
|
92
|
+
const m = /^gitdir: (.+)$/m.exec(fs.readFileSync(dotGit, 'utf8'));
|
|
93
|
+
if (!m)
|
|
94
|
+
return null;
|
|
95
|
+
gitDir = path.resolve(root, m[1].trim());
|
|
96
|
+
}
|
|
97
|
+
else
|
|
98
|
+
return null;
|
|
99
|
+
let common = gitDir;
|
|
100
|
+
try {
|
|
101
|
+
common = path.resolve(gitDir, fs.readFileSync(path.join(gitDir, 'commondir'), 'utf8').trim());
|
|
102
|
+
}
|
|
103
|
+
catch { /* not a linked worktree */ }
|
|
104
|
+
return { gitDir, common, head: fs.readFileSync(path.join(gitDir, 'HEAD'), 'utf8').trim() };
|
|
105
|
+
}
|
|
106
|
+
catch {
|
|
107
|
+
return null;
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
/** @implements A-SPEC-222.14 — the ref HEAD names (`refs/heads/feat`), `detached` for a commit, null with no `.git` here. */
|
|
111
|
+
function headRefOf(root) {
|
|
112
|
+
const dirs = gitDirsOf(root);
|
|
113
|
+
if (dirs === null)
|
|
114
|
+
return null;
|
|
115
|
+
const m = /^ref: (refs\/[^\s]+)$/.exec(dirs.head);
|
|
116
|
+
return m ? m[1] : 'detached';
|
|
117
|
+
}
|
|
118
|
+
function headCommitOf(root) {
|
|
119
|
+
try {
|
|
120
|
+
const dirs = gitDirsOf(root);
|
|
121
|
+
if (dirs === null)
|
|
122
|
+
return null;
|
|
123
|
+
const { gitDir, common, head } = dirs;
|
|
124
|
+
if (OID.test(head))
|
|
125
|
+
return head;
|
|
126
|
+
const m = /^ref: (refs\/[^\s]+)$/.exec(head);
|
|
127
|
+
if (!m || m[1].split('/').some((s) => s === '..' || s === ''))
|
|
128
|
+
return null;
|
|
129
|
+
for (const dir of [gitDir, common]) {
|
|
130
|
+
try {
|
|
131
|
+
const id = fs.readFileSync(path.join(dir, ...m[1].split('/')), 'utf8').trim();
|
|
132
|
+
if (OID.test(id))
|
|
133
|
+
return id;
|
|
134
|
+
}
|
|
135
|
+
catch { /* not loose here */ }
|
|
136
|
+
}
|
|
137
|
+
const packed = fs.readFileSync(path.join(common, 'packed-refs'), 'utf8');
|
|
138
|
+
for (const line of packed.split('\n')) {
|
|
139
|
+
const [id, ref] = line.trim().split(' ');
|
|
140
|
+
if (ref === m[1] && OID.test(id ?? ''))
|
|
141
|
+
return id;
|
|
142
|
+
}
|
|
143
|
+
return null;
|
|
144
|
+
}
|
|
145
|
+
catch {
|
|
146
|
+
return null;
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
/**
|
|
150
|
+
* @implements A-SPEC-222.12 (M1) — the text of ledger files as they stand in HEAD (`rels` from the root), read with one
|
|
151
|
+
* `git cat-file --batch` for all of them and memoised per process by the commit; null for a file HEAD does not hold. The
|
|
152
|
+
* Stop hook's rollback check and the trusted-events port share it (one git child per new commit, not one per replica).
|
|
153
|
+
* A root that holds no `.git`, or a HEAD its files do not name, is read per file and not memoised.
|
|
154
|
+
*/
|
|
155
|
+
const headMemo = new Map();
|
|
156
|
+
/** @implements A-SPEC-222.13 — HEAD could not be read: never "absent", so every reader fails closed on it. */
|
|
157
|
+
class CommittedReadError extends Error {
|
|
158
|
+
constructor(m) { super(m); this.name = 'CommittedReadError'; }
|
|
159
|
+
}
|
|
160
|
+
exports.CommittedReadError = CommittedReadError;
|
|
161
|
+
function committedLedgerTexts(root, rels) {
|
|
162
|
+
const commit = headCommitOf(root);
|
|
163
|
+
const out = new Map();
|
|
164
|
+
// @implements A-SPEC-222.13 (low d) — git names the paths NFC under core.precomposeunicode
|
|
165
|
+
const asked = (rel) => rel.normalize('NFC');
|
|
166
|
+
if (commit === null) {
|
|
167
|
+
for (const rel of rels) {
|
|
168
|
+
const r = (0, bounded_io_1.gitOnceBuffer)(root, ['-c', 'core.fsmonitor=false', 'cat-file', '-p', `HEAD:./${asked(rel)}`], 'repo', { pinned: (0, bounded_io_1.judgmentPins)() });
|
|
169
|
+
if (r.error !== undefined || r.status === null)
|
|
170
|
+
throw new CommittedReadError(`git could not read HEAD:${rel}`);
|
|
171
|
+
// a path HEAD does not hold (or no HEAD) answers 128 with nothing on stdout: absent, not unread
|
|
172
|
+
out.set(rel, r.status === 0 ? r.stdout.toString('utf8') : null);
|
|
173
|
+
}
|
|
174
|
+
return out;
|
|
175
|
+
}
|
|
176
|
+
const key = `${root}\u0000${commit}`;
|
|
177
|
+
const memo = headMemo.get(key) ?? new Map();
|
|
178
|
+
// one batch per commit: a miss also fetches every chain file the ledger directory holds, since the port, the seam and
|
|
179
|
+
// the Stop rollback check each ask for a different subset (A-SPEC-222.13 low a)
|
|
180
|
+
let missing = rels.filter((r) => !memo.has(r));
|
|
181
|
+
if (missing.length > 0) {
|
|
182
|
+
try {
|
|
183
|
+
const ledgerDir = path.join(root, '.ax', 'ledger');
|
|
184
|
+
const all = fs.readdirSync(ledgerDir).filter((n) => /^provenance(?:\.[^/]+)?\.jsonl$/.test(n)).map((n) => `.ax/ledger/${n}`);
|
|
185
|
+
// this writer's own file too, though the worktree no longer holds it: a deleted ledger is what the seam asks about
|
|
186
|
+
try {
|
|
187
|
+
all.push(`.ax/ledger/${fileName(new ledger_store_1.FileLedgerStore(ledgerDir).replicaId())}`);
|
|
188
|
+
}
|
|
189
|
+
catch { /* no replica id */ }
|
|
190
|
+
missing = [...new Set([...missing, ...all.filter((r) => !memo.has(r))])];
|
|
191
|
+
}
|
|
192
|
+
catch { /* no ledger directory: only what was asked */ }
|
|
193
|
+
}
|
|
194
|
+
if (missing.length > 0) {
|
|
195
|
+
const r = (0, bounded_io_1.gitOnceBuffer)(root, ['-c', 'core.fsmonitor=false', 'cat-file', '--batch'], 'repo', { pinned: (0, bounded_io_1.judgmentPins)(), input: missing.map((m) => `${commit}:${asked(m)}`).join('\n') + '\n' });
|
|
196
|
+
if (r.status !== 0 || r.error !== undefined)
|
|
197
|
+
throw new CommittedReadError(`git cat-file could not read the ledger at ${commit.slice(0, 12)}`);
|
|
198
|
+
// @implements A-SPEC-222.13 — cut at byte offsets of the bytes git wrote; a header that does not parse is a read
|
|
199
|
+
// failure, and nothing of a failed read is memoised
|
|
200
|
+
const buf = r.stdout;
|
|
201
|
+
const read = new Map();
|
|
202
|
+
let at = 0;
|
|
203
|
+
for (const rel of missing) {
|
|
204
|
+
const nl = buf.indexOf(10, at);
|
|
205
|
+
if (nl < 0)
|
|
206
|
+
throw new CommittedReadError(`git cat-file answered short for ${rel}`);
|
|
207
|
+
const header = buf.subarray(at, nl).toString('utf8').split(' ');
|
|
208
|
+
at = nl + 1;
|
|
209
|
+
if (header.length === 2 && header[1] === 'missing') {
|
|
210
|
+
read.set(rel, null);
|
|
211
|
+
continue;
|
|
212
|
+
}
|
|
213
|
+
if (header.length !== 3 || header[1] !== 'blob' || !/^\d+$/.test(header[2]))
|
|
214
|
+
throw new CommittedReadError(`git cat-file answered an unexpected header for ${rel}`);
|
|
215
|
+
const size = Number(header[2]);
|
|
216
|
+
if (at + size > buf.length)
|
|
217
|
+
throw new CommittedReadError(`git cat-file answered short for ${rel}`);
|
|
218
|
+
read.set(rel, buf.subarray(at, at + size).toString('utf8'));
|
|
219
|
+
at += size + 1;
|
|
220
|
+
}
|
|
221
|
+
for (const [rel, text] of read)
|
|
222
|
+
memo.set(rel, text);
|
|
223
|
+
if (headMemo.size > 64)
|
|
224
|
+
headMemo.clear();
|
|
225
|
+
headMemo.set(key, memo);
|
|
226
|
+
}
|
|
227
|
+
for (const rel of rels)
|
|
228
|
+
out.set(rel, memo.get(rel) ?? null);
|
|
229
|
+
return out;
|
|
230
|
+
}
|
|
231
|
+
function realTrustDeps(root, ledgerDir = path.join(root, '.ax', 'ledger'), givenId) {
|
|
232
|
+
const store = new ledger_store_1.FileLedgerStore(ledgerDir, givenId);
|
|
233
|
+
return {
|
|
234
|
+
chains: () => store.chains().map((c) => c.replicaId),
|
|
235
|
+
ownReplica: () => { try {
|
|
236
|
+
return store.replicaId();
|
|
237
|
+
}
|
|
238
|
+
catch {
|
|
239
|
+
return null;
|
|
240
|
+
} },
|
|
241
|
+
heads: (rels) => {
|
|
242
|
+
const out = new Map();
|
|
243
|
+
for (const [rel, text] of committedLedgerTexts(root, rels)) {
|
|
244
|
+
let events = null;
|
|
245
|
+
if (text !== null) {
|
|
246
|
+
try {
|
|
247
|
+
events = (0, provenance_chain_1.parseLedgerLines)(text, rel, { throwOnCorruption: false });
|
|
248
|
+
}
|
|
249
|
+
catch {
|
|
250
|
+
events = null;
|
|
251
|
+
}
|
|
252
|
+
}
|
|
253
|
+
out.set(rel, events);
|
|
254
|
+
}
|
|
255
|
+
return out;
|
|
256
|
+
},
|
|
257
|
+
broken: () => new Set(store.verifyAll().broken.filter((b) => (b.kind ?? 'chain') === 'chain').map((b) => b.replicaId)),
|
|
258
|
+
events: () => store.loadAll(),
|
|
259
|
+
key: () => process.env.HOLMES_LEDGER_KEY || undefined,
|
|
260
|
+
};
|
|
261
|
+
}
|
|
262
|
+
/** Whether a row's actor and authorization are a tool's or a well-formed person's (M-1). */
|
|
263
|
+
function trustedActor(e) {
|
|
264
|
+
const actor = String(e.actor ?? '');
|
|
265
|
+
if (actor.startsWith('unattested:'))
|
|
266
|
+
return false;
|
|
267
|
+
if (TOOL_ACTOR.test(actor))
|
|
268
|
+
return true;
|
|
269
|
+
const a = typeof e.authorization === 'string' ? e.authorization : '';
|
|
270
|
+
return a.startsWith(`${actor}:`) && /^[0-9a-f]{12}$/.test(a.slice(actor.length + 1)) && !/(?:^|:)unattested:/.test(a);
|
|
271
|
+
}
|
|
272
|
+
/** Every trusted event across the ledger's chains, and every event or chain that was ignored with its reason. */
|
|
273
|
+
function trustedLedgerEvents(root, deps = realTrustDeps(root)) {
|
|
274
|
+
const ignored = [];
|
|
275
|
+
const events = [];
|
|
276
|
+
let chains;
|
|
277
|
+
try {
|
|
278
|
+
chains = deps.chains();
|
|
279
|
+
}
|
|
280
|
+
catch {
|
|
281
|
+
return { events, ignored: [{ file: '.ax/ledger', why: 'the ledger directory cannot be read' }] };
|
|
282
|
+
}
|
|
283
|
+
if (chains.length === 0)
|
|
284
|
+
return { events, ignored };
|
|
285
|
+
const own = deps.ownReplica();
|
|
286
|
+
const ledgerRel = path.relative(root, path.join(root, '.ax', 'ledger')).split(path.sep).join('/');
|
|
287
|
+
const keep = (e, file) => {
|
|
288
|
+
if (trustedActor(e))
|
|
289
|
+
return true;
|
|
290
|
+
ignored.push({ file, seq: e.seq, kind: e.kind, why: `its actor ${JSON.stringify(String(e.actor).slice(0, 40))} is neither a tool nor authorized` });
|
|
291
|
+
return false;
|
|
292
|
+
};
|
|
293
|
+
// A-SPEC-222.12 (M1): every other replica's HEAD blob in one read
|
|
294
|
+
const others = chains.filter((id) => !(id !== null && id === own)).map((id) => `${ledgerRel}/${fileName(id)}`);
|
|
295
|
+
let heads = new Map();
|
|
296
|
+
let headUnread = false;
|
|
297
|
+
if (others.length > 0) {
|
|
298
|
+
try {
|
|
299
|
+
heads = deps.heads(others);
|
|
300
|
+
}
|
|
301
|
+
catch {
|
|
302
|
+
headUnread = true;
|
|
303
|
+
}
|
|
304
|
+
}
|
|
305
|
+
for (const id of chains) {
|
|
306
|
+
const file = `${ledgerRel}/${fileName(id)}`;
|
|
307
|
+
if (id !== null && id === own) {
|
|
308
|
+
// this writer's own file, in the worktree
|
|
309
|
+
let broken;
|
|
310
|
+
try {
|
|
311
|
+
broken = deps.broken();
|
|
312
|
+
}
|
|
313
|
+
catch {
|
|
314
|
+
broken = new Set([id]);
|
|
315
|
+
}
|
|
316
|
+
if (broken.has(id)) {
|
|
317
|
+
ignored.push({ file, why: 'its chain does not verify' });
|
|
318
|
+
continue;
|
|
319
|
+
}
|
|
320
|
+
let all;
|
|
321
|
+
try {
|
|
322
|
+
all = deps.events();
|
|
323
|
+
}
|
|
324
|
+
catch {
|
|
325
|
+
ignored.push({ file, why: 'it cannot be read' });
|
|
326
|
+
continue;
|
|
327
|
+
}
|
|
328
|
+
for (const e of all)
|
|
329
|
+
if (e.replicaId === id && keep(e, file))
|
|
330
|
+
events.push(e);
|
|
331
|
+
continue;
|
|
332
|
+
}
|
|
333
|
+
// A-SPEC-222.10 (H-A a): another replica, as committed
|
|
334
|
+
// A-SPEC-222.13 — a HEAD that could not be read is not "absent": the replica is ignored with that reason
|
|
335
|
+
if (headUnread) {
|
|
336
|
+
ignored.push({ file, why: 'not this writer\'s replica, and HEAD could not be read' });
|
|
337
|
+
continue;
|
|
338
|
+
}
|
|
339
|
+
const committed = heads.get(file) ?? null;
|
|
340
|
+
if (committed === null) {
|
|
341
|
+
ignored.push({ file, why: 'not this writer\'s replica, and HEAD does not hold it' });
|
|
342
|
+
continue;
|
|
343
|
+
}
|
|
344
|
+
if (!(0, provenance_chain_1.verifyChain)(committed, deps.key?.()).ok) {
|
|
345
|
+
ignored.push({ file, why: 'its chain in HEAD does not verify' });
|
|
346
|
+
continue;
|
|
347
|
+
}
|
|
348
|
+
for (const e of committed)
|
|
349
|
+
if (keep(e, file))
|
|
350
|
+
events.push({ ...e, replicaId: id });
|
|
351
|
+
}
|
|
352
|
+
const order = (e) => `${e.ts} ${e.replicaId ?? ''} ${String(e.seq).padStart(12, '0')}`;
|
|
353
|
+
events.sort((a, b) => (order(a) < order(b) ? -1 : order(a) > order(b) ? 1 : 0));
|
|
354
|
+
return { events, ignored };
|
|
355
|
+
}
|
|
356
|
+
/**
|
|
357
|
+
* @implements A-SPEC-222.13 — whether this writer's ledger is no longer an extension of its file in HEAD (cut to a
|
|
358
|
+
* prefix, emptied or deleted): the judgement the Stop hook's rollback check makes, for the spec seam too. A file HEAD
|
|
359
|
+
* does not hold cannot be shortened against it.
|
|
360
|
+
* @implements A-SPEC-222.14 — a HEAD that cannot be read is not "shortened": its CommittedReadError reaches the caller,
|
|
361
|
+
* which says retry (restoring from git on that advice dropped uncommitted rows). The verdict is memoised by the commit
|
|
362
|
+
* and the own file's size and mtime (it parsed both texts again on every read).
|
|
363
|
+
*/
|
|
364
|
+
const shortenedMemo = new Map();
|
|
365
|
+
function ownLedgerShortened(root, ledgerDir = path.join(root, '.ax', 'ledger')) {
|
|
366
|
+
let own;
|
|
367
|
+
try {
|
|
368
|
+
own = new ledger_store_1.FileLedgerStore(ledgerDir).replicaId();
|
|
369
|
+
}
|
|
370
|
+
catch {
|
|
371
|
+
return true;
|
|
372
|
+
}
|
|
373
|
+
const file = path.join(ledgerDir, fileName(own));
|
|
374
|
+
const rel = path.relative(root, file).split(path.sep).join('/');
|
|
375
|
+
let stamp = 'absent';
|
|
376
|
+
try {
|
|
377
|
+
const st = fs.statSync(file);
|
|
378
|
+
stamp = `${st.size}:${st.mtimeMs}:${st.ino}`;
|
|
379
|
+
}
|
|
380
|
+
catch { /* deleted */ }
|
|
381
|
+
const commit = headCommitOf(root);
|
|
382
|
+
const key = commit === null ? null : `${root}\u0000${commit}\u0000${rel}\u0000${stamp}`;
|
|
383
|
+
if (key !== null && shortenedMemo.has(key))
|
|
384
|
+
return shortenedMemo.get(key);
|
|
385
|
+
const committed = committedLedgerTexts(root, [rel]).get(rel) ?? null; // CommittedReadError: the caller's retry
|
|
386
|
+
let verdict = false;
|
|
387
|
+
if (committed !== null) {
|
|
388
|
+
let working = '';
|
|
389
|
+
try {
|
|
390
|
+
working = fs.readFileSync(file, 'utf8');
|
|
391
|
+
}
|
|
392
|
+
catch {
|
|
393
|
+
working = '';
|
|
394
|
+
}
|
|
395
|
+
const { mainlineIsPrefix } = require('./ledger-rechain');
|
|
396
|
+
const parse = (t) => (0, provenance_chain_1.parseLedgerLines)(t, rel, { throwOnCorruption: false });
|
|
397
|
+
verdict = !mainlineIsPrefix(parse(committed), parse(working));
|
|
398
|
+
}
|
|
399
|
+
if (key !== null) {
|
|
400
|
+
if (shortenedMemo.size > 64)
|
|
401
|
+
shortenedMemo.clear();
|
|
402
|
+
shortenedMemo.set(key, verdict);
|
|
403
|
+
}
|
|
404
|
+
return verdict;
|
|
405
|
+
}
|
|
406
|
+
/** A-SPEC-222.10 (H-B) — the seals a trusted `spec-approved` event recorded, as `[id, digest]`. */
|
|
407
|
+
function approvedSeals(events) {
|
|
408
|
+
const seals = new Set();
|
|
409
|
+
for (const e of events) {
|
|
410
|
+
if (e.kind !== 'spec-approved' || !Array.isArray(e.inputs))
|
|
411
|
+
continue;
|
|
412
|
+
const [id, digest] = e.inputs.map(String);
|
|
413
|
+
if (id && digest)
|
|
414
|
+
seals.add(`${id}\u0000${digest}`);
|
|
415
|
+
}
|
|
416
|
+
return (id, digest) => seals.has(`${id}\u0000${digest}`);
|
|
417
|
+
}
|
|
418
|
+
/**
|
|
419
|
+
* The successor pairs and seals the trusted events record, and the ignored rows or chains that could have recorded
|
|
420
|
+
* one: a chain ignored whole could hold any record, so it is named; an ignored row is named when it is of a succession
|
|
421
|
+
* kind or a seal.
|
|
422
|
+
*/
|
|
423
|
+
function recordedPairsPort(root, deps) {
|
|
424
|
+
const { events, ignored } = trustedLedgerEvents(root, deps);
|
|
425
|
+
return { recorded: (0, succession_1.recordedPairs)(events), approved: approvedSeals(events),
|
|
426
|
+
ignored: ignored.filter((i) => i.kind === undefined || SUCCESSION_KINDS.has(i.kind) || i.kind === 'spec-approved') };
|
|
427
|
+
}
|
|
428
|
+
/**
|
|
429
|
+
* A-SPEC-222.10 (H-C) — a ledger store whose reads are the trusted events only; appends and every other operation are
|
|
430
|
+
* the file store's. Readers that need trust construct this instead of FileLedgerStore (the reader census holds it).
|
|
431
|
+
*/
|
|
432
|
+
class TrustedLedgerStore extends ledger_store_1.FileLedgerStore {
|
|
433
|
+
ledgerDir;
|
|
434
|
+
id;
|
|
435
|
+
memo = null;
|
|
436
|
+
constructor(dir, givenId) { super(dir, givenId); this.ledgerDir = dir; this.id = givenId; }
|
|
437
|
+
/**
|
|
438
|
+
* @implements A-SPEC-222.12 (low a, b) — the trusted read, memoised per instance until a chain file's size or mtime or
|
|
439
|
+
* HEAD changes (untrusted() and repeated audits reuse it); the store it reads carries this instance's replica id.
|
|
440
|
+
*/
|
|
441
|
+
read() {
|
|
442
|
+
const root = rootOfLedger(this.ledgerDir);
|
|
443
|
+
let key;
|
|
444
|
+
try {
|
|
445
|
+
key = [headCommitOf(root) ?? 'no-head', ...fs.readdirSync(this.ledgerDir).filter((n) => /^provenance(?:\.[^/]+)?\.jsonl$/.test(n)).sort()
|
|
446
|
+
.map((n) => { const st = fs.statSync(path.join(this.ledgerDir, n)); return `${n}:${st.size}:${st.mtimeMs}`; })].join('|');
|
|
447
|
+
}
|
|
448
|
+
catch {
|
|
449
|
+
key = `unkeyed:${Date.now()}:${Math.random()}`;
|
|
450
|
+
}
|
|
451
|
+
if (this.memo?.key !== key)
|
|
452
|
+
this.memo = { key, read: trustedLedgerEvents(root, realTrustDeps(root, this.ledgerDir, this.id)) };
|
|
453
|
+
return this.memo.read;
|
|
454
|
+
}
|
|
455
|
+
loadAll() { return this.read().events; }
|
|
456
|
+
/**
|
|
457
|
+
* @implements A-SPEC-222.12 (H1) — whether this writer's own chain was ignored as not verifying: a reader that would
|
|
458
|
+
* otherwise take "no trusted events" for "nothing recorded yet" fails closed on it.
|
|
459
|
+
*/
|
|
460
|
+
ownChainBroken() {
|
|
461
|
+
let own = null;
|
|
462
|
+
try {
|
|
463
|
+
own = this.replicaId();
|
|
464
|
+
}
|
|
465
|
+
catch {
|
|
466
|
+
own = null;
|
|
467
|
+
}
|
|
468
|
+
if (own === null)
|
|
469
|
+
return true;
|
|
470
|
+
return this.read().ignored.some((i) => i.seq === undefined && i.file.endsWith(`/provenance.${own}.jsonl`) && /does not verify|cannot be read/.test(i.why));
|
|
471
|
+
}
|
|
472
|
+
/**
|
|
473
|
+
* Every row, trusted or not, for a check that only refuses: a conflicting row, even an untrusted one, stops an act
|
|
474
|
+
* (fail-closed), while what an act takes as granted or already done comes from `loadAll()` only.
|
|
475
|
+
*/
|
|
476
|
+
loadAllRaw() { return super.loadAll(); }
|
|
477
|
+
/** The rows among `rows` (read with loadAllRaw) that are not trusted: for an audit, each one is a conflict. */
|
|
478
|
+
untrusted(rows) {
|
|
479
|
+
const key = (e) => `${e.replicaId ?? ''}\u0000${e.seq}\u0000${e.hash}`;
|
|
480
|
+
const trusted = new Set(this.loadAll().map(key));
|
|
481
|
+
return rows.filter((e) => !trusted.has(key(e)));
|
|
482
|
+
}
|
|
483
|
+
/**
|
|
484
|
+
* @implements A-SPEC-222.12 (L1) — an audit refusal that names the replica files holding the untrusted rows and the
|
|
485
|
+
* way out, so one row is not a refusal with no recovery: commit that replica's file (a person stages another replica),
|
|
486
|
+
* or, for an old replica of this machine whose hostname changed, commit or remove it.
|
|
487
|
+
*/
|
|
488
|
+
untrustedReason(rows) {
|
|
489
|
+
// @implements A-SPEC-222.13 — by reason, from what the trusted read ignored: never tell a writer to remove its own file
|
|
490
|
+
const bad = this.untrusted(rows);
|
|
491
|
+
if (bad.length === 0)
|
|
492
|
+
return '';
|
|
493
|
+
const ignored = this.read().ignored;
|
|
494
|
+
const parts = new Set();
|
|
495
|
+
for (const e of bad) {
|
|
496
|
+
const name = e.replicaId === null ? 'provenance.jsonl' : `provenance.${e.replicaId}.jsonl`;
|
|
497
|
+
const row = ignored.find((i) => i.seq === e.seq && i.file.endsWith(`/${name}`));
|
|
498
|
+
const chain = ignored.find((i) => i.seq === undefined && i.file.endsWith(`/${name}`));
|
|
499
|
+
if (row)
|
|
500
|
+
parts.add(`${name}#${e.seq}: its actor is neither a tool nor authorized, so the row cannot count — redo the act through the tool`);
|
|
501
|
+
else if (chain && /HEAD could not be read/.test(chain.why))
|
|
502
|
+
parts.add(`${name}: HEAD could not be read — retry when git answers`);
|
|
503
|
+
else if (chain && /in HEAD does not verify/.test(chain.why))
|
|
504
|
+
parts.add(`${name}: its chain in HEAD does not verify — that replica's owner repairs it with \`holmes-kit ledger rechain\``);
|
|
505
|
+
else if (chain && /does not verify|cannot be read/.test(chain.why))
|
|
506
|
+
parts.add(`${name}: this writer's chain does not verify — repair it from a terminal with \`holmes-kit ledger rechain\` (an uncommitted ledger is re-chained whole: review it first)`);
|
|
507
|
+
else if (chain)
|
|
508
|
+
parts.add(`${name}: another replica that HEAD does not hold as written — a person stages and commits it`);
|
|
509
|
+
else
|
|
510
|
+
parts.add(`${name}#${e.seq}: not trusted`);
|
|
511
|
+
}
|
|
512
|
+
return ` (A-SPEC-222.13: ${[...parts].join('; ')}; then retry.)`;
|
|
513
|
+
}
|
|
514
|
+
}
|
|
515
|
+
exports.TrustedLedgerStore = TrustedLedgerStore;
|
|
516
|
+
/** One line naming ignored ledger entries, for a refusal or an unproven reason (at most three named). */
|
|
517
|
+
function describeIgnored(ignored) {
|
|
518
|
+
if (ignored.length === 0)
|
|
519
|
+
return '';
|
|
520
|
+
const named = ignored.slice(0, 3).map((i) => `${i.file}${i.seq !== undefined ? `#${i.seq}` : ''}: ${i.why}`).join('; ');
|
|
521
|
+
return `${ignored.length} ledger entr${ignored.length === 1 ? 'y was' : 'ies were'} ignored (${named}${ignored.length > 3 ? '; …' : ''})`;
|
|
522
|
+
}
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
*
|
|
4
4
|
* DOTS ARE THE POINT. macOS hostnames end in `.local`, and the schema rule reads
|
|
5
5
|
* `provenance.<segment>.jsonl` with `<segment>` containing no dot — an unsanitised
|
|
6
|
-
* `
|
|
6
|
+
* `my-host.local` would produce `provenance.my-host.local.jsonl`, which the
|
|
7
7
|
* schema check would not recognise as a replica chain at all. Two rules disagreeing about the same
|
|
8
8
|
* file is worse than either rule being wrong.
|
|
9
9
|
*/
|
|
@@ -56,7 +56,7 @@ const STORE = path.join('.ax', 'state', 'replica-id');
|
|
|
56
56
|
*
|
|
57
57
|
* DOTS ARE THE POINT. macOS hostnames end in `.local`, and the schema rule reads
|
|
58
58
|
* `provenance.<segment>.jsonl` with `<segment>` containing no dot — an unsanitised
|
|
59
|
-
* `
|
|
59
|
+
* `my-host.local` would produce `provenance.my-host.local.jsonl`, which the
|
|
60
60
|
* schema check would not recognise as a replica chain at all. Two rules disagreeing about the same
|
|
61
61
|
* file is worse than either rule being wrong.
|
|
62
62
|
*/
|