@holmes-lab/holmes-kit 0.39.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 +344 -6
- package/README.md +54 -41
- 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 +49 -13
- package/dist/holmes/cli/approve.js +249 -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 +34 -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 +202 -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.js +1 -1
- 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 +3 -1
- package/dist/holmes/cli/run-provision.js +255 -44
- 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 +21 -0
- package/dist/holmes/cli/run.js +341 -92
- 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 +26 -0
- package/dist/holmes/governance/approval-queue.js +109 -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/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 +64 -10
- package/dist/holmes/guardrail/risk-classifier.d.ts +15 -9
- package/dist/holmes/guardrail/risk-classifier.js +228 -16
- 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.js +24 -8
- package/dist/holmes/guardrail/run-stages.d.ts +5 -0
- package/dist/holmes/guardrail/run-stages.js +25 -5
- 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 +1134 -167
- 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/stop.d.ts +23 -0
- package/dist/holmes/hooks/stop.js +86 -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 +3 -0
- package/dist/holmes/mcp/handlers/approval-ask.js +18 -7
- 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-queries.d.ts +2 -2
- package/dist/holmes/mcp/handlers.d.ts +89 -79
- package/dist/holmes/mcp/handlers.js +69 -22
- 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.js +1 -1
- package/dist/holmes/mcp/server.js +9 -8
- 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 +29 -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/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 +105 -8
- package/dist/holmes/review/verdicts.js +640 -36
- 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,38 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The one place a person-channel actor is minted. A ledger row under `elicitation:` or `host-gated:` says a person
|
|
3
|
+
* decided in a form or a host's approval dialog; the server writes one only after its form gate passed, from the
|
|
4
|
+
* attested harness, never from a tool's input (F1-e.0d: risk_check recorded a forged `elicitation:claude-code`).
|
|
5
|
+
* The prefixes are spelled in this file only; a census holds every other spelling under src/holmes at zero.
|
|
6
|
+
*
|
|
7
|
+
* @implements A-SPEC-792.26 — a type brand on a string is erased at run time, so a ledger seam could not tell a minted
|
|
8
|
+
* `elicitation:claude` from an environment approval with the same text (F1-e.0e: reproduced). A minted actor is a
|
|
9
|
+
* frozen object this module registers; every ledger seam writes its actor through ledgerActor, which writes a
|
|
10
|
+
* registered object as its text and any string that claims a person channel as `unattested:<string>`.
|
|
11
|
+
*/
|
|
12
|
+
declare const humanChannel: unique symbol;
|
|
13
|
+
/**
|
|
14
|
+
* A person-channel actor, minted only by humanChannelActor: a frozen String object, so string methods and
|
|
15
|
+
* interpolation read its text, while it is not a `string` and only a seam turns it into one.
|
|
16
|
+
*/
|
|
17
|
+
export interface HumanChannelActor extends String {
|
|
18
|
+
readonly value: string;
|
|
19
|
+
readonly [humanChannel]: true;
|
|
20
|
+
}
|
|
21
|
+
/** What a ledger seam accepts as an actor. */
|
|
22
|
+
export type LedgerActor = string | HumanChannelActor;
|
|
23
|
+
declare const PREFIX: {
|
|
24
|
+
readonly elicitation: "elicitation:";
|
|
25
|
+
readonly 'host-gated': "host-gated:";
|
|
26
|
+
};
|
|
27
|
+
export declare function humanChannelActor(channel: keyof typeof PREFIX, harness: string): HumanChannelActor;
|
|
28
|
+
/** Whether a string claims a person channel, in any case, spacing or Unicode spelling. */
|
|
29
|
+
export declare function isHumanChannelActor(s: unknown): boolean;
|
|
30
|
+
/** Whether an actor value came from the mint. */
|
|
31
|
+
export declare function isMinted(a: unknown): a is HumanChannelActor;
|
|
32
|
+
/** The text a ledger seam writes for an actor: a minted one as is, a claimed person channel as unattested. */
|
|
33
|
+
export declare function ledgerActor(a: LedgerActor | unknown): string;
|
|
34
|
+
/** An authorization reference written beside an actor: one claiming a person channel stands only with a minted actor. */
|
|
35
|
+
export declare function ledgerAuthorization(authorization: string | undefined, actor: LedgerActor | unknown): string | undefined;
|
|
36
|
+
/** An actor that came in through a tool's input: recorded as such, never as a person. */
|
|
37
|
+
export declare function toolInputActor(s: LedgerActor | undefined): string;
|
|
38
|
+
export {};
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.humanChannelActor = humanChannelActor;
|
|
4
|
+
exports.isHumanChannelActor = isHumanChannelActor;
|
|
5
|
+
exports.isMinted = isMinted;
|
|
6
|
+
exports.ledgerActor = ledgerActor;
|
|
7
|
+
exports.ledgerAuthorization = ledgerAuthorization;
|
|
8
|
+
exports.toolInputActor = toolInputActor;
|
|
9
|
+
const PREFIX = { elicitation: 'elicitation:', 'host-gated': 'host-gated:' };
|
|
10
|
+
const minted = new WeakSet();
|
|
11
|
+
function humanChannelActor(channel, harness) {
|
|
12
|
+
const value = `${PREFIX[channel]}${harness}`;
|
|
13
|
+
// a summary that interpolates the actor reads its text; that text handed back to a seam is unattested
|
|
14
|
+
const actor = Object.freeze(Object.assign(new String(value), { value }));
|
|
15
|
+
minted.add(actor);
|
|
16
|
+
return actor;
|
|
17
|
+
}
|
|
18
|
+
/** Folded as a reader would: NFKC, lower case, and nothing but `a-z`, `0-9` and `:` kept (`host‐gated`, ` Elicitation`). */
|
|
19
|
+
const fold = (s) => s.normalize('NFKC').toLowerCase().replace(/[^a-z0-9:]/g, '');
|
|
20
|
+
const FOLDED = Object.values(PREFIX).map(fold);
|
|
21
|
+
/** Whether a string claims a person channel, in any case, spacing or Unicode spelling. */
|
|
22
|
+
function isHumanChannelActor(s) {
|
|
23
|
+
return typeof s === 'string' && FOLDED.some((p) => fold(s).startsWith(p));
|
|
24
|
+
}
|
|
25
|
+
/** Whether an actor value came from the mint. */
|
|
26
|
+
function isMinted(a) {
|
|
27
|
+
return typeof a === 'object' && a !== null && minted.has(a);
|
|
28
|
+
}
|
|
29
|
+
/** The text a ledger seam writes for an actor: a minted one as is, a claimed person channel as unattested. */
|
|
30
|
+
function ledgerActor(a) {
|
|
31
|
+
if (isMinted(a))
|
|
32
|
+
return a.value;
|
|
33
|
+
const s = typeof a === 'string' ? a
|
|
34
|
+
: typeof a === 'object' && a !== null && typeof a.value === 'string' ? a.value
|
|
35
|
+
: String(a);
|
|
36
|
+
// @implements A-SPEC-792.27 — and anything outside printable ASCII: confusables (Cyrillic е, U+A789, a combining
|
|
37
|
+
// accent) slipped past the fold, and a closed rule ends that family; a non-ASCII OS user is over-marked, never a person
|
|
38
|
+
return isHumanChannelActor(s) || /[^\x20-\x7e]/.test(s) ? `unattested:${s}` : s;
|
|
39
|
+
}
|
|
40
|
+
/** An authorization reference written beside an actor: one claiming a person channel stands only with a minted actor. */
|
|
41
|
+
function ledgerAuthorization(authorization, actor) {
|
|
42
|
+
if (authorization === undefined || isMinted(actor) || !isHumanChannelActor(authorization))
|
|
43
|
+
return authorization;
|
|
44
|
+
return `unattested:${authorization}`;
|
|
45
|
+
}
|
|
46
|
+
/** An actor that came in through a tool's input: recorded as such, never as a person. */
|
|
47
|
+
function toolInputActor(s) {
|
|
48
|
+
return `tool-input:${s === undefined ? 'unknown' : String(s)}`;
|
|
49
|
+
}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
export declare const INSTALL_MANIFEST: string;
|
|
2
|
+
export interface ManifestFile {
|
|
3
|
+
path: string;
|
|
4
|
+
sha256: string;
|
|
5
|
+
}
|
|
6
|
+
export interface ProductProblem {
|
|
7
|
+
path?: string;
|
|
8
|
+
why: 'manifest-missing' | 'manifest-invalid' | 'manifest-tampered' | 'missing' | 'changed' | 'staged' | 'in-index';
|
|
9
|
+
}
|
|
10
|
+
export declare function readInstallManifest(root: string): ManifestFile[] | null;
|
|
11
|
+
/**
|
|
12
|
+
* Records `paths` (absolute or target-relative) and every path the previous manifest listed that still exists, each with
|
|
13
|
+
* the sha256 of its content now; a path outside the target is never listed.
|
|
14
|
+
*/
|
|
15
|
+
export declare function writeInstallManifest(target: string, paths: string[], version: string): void;
|
|
16
|
+
export declare function removeInstallManifest(target: string): void;
|
|
17
|
+
/**
|
|
18
|
+
* Each manifest file that is missing, changed against its digest, in `staged` (paths a command stages, target-relative)
|
|
19
|
+
* or staged in the index against HEAD; `manifest-missing` when there is no readable manifest.
|
|
20
|
+
*/
|
|
21
|
+
export declare function productInstalledProblems(root: string, staged?: string[]): ProductProblem[];
|
|
22
|
+
export declare function describeProductInstalled(problems: ProductProblem[]): string;
|
|
@@ -0,0 +1,160 @@
|
|
|
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.INSTALL_MANIFEST = void 0;
|
|
37
|
+
exports.readInstallManifest = readInstallManifest;
|
|
38
|
+
exports.writeInstallManifest = writeInstallManifest;
|
|
39
|
+
exports.removeInstallManifest = removeInstallManifest;
|
|
40
|
+
exports.productInstalledProblems = productInstalledProblems;
|
|
41
|
+
exports.describeProductInstalled = describeProductInstalled;
|
|
42
|
+
// @implements A-SPEC-792.16, A-SPEC-222.10, A-SPEC-794.55, A-SPEC-794.57
|
|
43
|
+
/**
|
|
44
|
+
* The files the product installed in a target, by path and digest, as init recorded them. A self-approval must never
|
|
45
|
+
* cover one of them: a changed, staged or missing product file — or no record at all — is a reason to refuse.
|
|
46
|
+
*/
|
|
47
|
+
const crypto = __importStar(require("node:crypto"));
|
|
48
|
+
const fs = __importStar(require("node:fs"));
|
|
49
|
+
const path = __importStar(require("node:path"));
|
|
50
|
+
const bounded_io_1 = require("../project/bounded-io");
|
|
51
|
+
exports.INSTALL_MANIFEST = path.join('.ax', 'state', 'install-manifest.json');
|
|
52
|
+
const MANIFEST_EVENT = 'install-manifest';
|
|
53
|
+
const digestOf = (abs) => {
|
|
54
|
+
try {
|
|
55
|
+
return crypto.createHash('sha256').update(fs.readFileSync(abs)).digest('hex');
|
|
56
|
+
}
|
|
57
|
+
catch {
|
|
58
|
+
return null;
|
|
59
|
+
}
|
|
60
|
+
};
|
|
61
|
+
const inside = (root, abs) => { const r = path.relative(root, abs); return r !== '' && !r.startsWith('..') && !path.isAbsolute(r); };
|
|
62
|
+
function readInstallManifest(root) {
|
|
63
|
+
const r = readManifestChecked(root);
|
|
64
|
+
return r === null ? null : r.files;
|
|
65
|
+
}
|
|
66
|
+
/** The manifest's entries, and whether any entry was malformed (dropped). Null when there is no readable manifest. */
|
|
67
|
+
function readManifestChecked(root) {
|
|
68
|
+
try {
|
|
69
|
+
const m = JSON.parse(fs.readFileSync(path.join(root, exports.INSTALL_MANIFEST), 'utf8'));
|
|
70
|
+
if (!Array.isArray(m.files))
|
|
71
|
+
return null;
|
|
72
|
+
const files = m.files.filter((f) => !!f && typeof f.path === 'string' && typeof f.sha256 === 'string');
|
|
73
|
+
return { files, malformed: files.length !== m.files.length };
|
|
74
|
+
}
|
|
75
|
+
catch {
|
|
76
|
+
return null;
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
/** @implements A-SPEC-792.18 — the digest the last init recorded for the manifest, or null when none is recorded. */
|
|
80
|
+
function recordedManifestDigest(root) {
|
|
81
|
+
try {
|
|
82
|
+
// @implements A-SPEC-222.10 — H-C (M-3): the recorded digest comes from trusted events (a forged event hid tampering)
|
|
83
|
+
const { TrustedLedgerStore } = require('./recorded-pairs');
|
|
84
|
+
const evs = new TrustedLedgerStore(path.join(root, '.ax', 'ledger')).loadAll();
|
|
85
|
+
for (let i = evs.length - 1; i >= 0; i--) {
|
|
86
|
+
if (evs[i].kind !== MANIFEST_EVENT)
|
|
87
|
+
continue;
|
|
88
|
+
const d = (evs[i].inputs ?? []).find((x) => x.startsWith('sha256:'));
|
|
89
|
+
return d ? d.slice(7) : null;
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
catch { /* unreadable ledger: nothing is recorded */ }
|
|
93
|
+
return null;
|
|
94
|
+
}
|
|
95
|
+
/**
|
|
96
|
+
* Records `paths` (absolute or target-relative) and every path the previous manifest listed that still exists, each with
|
|
97
|
+
* the sha256 of its content now; a path outside the target is never listed.
|
|
98
|
+
*/
|
|
99
|
+
function writeInstallManifest(target, paths, version) {
|
|
100
|
+
const previous = (readInstallManifest(target) ?? []).map((f) => f.path);
|
|
101
|
+
const rels = [...new Set([...paths.map((p) => path.isAbsolute(p) ? p : path.join(target, p)), ...previous.map((p) => path.join(target, p))]
|
|
102
|
+
.filter((abs) => inside(target, abs)).map((abs) => path.relative(target, abs)))].sort();
|
|
103
|
+
const files = rels.map((rel) => ({ path: rel, sha256: digestOf(path.join(target, rel)) })).filter((f) => f.sha256 !== null);
|
|
104
|
+
const file = path.join(target, exports.INSTALL_MANIFEST);
|
|
105
|
+
fs.mkdirSync(path.dirname(file), { recursive: true });
|
|
106
|
+
const tmp = `${file}.${process.pid}.tmp`;
|
|
107
|
+
const text = `${JSON.stringify({ schema: 'install-manifest/1', holmes: version, files }, null, 2)}\n`;
|
|
108
|
+
fs.writeFileSync(tmp, text, { mode: 0o644 });
|
|
109
|
+
fs.renameSync(tmp, file);
|
|
110
|
+
// @implements A-SPEC-792.18 — the manifest's own digest, kept where the judgement can compare it
|
|
111
|
+
const { FileLedgerStore } = require('./ledger-store');
|
|
112
|
+
new FileLedgerStore(path.join(target, '.ax', 'ledger')).append({ ts: new Date().toISOString(), actor: 'holmes-kit init', kind: MANIFEST_EVENT,
|
|
113
|
+
summary: `install manifest of ${files.length} file(s)`, inputs: [`sha256:${crypto.createHash('sha256').update(text).digest('hex')}`] });
|
|
114
|
+
}
|
|
115
|
+
function removeInstallManifest(target) {
|
|
116
|
+
try {
|
|
117
|
+
fs.rmSync(path.join(target, exports.INSTALL_MANIFEST), { force: true });
|
|
118
|
+
}
|
|
119
|
+
catch { /* nothing to remove */ }
|
|
120
|
+
}
|
|
121
|
+
/**
|
|
122
|
+
* Each manifest file that is missing, changed against its digest, in `staged` (paths a command stages, target-relative)
|
|
123
|
+
* or staged in the index against HEAD; `manifest-missing` when there is no readable manifest.
|
|
124
|
+
*/
|
|
125
|
+
function productInstalledProblems(root, staged = []) {
|
|
126
|
+
const checked = readManifestChecked(root);
|
|
127
|
+
if (checked === null)
|
|
128
|
+
return [{ why: 'manifest-missing' }];
|
|
129
|
+
const files = checked.files;
|
|
130
|
+
// @implements A-SPEC-792.18 — a manifest that cannot vouch for anything, or is not the one init recorded, is never clear
|
|
131
|
+
const head = [];
|
|
132
|
+
if (files.length === 0 || checked.malformed)
|
|
133
|
+
head.push({ why: 'manifest-invalid' });
|
|
134
|
+
const recorded = recordedManifestDigest(root);
|
|
135
|
+
if (recorded === null || digestOf(path.join(root, exports.INSTALL_MANIFEST)) !== recorded)
|
|
136
|
+
head.push({ why: 'manifest-tampered' });
|
|
137
|
+
const norm = (p) => path.normalize(p);
|
|
138
|
+
const stagedSet = new Set(staged.map(norm));
|
|
139
|
+
const r = (0, bounded_io_1.gitOnce)(root, ['-c', 'core.fsmonitor=false', 'diff', '--cached', '--name-only', '-z', '--no-renames'], 'repo');
|
|
140
|
+
const indexChanged = new Set(r.status === 0 ? String(r.stdout).split('\0').filter(Boolean).map(norm) : []);
|
|
141
|
+
const out = [...head];
|
|
142
|
+
for (const f of files) {
|
|
143
|
+
const now = digestOf(path.join(root, f.path));
|
|
144
|
+
if (now === null)
|
|
145
|
+
out.push({ path: f.path, why: 'missing' });
|
|
146
|
+
else if (now !== f.sha256)
|
|
147
|
+
out.push({ path: f.path, why: 'changed' });
|
|
148
|
+
// A-SPEC-794.57 — what the command stages, and what the index already holds, are told apart
|
|
149
|
+
if (stagedSet.has(norm(f.path)))
|
|
150
|
+
out.push({ path: f.path, why: 'staged' });
|
|
151
|
+
else if (indexChanged.has(norm(f.path)))
|
|
152
|
+
out.push({ path: f.path, why: 'in-index' });
|
|
153
|
+
}
|
|
154
|
+
return out;
|
|
155
|
+
}
|
|
156
|
+
function describeProductInstalled(problems) {
|
|
157
|
+
return problems.map((p) => p.why === 'manifest-missing' ? 'product-installed: no install manifest (run holmes-kit init)'
|
|
158
|
+
: p.path === undefined ? `product-installed: the install manifest is ${p.why === 'manifest-invalid' ? 'invalid' : 'not the one init recorded'} (${p.why})`
|
|
159
|
+
: `product-installed: ${p.path} (${p.why === 'in-index' ? 'already in the index' : p.why})`).join('; ');
|
|
160
|
+
}
|
|
@@ -104,6 +104,8 @@ function rechainLedger(mainline, working, key) {
|
|
|
104
104
|
// Timestamp order, stable for ties (Array#sort is stable): the tail reads chronologically.
|
|
105
105
|
orphans.sort((a, b) => (a.ts < b.ts ? -1 : a.ts > b.ts ? 1 : 0));
|
|
106
106
|
const events = [...mainline];
|
|
107
|
+
// @implements A-SPEC-792.27 — the seams' named limit: an orphan is re-chained VERBATIM. Its actor was judged when it
|
|
108
|
+
// was first written (ledgerActor), and judging the recorded text again would mark every person row unattested.
|
|
107
109
|
for (const o of orphans)
|
|
108
110
|
events.push((0, provenance_chain_1.chainNext)(events, bodyOf(o), key));
|
|
109
111
|
return { events, orphanCount: orphans.length, alreadyVerified: false };
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { LedgerStore } from './ledger-store';
|
|
1
|
+
import { LedgerStore, SpendLedger } from './ledger-store';
|
|
2
2
|
/**
|
|
3
3
|
* The ONE conformance suite every `LedgerStore` adapter must pass.
|
|
4
4
|
*
|
|
@@ -9,3 +9,9 @@ import { LedgerStore } from './ledger-store';
|
|
|
9
9
|
* implementation, and finding that now is the whole reason a second adapter exists.
|
|
10
10
|
*/
|
|
11
11
|
export declare function ledgerStoreConformance(name: string, make: () => LedgerStore): void;
|
|
12
|
+
/**
|
|
13
|
+
* @implements A-SPEC-245.12 (X5) — the clauses every SpendLedger adapter must pass, against the contract only: a first
|
|
14
|
+
* spend is appended, a second of the same nonce is spent and writes nothing, another nonce is appended, and a spend
|
|
15
|
+
* row written before fingerprints (the raw nonce) still counts as spent.
|
|
16
|
+
*/
|
|
17
|
+
export declare function spendLedgerConformance(name: string, make: () => SpendLedger & LedgerStore): void;
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
3
|
exports.ledgerStoreConformance = ledgerStoreConformance;
|
|
4
|
+
exports.spendLedgerConformance = spendLedgerConformance;
|
|
4
5
|
/**
|
|
5
6
|
* The ONE conformance suite every `LedgerStore` adapter must pass.
|
|
6
7
|
*
|
|
@@ -88,3 +89,68 @@ function ledgerStoreConformance(name, make) {
|
|
|
88
89
|
});
|
|
89
90
|
});
|
|
90
91
|
}
|
|
92
|
+
/**
|
|
93
|
+
* @implements A-SPEC-245.12 (X5) — the clauses every SpendLedger adapter must pass, against the contract only: a first
|
|
94
|
+
* spend is appended, a second of the same nonce is spent and writes nothing, another nonce is appended, and a spend
|
|
95
|
+
* row written before fingerprints (the raw nonce) still counts as spent.
|
|
96
|
+
*/
|
|
97
|
+
function spendLedgerConformance(name, make) {
|
|
98
|
+
const { nonceFingerprint } = require('./provenance-chain');
|
|
99
|
+
const spend = (nonce) => ({ nonce, row: { ts: '2026-10-27T00:00:00.000Z', actor: 'a', kind: 'nonce-consumed', summary: 's', inputs: [nonceFingerprint(nonce)], rationale: 'r' } });
|
|
100
|
+
const spentRows = (s) => s.loadAll().filter((e) => e.kind === 'nonce-consumed').length;
|
|
101
|
+
const far = () => Date.now() + 5000;
|
|
102
|
+
describe(`SpendLedger conformance — ${name} (A-SPEC-245.12)`, () => {
|
|
103
|
+
it('normal: a first spend is appended, a second of the same nonce is spent and writes nothing', () => {
|
|
104
|
+
const s = make();
|
|
105
|
+
expect(s.appendIfUnspent([spend('N-1')], far())).toBe('appended');
|
|
106
|
+
expect(s.appendIfUnspent([spend('N-1')], far())).toBe('spent');
|
|
107
|
+
expect(spentRows(s)).toBe(1);
|
|
108
|
+
});
|
|
109
|
+
it('corner: another nonce is appended beside a spent one', () => {
|
|
110
|
+
const s = make();
|
|
111
|
+
s.appendIfUnspent([spend('N-1')], far());
|
|
112
|
+
expect(s.appendIfUnspent([spend('N-2')], far())).toBe('appended');
|
|
113
|
+
expect(spentRows(s)).toBe(2);
|
|
114
|
+
});
|
|
115
|
+
it('boundary (A-SPEC-245.13, Y4): with the second of two nonces spent, the call is spent and writes nothing', () => {
|
|
116
|
+
const s = make();
|
|
117
|
+
s.appendIfUnspent([spend('N-2')], far());
|
|
118
|
+
expect(s.appendIfUnspent([spend('N-1'), spend('N-2')], far())).toBe('spent');
|
|
119
|
+
expect(s.loadAll().filter((e) => e.kind === 'nonce-consumed').map((e) => e.inputs)).toEqual([[nonceFingerprint('N-2')]]);
|
|
120
|
+
});
|
|
121
|
+
it('negative: a spend row that carries the raw nonce (written before fingerprints) counts as spent', () => {
|
|
122
|
+
const s = make();
|
|
123
|
+
s.append({ ts: '2026-10-27T00:00:00.000Z', actor: 'old', kind: 'nonce-consumed', summary: 's', inputs: ['N-raw'] });
|
|
124
|
+
expect(s.appendIfUnspent([spend('N-raw')], far())).toBe('spent');
|
|
125
|
+
});
|
|
126
|
+
// @implements A-SPEC-245.9 (1b-3, M-10) — the revocation operation, on both adapters
|
|
127
|
+
const revocation = (nonce) => ({ ts: '2026-10-27T00:00:00.000Z', actor: 'op', kind: 'nonce-revoked', summary: 'revoked', inputs: [nonceFingerprint(nonce)], rationale: 'r' });
|
|
128
|
+
// typed loosely, so an adapter without the operation is red as an assertion, not a type error
|
|
129
|
+
const revoke = (s, nonce) => s.appendRevocationIfUnspent?.(nonce, revocation(nonce), far());
|
|
130
|
+
const revokedRows = (s) => s.loadAll().filter((e) => e.kind === 'nonce-revoked').length;
|
|
131
|
+
it('normal (A-SPEC-245.9, M-10): an unspent nonce is revoked once; a second revocation is revoked-already and writes nothing', () => {
|
|
132
|
+
const s = make();
|
|
133
|
+
expect(revoke(s, 'R-1')).toBe('revoked');
|
|
134
|
+
expect(revoke(s, 'R-1')).toBe('revoked-already');
|
|
135
|
+
expect(revokedRows(s)).toBe(1);
|
|
136
|
+
});
|
|
137
|
+
it('negative (A-SPEC-245.9, M-10): a spent nonce is not revoked — the answer is spent and nothing is written', () => {
|
|
138
|
+
const s = make();
|
|
139
|
+
s.appendIfUnspent([spend('R-2')], far());
|
|
140
|
+
expect(revoke(s, 'R-2')).toBe('spent');
|
|
141
|
+
expect(revokedRows(s)).toBe(0);
|
|
142
|
+
});
|
|
143
|
+
it('negative (A-SPEC-245.16, item 1): a revoked nonce is not spent — the spend answers revoked and writes nothing', () => {
|
|
144
|
+
const s = make();
|
|
145
|
+
s.append(revocation('R-RV'));
|
|
146
|
+
expect(s.appendIfUnspent([spend('R-OK'), spend('R-RV')], far())).toBe('revoked');
|
|
147
|
+
expect(spentRows(s)).toBe(0);
|
|
148
|
+
});
|
|
149
|
+
it('corner (A-SPEC-245.9, M-10): a nonce spent by a row written before fingerprints is not revoked', () => {
|
|
150
|
+
const s = make();
|
|
151
|
+
s.append({ ts: '2026-10-27T00:00:00.000Z', actor: 'old', kind: 'nonce-consumed', summary: 's', inputs: ['R-raw'] });
|
|
152
|
+
expect(revoke(s, 'R-raw')).toBe('spent');
|
|
153
|
+
expect(revokedRows(s)).toBe(0);
|
|
154
|
+
});
|
|
155
|
+
});
|
|
156
|
+
}
|
|
@@ -1,5 +1,6 @@
|
|
|
1
|
-
import { ProvenanceEvent } from './provenance-chain';
|
|
1
|
+
import { ProvenanceEvent, AppendBody } from './provenance-chain';
|
|
2
2
|
import { LedgerEvent, DoubleSpend } from './provenance-ledger';
|
|
3
|
+
import { type SpendNamespace } from './spend-kinds';
|
|
3
4
|
/**
|
|
4
5
|
* The ledger as a PORT — ADR-001's deferred half, applied to the one store whose shape was derived
|
|
5
6
|
* from real use rather than guessed at.
|
|
@@ -21,6 +22,8 @@ import { LedgerEvent, DoubleSpend } from './provenance-ledger';
|
|
|
21
22
|
*
|
|
22
23
|
* NOT DECLARED, and why: transactions, batching, pagination, RBAC. No caller needs them, they cannot
|
|
23
24
|
* be verified by the two adapters, and an unverifiable contract clause is worth less than a comment.
|
|
25
|
+
* (A-SPEC-245.12: the one exclusive operation, spending, is the separate SpendLedger port below, with
|
|
26
|
+
* its own conformance clauses — not a transaction on this one.)
|
|
24
27
|
* ADR-001 named speculative port design as the cost of deciding early; this is where that cost is
|
|
25
28
|
* refused.
|
|
26
29
|
*/
|
|
@@ -28,7 +31,7 @@ import { LedgerEvent, DoubleSpend } from './provenance-ledger';
|
|
|
28
31
|
export interface LedgerBroken {
|
|
29
32
|
replicaId: string | null;
|
|
30
33
|
detail?: string;
|
|
31
|
-
kind?: 'chain' | 'double-spend';
|
|
34
|
+
kind?: 'chain' | 'double-spend' | 'revoked-and-consumed';
|
|
32
35
|
nonce?: string;
|
|
33
36
|
events?: DoubleSpend['events'];
|
|
34
37
|
}
|
|
@@ -48,12 +51,48 @@ export interface LedgerStore {
|
|
|
48
51
|
broken: LedgerBroken[];
|
|
49
52
|
};
|
|
50
53
|
/** Append to this writer's chain. Never modifies or removes an existing event. */
|
|
51
|
-
append(body:
|
|
52
|
-
/** Spent on ANY chain — see the interface note. */
|
|
53
|
-
isNonceConsumed(nonce: string): boolean;
|
|
54
|
+
append(body: AppendBody): ProvenanceEvent;
|
|
55
|
+
/** Spent on ANY chain — see the interface note. A-SPEC-794.4: in the namespace `ns` (the grant namespace by default). */
|
|
56
|
+
isNonceConsumed(nonce: string, ns?: SpendNamespace): boolean;
|
|
54
57
|
/** A-SPEC-642 — single-use nonces consumed more than once across chains and not yet reconciled. */
|
|
55
58
|
doubleSpends(): DoubleSpend[];
|
|
56
59
|
}
|
|
60
|
+
/**
|
|
61
|
+
* @implements A-SPEC-245.12 (X5) — the spend port: one operation, apart from the general LedgerStore its many readers
|
|
62
|
+
* use. `appendIfUnspent` appends each spend's row when none of the nonces is spent on any chain, excluding every other
|
|
63
|
+
* writer it can until the deadline; it answers
|
|
64
|
+
* - `appended`;
|
|
65
|
+
* - `spent`: a nonce was already spent, nothing written;
|
|
66
|
+
* - `conflict`: after the append, a spend of the same approval appeared on a chain begun after the store's last look;
|
|
67
|
+
* - `unconfirmed`: such a chain could not be read, so the spend is not confirmed single.
|
|
68
|
+
* The last two record `spend-conflict-detected`, in words that tell them apart.
|
|
69
|
+
*/
|
|
70
|
+
export interface SpendLedger {
|
|
71
|
+
/** @implements A-SPEC-794.4 — `ns` names the namespace the nonces are judged in (the grant namespace by default). */
|
|
72
|
+
appendIfUnspent(spends: Array<{
|
|
73
|
+
nonce: string;
|
|
74
|
+
row: AppendBody;
|
|
75
|
+
}>, deadline: number, ns?: SpendNamespace): SpendAppend;
|
|
76
|
+
/** @implements A-SPEC-245.9 (1b-3, M-10) — append a revocation row unless the nonce is spent or already revoked. */
|
|
77
|
+
appendRevocationIfUnspent(nonce: string, row: AppendBody, deadline: number, ns?: SpendNamespace): RevocationAppend;
|
|
78
|
+
}
|
|
79
|
+
/** `revoked` (A-SPEC-245.16): a nonce of the call was revoked on some chain — nothing written, like `spent`. */
|
|
80
|
+
export type SpendAppend = 'appended' | 'spent' | 'revoked' | 'conflict' | 'unconfirmed';
|
|
81
|
+
export type RevocationAppend = 'revoked' | 'spent' | 'revoked-already';
|
|
82
|
+
/** The ledger kind of a revocation (A-SPEC-245.9, H-2), in the grant namespace (A-SPEC-794.4). */
|
|
83
|
+
export declare const NONCE_REVOKED: string;
|
|
84
|
+
/**
|
|
85
|
+
* @implements A-SPEC-794.5 — the port binds a row's kind to the namespace it judges: a spend judged in one namespace
|
|
86
|
+
* and written under another kind would be invisible to that namespace's readers, so it is refused before anything is
|
|
87
|
+
* written.
|
|
88
|
+
*/
|
|
89
|
+
export declare class SpendKindMismatch extends Error {
|
|
90
|
+
readonly expected: string;
|
|
91
|
+
readonly actual: string;
|
|
92
|
+
constructor(expected: string, actual: string);
|
|
93
|
+
}
|
|
94
|
+
/** The least time a late chain gets to be read, even when the spend's budget is spent (reviewer A, L1). */
|
|
95
|
+
export declare const LATE_CHAIN_READ_MS = 500;
|
|
57
96
|
/**
|
|
58
97
|
* @implements A-SPEC-643
|
|
59
98
|
* The chain file THIS process writes: `provenance.<replica>.jsonl`, resolved exactly as every other
|
|
@@ -87,7 +126,7 @@ export declare function ledgerConflictReason(dir: string): string | null;
|
|
|
87
126
|
* wrote files itself would satisfy every conformance test while silently dropping all three, and
|
|
88
127
|
* nothing in this suite would notice — which is why a structural test pins the delegation too.
|
|
89
128
|
*/
|
|
90
|
-
export declare class FileLedgerStore implements LedgerStore {
|
|
129
|
+
export declare class FileLedgerStore implements LedgerStore, SpendLedger {
|
|
91
130
|
private readonly dir;
|
|
92
131
|
private readonly givenId?;
|
|
93
132
|
private readonly inner;
|
|
@@ -111,10 +150,41 @@ export declare class FileLedgerStore implements LedgerStore {
|
|
|
111
150
|
ok: boolean;
|
|
112
151
|
broken: LedgerBroken[];
|
|
113
152
|
};
|
|
114
|
-
append(body:
|
|
115
|
-
isNonceConsumed(nonce: string): boolean;
|
|
153
|
+
append(body: AppendBody): ProvenanceEvent;
|
|
154
|
+
isNonceConsumed(nonce: string, ns?: SpendNamespace): boolean;
|
|
116
155
|
doubleSpends(): DoubleSpend[];
|
|
156
|
+
/**
|
|
157
|
+
* @implements A-SPEC-245.10, A-SPEC-245.11, A-SPEC-245.12 — the spend port on files: append the spend rows to this
|
|
158
|
+
* writer's chain while holding every replica chain's append lock, taken in sorted path order within the deadline.
|
|
159
|
+
* The chains are enumerated with their lock directories (M-a): a chain whose first append is in progress has a lock
|
|
160
|
+
* and no file yet, and is waited for. This writer's own chain is included even when absent. If a chain appears
|
|
161
|
+
* while the locks are taken, they are released and taken again. The spent check runs inside all the locks. After
|
|
162
|
+
* the append, still holding them, chains begun since are waited for (at least LATE_CHAIN_READ_MS) and read (W2).
|
|
163
|
+
* Throws the lock layer's error when the deadline passes before the append.
|
|
164
|
+
*/
|
|
165
|
+
appendIfUnspent(spends: Array<{
|
|
166
|
+
nonce: string;
|
|
167
|
+
row: AppendBody;
|
|
168
|
+
}>, deadline: number, ns?: SpendNamespace): SpendAppend;
|
|
169
|
+
/**
|
|
170
|
+
* @implements A-SPEC-245.9 (1b-3, M-10) — revocation on files: under every replica chain's append lock, a nonce
|
|
171
|
+
* spent on any chain answers `spent`, one already revoked answers `revoked-already`, and otherwise the revocation row
|
|
172
|
+
* is appended (`revoked`). A spend that appears later on a chain begun after the enumeration is N10's report.
|
|
173
|
+
*/
|
|
174
|
+
appendRevocationIfUnspent(nonce: string, row: AppendBody, deadline: number, ns?: SpendNamespace): RevocationAppend;
|
|
175
|
+
/**
|
|
176
|
+
* Run `body` holding every replica chain's append lock, taken in sorted path order within `deadline` (A-SPEC-245.10,
|
|
177
|
+
* 245.11): the chains are enumerated with their lock directories, this writer's own chain is included even when
|
|
178
|
+
* absent, and a chain that appears while the locks are taken starts the round again. Throws the lock layer's error
|
|
179
|
+
* when the deadline passes first.
|
|
180
|
+
*/
|
|
181
|
+
private underEveryChainLock;
|
|
117
182
|
}
|
|
183
|
+
/** @implements A-SPEC-245.9 (1b-3) — whether a ledger holds a revocation of `nonce` (its fingerprint, or the raw value). */
|
|
184
|
+
export declare function nonceRevokedIn(events: Array<{
|
|
185
|
+
kind: string;
|
|
186
|
+
inputs?: string[];
|
|
187
|
+
}>, nonce: string, ns?: SpendNamespace): boolean;
|
|
118
188
|
/**
|
|
119
189
|
* In-memory adapter — the instrument that makes the contract testable.
|
|
120
190
|
*
|
|
@@ -122,7 +192,7 @@ export declare class FileLedgerStore implements LedgerStore {
|
|
|
122
192
|
* adapter in disguise and would prove nothing about coupling. It reuses the pure chain functions
|
|
123
193
|
* (`chainNext`, `verifyChain`) because those are the format, not the storage.
|
|
124
194
|
*/
|
|
125
|
-
export declare class MemoryLedgerStore implements LedgerStore {
|
|
195
|
+
export declare class MemoryLedgerStore implements LedgerStore, SpendLedger {
|
|
126
196
|
private readonly id;
|
|
127
197
|
private readonly byReplica;
|
|
128
198
|
constructor(id?: string);
|
|
@@ -136,9 +206,16 @@ export declare class MemoryLedgerStore implements LedgerStore {
|
|
|
136
206
|
ok: boolean;
|
|
137
207
|
broken: LedgerBroken[];
|
|
138
208
|
};
|
|
139
|
-
append(body:
|
|
140
|
-
isNonceConsumed(nonce: string): boolean;
|
|
209
|
+
append(body: AppendBody): ProvenanceEvent;
|
|
210
|
+
isNonceConsumed(nonce: string, ns?: SpendNamespace): boolean;
|
|
141
211
|
doubleSpends(): DoubleSpend[];
|
|
212
|
+
/** One process, no other writer to exclude: check, then append (A-SPEC-245.12, the spend port's in-memory form). */
|
|
213
|
+
appendIfUnspent(spends: Array<{
|
|
214
|
+
nonce: string;
|
|
215
|
+
row: AppendBody;
|
|
216
|
+
}>, _deadline: number, ns?: SpendNamespace): SpendAppend;
|
|
217
|
+
/** @implements A-SPEC-245.9 (1b-3, M-10) — the revocation port's in-memory form: check, then append. */
|
|
218
|
+
appendRevocationIfUnspent(nonce: string, row: AppendBody, _deadline: number, ns?: SpendNamespace): RevocationAppend;
|
|
142
219
|
}
|
|
143
220
|
/**
|
|
144
221
|
* The cross-replica nonce check, bound to one ledger file, ready to hand to
|