@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,82 @@
|
|
|
1
|
+
export declare const SPEND_LOCK_PARENT = ".ax/state/spend-lock";
|
|
2
|
+
export declare const SPEND_LOCK_DIR = ".ax/state/spend-lock/held";
|
|
3
|
+
export declare const SPEND_CLAIMS_DIR = ".ax/state/spend-recovery-claims";
|
|
4
|
+
export declare const SPEND_RETIRED_DIR = ".ax/state/spend-retired-locks";
|
|
5
|
+
export declare const SPEND_LEAKS_FILE = ".ax/state/spend-lock-leaks.jsonl";
|
|
6
|
+
export interface SpendHolder {
|
|
7
|
+
kind: 'spend';
|
|
8
|
+
token: string;
|
|
9
|
+
pid: number;
|
|
10
|
+
host: string | null;
|
|
11
|
+
bootId: string | null;
|
|
12
|
+
acquiredAt: string;
|
|
13
|
+
boundMs: number;
|
|
14
|
+
nonces: string[];
|
|
15
|
+
}
|
|
16
|
+
export interface SpendIdentity {
|
|
17
|
+
host: string | null;
|
|
18
|
+
bootId: string | null;
|
|
19
|
+
}
|
|
20
|
+
export type SpendVerdict = {
|
|
21
|
+
dead: true;
|
|
22
|
+
case: 1 | 2;
|
|
23
|
+
} | {
|
|
24
|
+
dead: false;
|
|
25
|
+
reason: 'host' | 'boot-unknown' | 'case-1-off' | 'alive' | 'leak';
|
|
26
|
+
};
|
|
27
|
+
/**
|
|
28
|
+
* Whether a spend holder is certainly dead. Never across hosts or with a null identity; case 1 (another boot of this
|
|
29
|
+
* host) is off on darwin; case 2 (this boot) needs ESRCH. This process's pid is never dead (R1): this module's own
|
|
30
|
+
* token is a leak, any other is another thread or module copy.
|
|
31
|
+
*/
|
|
32
|
+
export declare function spendVerdict(holder: {
|
|
33
|
+
pid: number;
|
|
34
|
+
host: string | null;
|
|
35
|
+
bootId: string | null;
|
|
36
|
+
token: string;
|
|
37
|
+
}, me: SpendIdentity, platform: NodeJS.Platform, probe?: (pid: number) => 'dead' | 'alive'): SpendVerdict;
|
|
38
|
+
/** A recovery claim older than this may be taken as dead by the operator (A-SPEC-245.11, W3). */
|
|
39
|
+
export declare const CLAIM_STALE_MS = 60000;
|
|
40
|
+
/** The spend lock's holder record, or null when no lock is held or it cannot be read. */
|
|
41
|
+
export declare function spendLockHolder(root: string): SpendHolder | null;
|
|
42
|
+
export interface SpendLockOptions {
|
|
43
|
+
budgetMs: number;
|
|
44
|
+
nonces?: string[];
|
|
45
|
+
/** The step bound of the commit kind held under the lock; doctor's alarm fires at 4x. */
|
|
46
|
+
boundMs?: number;
|
|
47
|
+
identity?: SpendIdentity;
|
|
48
|
+
platform?: NodeJS.Platform;
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* Take the workspace spend lock within `budgetMs`, recovering a certainly dead holder on the way. Busy past the budget
|
|
52
|
+
* is `lock-busy` — every pass that does not acquire checks the deadline and waits (R2); this module's own hold is
|
|
53
|
+
* `lock-leak`; a lock without a readable holder is `unknown-owner`.
|
|
54
|
+
*/
|
|
55
|
+
export declare function acquireSpendLock(root: string, opts: SpendLockOptions): {
|
|
56
|
+
token: string;
|
|
57
|
+
release(): void;
|
|
58
|
+
};
|
|
59
|
+
export declare function withSpendLock<T>(root: string, opts: SpendLockOptions, act: () => T): T;
|
|
60
|
+
export type OperatorRecovery = {
|
|
61
|
+
recovered: SpendHolder;
|
|
62
|
+
reason: string;
|
|
63
|
+
} | {
|
|
64
|
+
refused: string;
|
|
65
|
+
} | {
|
|
66
|
+
nothing: true;
|
|
67
|
+
};
|
|
68
|
+
/**
|
|
69
|
+
* The operator's recovery of the spend lock. The caller judges the harness first.
|
|
70
|
+
* - A dead holder is recovered.
|
|
71
|
+
* - Another host, a null identity, or another boot on darwin needs `confirmHolderDead`.
|
|
72
|
+
* - An answering holder (alive, EPERM, or a reused pid) needs `confirmHolderDead` and a hold longer than 4x its bound
|
|
73
|
+
* (M-b); this process's own hold is refused.
|
|
74
|
+
* - Only the generation judged is retired (R3): a lock that changed hands meanwhile is refused.
|
|
75
|
+
*/
|
|
76
|
+
export declare function recoverSpendLockAsOperator(root: string, opts: {
|
|
77
|
+
confirmHolderDead: boolean;
|
|
78
|
+
identity?: SpendIdentity;
|
|
79
|
+
platform?: NodeJS.Platform;
|
|
80
|
+
now?: () => number;
|
|
81
|
+
expectToken?: string | null;
|
|
82
|
+
}): OperatorRecovery;
|
|
@@ -0,0 +1,413 @@
|
|
|
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.CLAIM_STALE_MS = exports.SPEND_LEAKS_FILE = exports.SPEND_RETIRED_DIR = exports.SPEND_CLAIMS_DIR = exports.SPEND_LOCK_DIR = exports.SPEND_LOCK_PARENT = void 0;
|
|
37
|
+
exports.spendVerdict = spendVerdict;
|
|
38
|
+
exports.spendLockHolder = spendLockHolder;
|
|
39
|
+
exports.acquireSpendLock = acquireSpendLock;
|
|
40
|
+
exports.withSpendLock = withSpendLock;
|
|
41
|
+
exports.recoverSpendLockAsOperator = recoverSpendLockAsOperator;
|
|
42
|
+
// @implements A-SPEC-245.10, A-SPEC-245.11, A-SPEC-245.12
|
|
43
|
+
/**
|
|
44
|
+
* The workspace spend lock: one holder per workspace for spending single-use approvals (slice 1a of A-SPEC-245.7,
|
|
45
|
+
* moved here from owned-lock.ts by A-SPEC-245.10), on the owned-lock protocol.
|
|
46
|
+
*
|
|
47
|
+
* Recovery is automatic only when the holder is certainly dead: never across hosts or with a null host or boot id;
|
|
48
|
+
* case 1 (another boot of this host) off on darwin; case 2 (this boot, the pid answering ESRCH). A holder with this
|
|
49
|
+
* process's pid is never dead (R1): its token in this module's registry is a leak, otherwise it is another thread or
|
|
50
|
+
* another copy of this module, alive. Acquisition never runs past its budget (R2), and the operator retires only the
|
|
51
|
+
* generation it judged (R3).
|
|
52
|
+
*
|
|
53
|
+
* Limits: one host and a local file system; an earlier holder of this boot whose pid this process now has waits for
|
|
54
|
+
* the operator.
|
|
55
|
+
*/
|
|
56
|
+
const fs = __importStar(require("node:fs"));
|
|
57
|
+
const path = __importStar(require("node:path"));
|
|
58
|
+
const node_crypto_1 = require("node:crypto");
|
|
59
|
+
const owned_lock_1 = require("./owned-lock");
|
|
60
|
+
exports.SPEND_LOCK_PARENT = '.ax/state/spend-lock';
|
|
61
|
+
exports.SPEND_LOCK_DIR = `${exports.SPEND_LOCK_PARENT}/held`;
|
|
62
|
+
exports.SPEND_CLAIMS_DIR = '.ax/state/spend-recovery-claims';
|
|
63
|
+
exports.SPEND_RETIRED_DIR = '.ax/state/spend-retired-locks';
|
|
64
|
+
exports.SPEND_LEAKS_FILE = '.ax/state/spend-lock-leaks.jsonl';
|
|
65
|
+
const SPEND_LAYOUT = { parent: exports.SPEND_LOCK_PARENT, name: 'held', claims: exports.SPEND_CLAIMS_DIR, retired: exports.SPEND_RETIRED_DIR };
|
|
66
|
+
const FINGERPRINT = /^nonce:[0-9a-f]{12}$/;
|
|
67
|
+
const TRANSIENT = /^\.lock-[0-9a-f-]{36}\.tmp$/;
|
|
68
|
+
/** Plain primitives under one root: no symlinked directories, regular files only, exclusive publication. */
|
|
69
|
+
function plainLockFs(root) {
|
|
70
|
+
const stat = (file) => {
|
|
71
|
+
try {
|
|
72
|
+
return fs.lstatSync(file);
|
|
73
|
+
}
|
|
74
|
+
catch (e) {
|
|
75
|
+
if (e.code === 'ENOENT')
|
|
76
|
+
return undefined;
|
|
77
|
+
throw e;
|
|
78
|
+
}
|
|
79
|
+
};
|
|
80
|
+
const directory = (relative, create = false) => {
|
|
81
|
+
let current = root;
|
|
82
|
+
for (const part of relative.replace(/\\/g, '/').split('/').filter((p) => p !== '' && p !== '.')) {
|
|
83
|
+
if (part === '..')
|
|
84
|
+
throw new owned_lock_1.LockError('unknown-owner', 'inspect', 'Lock paths must be canonical relative locators.');
|
|
85
|
+
current = path.join(current, part);
|
|
86
|
+
if (create && !stat(current)) {
|
|
87
|
+
try {
|
|
88
|
+
fs.mkdirSync(current);
|
|
89
|
+
}
|
|
90
|
+
catch (e) {
|
|
91
|
+
if (e.code !== 'EEXIST')
|
|
92
|
+
throw e;
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
const s = stat(current);
|
|
96
|
+
if (s && (!s.isDirectory() || s.isSymbolicLink()))
|
|
97
|
+
throw new owned_lock_1.LockError('unknown-owner', 'inspect', 'Lock directories must not be symlinks or non-directories.');
|
|
98
|
+
}
|
|
99
|
+
return current;
|
|
100
|
+
};
|
|
101
|
+
const readBytes = (file) => {
|
|
102
|
+
const s = stat(file);
|
|
103
|
+
if (!s)
|
|
104
|
+
return undefined;
|
|
105
|
+
if (!s.isFile())
|
|
106
|
+
throw new owned_lock_1.LockError('unknown-owner', 'inspect', 'Lock records must be regular files.');
|
|
107
|
+
// an unreadable record (EACCES and the like) is preserved ownership, never a raw error (A-SPEC-245.12)
|
|
108
|
+
try {
|
|
109
|
+
return fs.readFileSync(file);
|
|
110
|
+
}
|
|
111
|
+
catch (e) {
|
|
112
|
+
if (e.code === 'ENOENT')
|
|
113
|
+
return undefined;
|
|
114
|
+
throw new owned_lock_1.LockError('unknown-owner', 'inspect', `A lock record that cannot be read (${e.code ?? 'error'}) is preserved for inspection.`);
|
|
115
|
+
}
|
|
116
|
+
};
|
|
117
|
+
return {
|
|
118
|
+
stat, directory, readBytes,
|
|
119
|
+
publish: (relative, bytes) => {
|
|
120
|
+
const dir = directory(path.dirname(relative), true);
|
|
121
|
+
const temp = path.join(dir, `.lock-${(0, node_crypto_1.randomUUID)()}.tmp`);
|
|
122
|
+
fs.writeFileSync(temp, bytes, { flag: 'wx', mode: 0o600 });
|
|
123
|
+
try {
|
|
124
|
+
fs.linkSync(temp, path.join(dir, path.basename(relative)));
|
|
125
|
+
}
|
|
126
|
+
finally {
|
|
127
|
+
fs.unlinkSync(temp);
|
|
128
|
+
}
|
|
129
|
+
},
|
|
130
|
+
rename: (from, to) => fs.renameSync(from, to),
|
|
131
|
+
renameNew: (from, to) => fs.renameSync(from, to),
|
|
132
|
+
appendLine: (file, line) => { directory(path.relative(root, path.dirname(file)), true); fs.appendFileSync(file, line + '\n'); },
|
|
133
|
+
replace: (relative, before, after) => {
|
|
134
|
+
const file = path.join(root, relative);
|
|
135
|
+
if (fs.readFileSync(file, 'utf8') !== before)
|
|
136
|
+
return;
|
|
137
|
+
const temp = `${file}.${(0, node_crypto_1.randomUUID)()}.tmp`;
|
|
138
|
+
fs.writeFileSync(temp, after, { flag: 'wx', mode: 0o600 });
|
|
139
|
+
fs.renameSync(temp, file);
|
|
140
|
+
},
|
|
141
|
+
list: (dir) => fs.readdirSync(dir),
|
|
142
|
+
makeDir: (dir) => fs.mkdirSync(dir),
|
|
143
|
+
writeNew: (file, bytes) => fs.writeFileSync(file, bytes, { flag: 'wx', mode: 0o600 }),
|
|
144
|
+
unlink: (file) => fs.unlinkSync(file),
|
|
145
|
+
removeDir: (dir) => fs.rmdirSync(dir),
|
|
146
|
+
removeTree: (dir) => fs.rmSync(dir, { recursive: true, force: true }),
|
|
147
|
+
isOwnTransient: (name) => TRANSIENT.test(name),
|
|
148
|
+
};
|
|
149
|
+
}
|
|
150
|
+
/** Tokens of spend locks this copy of the module holds, in this thread. */
|
|
151
|
+
const held = new Set();
|
|
152
|
+
function identityOf(given) {
|
|
153
|
+
if (given)
|
|
154
|
+
return given;
|
|
155
|
+
const m = require('./machine-identity');
|
|
156
|
+
return { host: m.hostId(), bootId: m.bootId() };
|
|
157
|
+
}
|
|
158
|
+
function validSpendHolder(r) {
|
|
159
|
+
if (typeof r !== 'object' || r === null)
|
|
160
|
+
return false;
|
|
161
|
+
const o = r;
|
|
162
|
+
const keys = ['kind', 'token', 'pid', 'host', 'bootId', 'acquiredAt', 'boundMs', 'nonces'];
|
|
163
|
+
return Object.keys(o).every((k) => keys.includes(k)) && o.kind === 'spend' && (0, owned_lock_1.isLockToken)(o.token)
|
|
164
|
+
&& Number.isSafeInteger(o.pid) && o.pid > 0
|
|
165
|
+
&& (o.host === null || typeof o.host === 'string') && (o.bootId === null || typeof o.bootId === 'string')
|
|
166
|
+
&& typeof o.acquiredAt === 'string' && typeof o.boundMs === 'number' && o.boundMs > 0
|
|
167
|
+
&& Array.isArray(o.nonces) && o.nonces.every((n) => typeof n === 'string' && FINGERPRINT.test(n));
|
|
168
|
+
}
|
|
169
|
+
function validSpendClaim(r) {
|
|
170
|
+
if (typeof r !== 'object' || r === null)
|
|
171
|
+
return false;
|
|
172
|
+
const o = r;
|
|
173
|
+
const keys = ['kind', 'token', 'pid', 'host', 'bootId', 'claimedAt', 'recovers', 'released'];
|
|
174
|
+
return Object.keys(o).every((k) => keys.includes(k)) && o.kind === 'spend-recovery' && (0, owned_lock_1.isLockToken)(o.token)
|
|
175
|
+
&& Number.isSafeInteger(o.pid) && o.pid > 0
|
|
176
|
+
&& (o.host === null || typeof o.host === 'string') && (o.bootId === null || typeof o.bootId === 'string')
|
|
177
|
+
&& typeof o.claimedAt === 'string' && (0, owned_lock_1.isLockToken)(o.recovers) && (o.released === undefined || o.released === true);
|
|
178
|
+
}
|
|
179
|
+
/**
|
|
180
|
+
* Whether a spend holder is certainly dead. Never across hosts or with a null identity; case 1 (another boot of this
|
|
181
|
+
* host) is off on darwin; case 2 (this boot) needs ESRCH. This process's pid is never dead (R1): this module's own
|
|
182
|
+
* token is a leak, any other is another thread or module copy.
|
|
183
|
+
*/
|
|
184
|
+
function spendVerdict(holder, me, platform, probe = probePid) {
|
|
185
|
+
if (holder.host === null || me.host === null || holder.host !== me.host)
|
|
186
|
+
return { dead: false, reason: 'host' };
|
|
187
|
+
if (holder.bootId === null || me.bootId === null)
|
|
188
|
+
return { dead: false, reason: 'boot-unknown' };
|
|
189
|
+
if (holder.bootId !== me.bootId)
|
|
190
|
+
return platform === 'darwin' ? { dead: false, reason: 'case-1-off' } : { dead: true, case: 1 };
|
|
191
|
+
if (holder.pid === process.pid)
|
|
192
|
+
return { dead: false, reason: held.has(holder.token) ? 'leak' : 'alive' };
|
|
193
|
+
return probe(holder.pid) === 'dead' ? { dead: true, case: 2 } : { dead: false, reason: 'alive' };
|
|
194
|
+
}
|
|
195
|
+
/** ESRCH is dead; an answer or EPERM is alive. */
|
|
196
|
+
function probePid(pid) {
|
|
197
|
+
try {
|
|
198
|
+
process.kill(pid, 0);
|
|
199
|
+
return 'alive';
|
|
200
|
+
}
|
|
201
|
+
catch (e) {
|
|
202
|
+
return e.code === 'ESRCH' ? 'dead' : 'alive';
|
|
203
|
+
}
|
|
204
|
+
}
|
|
205
|
+
/** A recovery claim older than this may be taken as dead by the operator (A-SPEC-245.11, W3). */
|
|
206
|
+
exports.CLAIM_STALE_MS = 60_000;
|
|
207
|
+
/** The spend policy; `force` makes the operator's judgement final for what it covers. */
|
|
208
|
+
function spendPolicy(me, platform, force) {
|
|
209
|
+
return {
|
|
210
|
+
kind: 'spend',
|
|
211
|
+
valid: (r, first) => (first ? validSpendHolder(r) : validSpendClaim(r)),
|
|
212
|
+
judgeDead: (r, first) => {
|
|
213
|
+
if (force !== undefined && first) {
|
|
214
|
+
if (r.token === force.token)
|
|
215
|
+
return;
|
|
216
|
+
throw new owned_lock_1.LockError('lock-busy', 'recover-live', 'The spend lock changed hands after it was judged; it is not recovered. Judge it again.');
|
|
217
|
+
}
|
|
218
|
+
const v = spendVerdict(r, me, platform);
|
|
219
|
+
if (v.dead)
|
|
220
|
+
return;
|
|
221
|
+
if (first)
|
|
222
|
+
throw new owned_lock_1.LockError('lock-busy', 'recover-live', busyMessage(r, v.reason));
|
|
223
|
+
// a successor claim: a recoverer that published it and may have died (W3)
|
|
224
|
+
const ageMs = (force?.now ?? Date.now()) - Date.parse(String(r.claimedAt));
|
|
225
|
+
if (force?.confirmClaims && ageMs > exports.CLAIM_STALE_MS)
|
|
226
|
+
return;
|
|
227
|
+
throw new owned_lock_1.LockError('lock-busy', 'recover-live', claimBusyMessage(r, v.reason, ageMs, force !== undefined));
|
|
228
|
+
},
|
|
229
|
+
claim: (recovers) => ({ kind: 'spend-recovery', token: (0, node_crypto_1.randomUUID)(), pid: process.pid, host: me.host, bootId: me.bootId, claimedAt: new Date().toISOString(), recovers }),
|
|
230
|
+
};
|
|
231
|
+
}
|
|
232
|
+
function busyMessage(h, reason) {
|
|
233
|
+
const why = {
|
|
234
|
+
host: 'it was taken on another host, or a host identity is unknown',
|
|
235
|
+
'boot-unknown': 'a boot identifier is unknown',
|
|
236
|
+
'case-1-off': 'it was taken on an earlier boot, and recovery across boots is off on this platform',
|
|
237
|
+
alive: 'its holder is running',
|
|
238
|
+
leak: 'this process holds it',
|
|
239
|
+
}[reason];
|
|
240
|
+
const route = reason === 'alive' || reason === 'leak' ? 'Retry when it is released.'
|
|
241
|
+
: 'If the holder is dead, the operator runs `holmes-kit lock recover spend --confirm-holder-dead` from a terminal.';
|
|
242
|
+
return `The spend lock is held by pid ${h.pid}; ${why}. ${route}`;
|
|
243
|
+
}
|
|
244
|
+
function claimBusyMessage(claim, reason, ageMs, operator) {
|
|
245
|
+
const age = `${Math.max(0, ageMs / 1000).toFixed(1)} s old`;
|
|
246
|
+
if (!operator)
|
|
247
|
+
return `A recovery claim by pid ${claim.pid} (${age}, ${reason}) blocks this recovery. If that recoverer is dead, the operator runs \`holmes-kit lock recover spend --confirm-holder-dead\` from a terminal once the claim is older than ${exports.CLAIM_STALE_MS / 1000} s.`;
|
|
248
|
+
return ageMs > exports.CLAIM_STALE_MS
|
|
249
|
+
? `A recovery claim by pid ${claim.pid} (${age}, ${reason}) blocks the recovery; if that recoverer is dead, run again with --confirm-holder-dead.`
|
|
250
|
+
: `A recovery claim by pid ${claim.pid} (${age}, ${reason}) blocks the recovery; a claim younger than ${exports.CLAIM_STALE_MS / 1000} s may still be working — wait, then run again with --confirm-holder-dead if it is dead.`;
|
|
251
|
+
}
|
|
252
|
+
/**
|
|
253
|
+
* The holder record read through a LockFs, or null when no lock is held or it cannot be read. The lock directory is
|
|
254
|
+
* reached through `directory`, so a symlinked path reads as no holder (A-SPEC-245.12).
|
|
255
|
+
*/
|
|
256
|
+
function holderThrough(lfs, root) {
|
|
257
|
+
try {
|
|
258
|
+
const bytes = lfs.readBytes(path.join(lfs.directory(exports.SPEND_LOCK_DIR), 'owner.json'));
|
|
259
|
+
const r = bytes ? JSON.parse(bytes.toString('utf8')) : null;
|
|
260
|
+
return validSpendHolder(r) ? r : null;
|
|
261
|
+
}
|
|
262
|
+
catch {
|
|
263
|
+
return null;
|
|
264
|
+
}
|
|
265
|
+
}
|
|
266
|
+
/** The spend lock's holder record, or null when no lock is held or it cannot be read. */
|
|
267
|
+
function spendLockHolder(root) { return holderThrough(plainLockFs(root), root); }
|
|
268
|
+
function recordLeak(lfs, root, holder) {
|
|
269
|
+
try {
|
|
270
|
+
lfs.appendLine(path.join(root, exports.SPEND_LEAKS_FILE), JSON.stringify({ at: new Date().toISOString(), pid: process.pid, acquiredAt: holder.acquiredAt, locator: exports.SPEND_LOCK_DIR }));
|
|
271
|
+
}
|
|
272
|
+
catch { /* the leak is reported by the throw either way */ }
|
|
273
|
+
}
|
|
274
|
+
const sleepSync = (ms) => { try {
|
|
275
|
+
Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
|
|
276
|
+
}
|
|
277
|
+
catch { /* retry without waiting */ } };
|
|
278
|
+
const unwrapAct = (f) => { try {
|
|
279
|
+
return f();
|
|
280
|
+
}
|
|
281
|
+
catch (e) {
|
|
282
|
+
throw e instanceof owned_lock_1.ActError ? e.inner : e;
|
|
283
|
+
} };
|
|
284
|
+
/**
|
|
285
|
+
* Take the workspace spend lock within `budgetMs`, recovering a certainly dead holder on the way. Busy past the budget
|
|
286
|
+
* is `lock-busy` — every pass that does not acquire checks the deadline and waits (R2); this module's own hold is
|
|
287
|
+
* `lock-leak`; a lock without a readable holder is `unknown-owner`.
|
|
288
|
+
*/
|
|
289
|
+
function acquireSpendLock(root, opts) {
|
|
290
|
+
const lfs = plainLockFs(root);
|
|
291
|
+
const me = identityOf(opts.identity);
|
|
292
|
+
const platform = opts.platform ?? process.platform;
|
|
293
|
+
const record = { kind: 'spend', token: (0, node_crypto_1.randomUUID)(), pid: process.pid, host: me.host, bootId: me.bootId,
|
|
294
|
+
acquiredAt: new Date().toISOString(), boundMs: opts.boundMs ?? 1000, nonces: (opts.nonces ?? []).filter((n) => FINGERPRINT.test(n)) };
|
|
295
|
+
const deadline = Date.now() + opts.budgetMs;
|
|
296
|
+
let lastBusy = `The spend lock (${exports.SPEND_LOCK_DIR}) is held.`;
|
|
297
|
+
for (;;) {
|
|
298
|
+
try {
|
|
299
|
+
const release = (0, owned_lock_1.acquireOwnedLock)(lfs, SPEND_LAYOUT, record);
|
|
300
|
+
held.add(record.token);
|
|
301
|
+
return { token: record.token, release: () => { try {
|
|
302
|
+
release();
|
|
303
|
+
}
|
|
304
|
+
finally {
|
|
305
|
+
held.delete(record.token);
|
|
306
|
+
} } };
|
|
307
|
+
}
|
|
308
|
+
catch (e) {
|
|
309
|
+
if (!(e instanceof owned_lock_1.LockError) || e.code !== 'lock-busy')
|
|
310
|
+
throw e;
|
|
311
|
+
}
|
|
312
|
+
// A-SPEC-245.11 (W7), 245.12: the holder is read through this lock's own filesystem and its checked directory
|
|
313
|
+
const dir = lfs.directory(exports.SPEND_LOCK_DIR);
|
|
314
|
+
let raw = undefined, vanished = false;
|
|
315
|
+
const bytes = lfs.readBytes(path.join(dir, 'owner.json'));
|
|
316
|
+
if (bytes === undefined) {
|
|
317
|
+
if (!lfs.stat(dir))
|
|
318
|
+
vanished = true; // released between the two reads
|
|
319
|
+
else
|
|
320
|
+
throw new owned_lock_1.LockError('unknown-owner', 'inspect', 'A spend lock without a holder record is preserved for inspection.');
|
|
321
|
+
}
|
|
322
|
+
else {
|
|
323
|
+
try {
|
|
324
|
+
raw = JSON.parse(bytes.toString('utf8'));
|
|
325
|
+
}
|
|
326
|
+
catch {
|
|
327
|
+
throw new owned_lock_1.LockError('unknown-owner', 'inspect', 'Malformed lock ownership must be preserved.');
|
|
328
|
+
}
|
|
329
|
+
}
|
|
330
|
+
if (!vanished) {
|
|
331
|
+
if (!validSpendHolder(raw))
|
|
332
|
+
throw new owned_lock_1.LockError('unknown-owner', 'inspect', 'Invalid lock ownership must be preserved.');
|
|
333
|
+
const v = spendVerdict(raw, me, platform);
|
|
334
|
+
if (!v.dead && v.reason === 'leak') {
|
|
335
|
+
recordLeak(lfs, root, raw);
|
|
336
|
+
throw new owned_lock_1.LockError('lock-leak', 'acquire', `This process already holds the spend lock (${exports.SPEND_LOCK_DIR}); a second acquisition is a leak.`);
|
|
337
|
+
}
|
|
338
|
+
if (v.dead) {
|
|
339
|
+
try {
|
|
340
|
+
unwrapAct(() => (0, owned_lock_1.recoverOwnedLock)(lfs, SPEND_LAYOUT, spendPolicy(me, platform), () => undefined, () => () => undefined));
|
|
341
|
+
}
|
|
342
|
+
catch (e) {
|
|
343
|
+
if (!(e instanceof owned_lock_1.LockError) || e.code !== 'lock-busy')
|
|
344
|
+
throw e;
|
|
345
|
+
lastBusy = e.message;
|
|
346
|
+
}
|
|
347
|
+
}
|
|
348
|
+
else
|
|
349
|
+
lastBusy = busyMessage(raw, v.reason);
|
|
350
|
+
}
|
|
351
|
+
if (Date.now() >= deadline)
|
|
352
|
+
throw new owned_lock_1.LockError('lock-busy', 'acquire', lastBusy);
|
|
353
|
+
sleepSync(Math.min(15, Math.max(1, deadline - Date.now())));
|
|
354
|
+
}
|
|
355
|
+
}
|
|
356
|
+
function withSpendLock(root, opts, act) {
|
|
357
|
+
const h = acquireSpendLock(root, opts);
|
|
358
|
+
try {
|
|
359
|
+
return act();
|
|
360
|
+
}
|
|
361
|
+
finally {
|
|
362
|
+
h.release();
|
|
363
|
+
}
|
|
364
|
+
}
|
|
365
|
+
/**
|
|
366
|
+
* The operator's recovery of the spend lock. The caller judges the harness first.
|
|
367
|
+
* - A dead holder is recovered.
|
|
368
|
+
* - Another host, a null identity, or another boot on darwin needs `confirmHolderDead`.
|
|
369
|
+
* - An answering holder (alive, EPERM, or a reused pid) needs `confirmHolderDead` and a hold longer than 4x its bound
|
|
370
|
+
* (M-b); this process's own hold is refused.
|
|
371
|
+
* - Only the generation judged is retired (R3): a lock that changed hands meanwhile is refused.
|
|
372
|
+
*/
|
|
373
|
+
function recoverSpendLockAsOperator(root, opts) {
|
|
374
|
+
const lfs = plainLockFs(root);
|
|
375
|
+
const holder = holderThrough(lfs, root);
|
|
376
|
+
if (!holder)
|
|
377
|
+
return lfs.stat(path.join(root, exports.SPEND_LOCK_DIR)) ? { refused: 'The spend lock has no readable holder record; it is preserved for inspection.' } : { nothing: true };
|
|
378
|
+
// A-SPEC-245.11, 245.12 (low): the caller recorded the holder it read — or that it read none (null); a lock that
|
|
379
|
+
// changed hands since is not this recovery's
|
|
380
|
+
if (opts.expectToken !== undefined && holder.token !== opts.expectToken)
|
|
381
|
+
return { refused: 'The spend lock changed hands after it was read; it is not recovered. Run again to judge the current holder.' };
|
|
382
|
+
const me = identityOf(opts.identity);
|
|
383
|
+
const platform = opts.platform ?? process.platform;
|
|
384
|
+
const v = spendVerdict(holder, me, platform);
|
|
385
|
+
let reason;
|
|
386
|
+
if (v.dead)
|
|
387
|
+
reason = `case ${v.case}: the holder is dead`;
|
|
388
|
+
else if (v.reason === 'leak')
|
|
389
|
+
return { refused: 'This process holds the spend lock; it is released when its act ends.' };
|
|
390
|
+
else if (v.reason === 'alive') {
|
|
391
|
+
const ageMs = (opts.now ?? Date.now)() - Date.parse(holder.acquiredAt);
|
|
392
|
+
if (!opts.confirmHolderDead)
|
|
393
|
+
return { refused: `The spend lock's holder, pid ${holder.pid}, answers on this host; if that pid is not the holder (reused) and the holder is dead, run again with --confirm-holder-dead once it has been held longer than 4x its bound.` };
|
|
394
|
+
if (!(ageMs > 4 * holder.boundMs))
|
|
395
|
+
return { refused: `The spend lock's holder, pid ${holder.pid}, answers and has been held ${(ageMs / 1000).toFixed(1)} s, not yet longer than 4x its bound of ${(holder.boundMs / 1000).toFixed(1)} s; it is not recovered.` };
|
|
396
|
+
reason = `confirmed dead by the operator: pid ${holder.pid} answers, held past 4x its bound`;
|
|
397
|
+
}
|
|
398
|
+
else {
|
|
399
|
+
if (!opts.confirmHolderDead)
|
|
400
|
+
return { refused: `The spend lock's holder, pid ${holder.pid}, cannot be judged dead here (${v.reason}); if it is dead, run again with --confirm-holder-dead.` };
|
|
401
|
+
reason = `confirmed dead by the operator (${v.reason})`;
|
|
402
|
+
}
|
|
403
|
+
const force = { token: holder.token, confirmClaims: opts.confirmHolderDead, now: (opts.now ?? Date.now)() };
|
|
404
|
+
try {
|
|
405
|
+
unwrapAct(() => (0, owned_lock_1.recoverOwnedLock)(lfs, SPEND_LAYOUT, spendPolicy(me, platform, force), () => undefined, () => () => undefined));
|
|
406
|
+
}
|
|
407
|
+
catch (e) {
|
|
408
|
+
if (e instanceof owned_lock_1.LockError && e.code === 'lock-busy')
|
|
409
|
+
return { refused: e.message };
|
|
410
|
+
throw e;
|
|
411
|
+
}
|
|
412
|
+
return { recovered: holder, reason };
|
|
413
|
+
}
|
|
@@ -40,7 +40,7 @@ export declare const FRESHNESS_LEASE_MS: number;
|
|
|
40
40
|
/** A failed detached worker is visible immediately but retries only after this bounded pause. */
|
|
41
41
|
export declare const FRESHNESS_RETRY_MS: number;
|
|
42
42
|
/**
|
|
43
|
-
* @implements A-SPEC-719.1 — the longest a live worker may hold its lease. Measured 2026-10-15: a
|
|
43
|
+
* @implements A-SPEC-719.1 — the longest a live worker may hold its lease. Measured 2026-10-15: a consumer workspace's refresh
|
|
44
44
|
* outlived the 2-minute lease, every later request spawned another child, and 13 ran at once (attempt 13, load
|
|
45
45
|
* 300–433). A live worker now keeps the lease up to this cap, and ends itself when it reaches it.
|
|
46
46
|
*/
|
|
@@ -64,7 +64,7 @@ exports.FRESHNESS_LEASE_MS = 2 * 60 * 1000;
|
|
|
64
64
|
/** A failed detached worker is visible immediately but retries only after this bounded pause. */
|
|
65
65
|
exports.FRESHNESS_RETRY_MS = 30 * 1000;
|
|
66
66
|
/**
|
|
67
|
-
* @implements A-SPEC-719.1 — the longest a live worker may hold its lease. Measured 2026-10-15: a
|
|
67
|
+
* @implements A-SPEC-719.1 — the longest a live worker may hold its lease. Measured 2026-10-15: a consumer workspace's refresh
|
|
68
68
|
* outlived the 2-minute lease, every later request spawned another child, and 13 ran at once (attempt 13, load
|
|
69
69
|
* 300–433). A live worker now keeps the lease up to this cap, and ends itself when it reaches it.
|
|
70
70
|
*/
|
|
@@ -42,6 +42,7 @@ const path = __importStar(require("node:path"));
|
|
|
42
42
|
const language_parser_1 = require("../cpg/language-parser");
|
|
43
43
|
const condition_hunk_resolution_1 = require("./condition-hunk-resolution");
|
|
44
44
|
const bounded_io_1 = require("../project/bounded-io");
|
|
45
|
+
const root_1 = require("../project/root");
|
|
45
46
|
const SAFE_COMMIT = /^[0-9a-f]{7,64}$/;
|
|
46
47
|
const sourceLanguage = (file) => {
|
|
47
48
|
if (/\.(ts|mts|cts)$/.test(file))
|
|
@@ -51,8 +52,9 @@ const sourceLanguage = (file) => {
|
|
|
51
52
|
return null;
|
|
52
53
|
};
|
|
53
54
|
const safePath = (file) => file !== '' && !path.isAbsolute(file) && !file.split(/[\\/]/).includes('..');
|
|
55
|
+
// @implements A-SPEC-792.39 — the shared inert git environment; the diff runs no external diff or textconv.
|
|
54
56
|
const git = (root, args) => (0, node_child_process_1.execFileSync)('git', ['-C', root, ...args], { timeout: bounded_io_1.GIT_LONG_TIMEOUT_MS,
|
|
55
|
-
encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 16 * 1024 * 1024,
|
|
57
|
+
encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 16 * 1024 * 1024, env: (0, bounded_io_1.gitEnv)((0, root_1.cleanSubprocessEnv)()),
|
|
56
58
|
});
|
|
57
59
|
/** Replays caller-selected commits only; it never checks out, writes a cache, or inspects another repository. */
|
|
58
60
|
async function replayConditionHunks(input) {
|
|
@@ -74,7 +76,7 @@ async function replayConditionHunks(input) {
|
|
|
74
76
|
const baselineStart = Date.now();
|
|
75
77
|
try {
|
|
76
78
|
source = git(input.root, ['show', `${replayCase.commit}:${file}`]);
|
|
77
|
-
diff = git(input.root, ['diff', '--unified=0', `${replayCase.commit}^`, replayCase.commit, '--', file]);
|
|
79
|
+
diff = git(input.root, ['diff', '--no-ext-diff', '--no-textconv', '--unified=0', `${replayCase.commit}^`, replayCase.commit, '--', file]);
|
|
78
80
|
}
|
|
79
81
|
catch {
|
|
80
82
|
continue;
|
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
* corpora, with the highest band the worst in each:
|
|
8
8
|
*
|
|
9
9
|
* holmes conf 0.25 → recall 0.751 conf 0.70 → 0.306 conf 0.85 → 0.542 r = −0.309
|
|
10
|
-
*
|
|
10
|
+
* consumer conf 0.25 → recall 0.669 conf 0.65 → 0.646 conf 0.85 → 0.000 r = −0.212
|
|
11
11
|
*
|
|
12
12
|
* A caller who trusts this field trusts the wrong answers most. On the second corpus the two cases
|
|
13
13
|
* the harness was surest about returned nothing correct at all.
|
|
@@ -14,7 +14,7 @@ exports.CONFIDENCE_BY_CORPUS = [
|
|
|
14
14
|
],
|
|
15
15
|
},
|
|
16
16
|
{
|
|
17
|
-
corpus: '
|
|
17
|
+
corpus: 'consumer clean-30', cases: 30, correlationWithRecall: -0.212,
|
|
18
18
|
bands: [
|
|
19
19
|
{ confidence: 0.25, n: 12, meanRecall: 0.669, meanPrecision: 0.175 },
|
|
20
20
|
{ confidence: 0.65, n: 16, meanRecall: 0.646, meanPrecision: 0.119 },
|
|
@@ -43,7 +43,7 @@ function mentionNames(headPath, headSymbols) {
|
|
|
43
43
|
// @implements A-SPEC-490 — the excerpt fix S-507 demanded: a 400-char excerpt of a Google-style
|
|
44
44
|
// file is ALL license header, and a judge reading it learns nothing. Only blocks that actually
|
|
45
45
|
// talk about licensing are dropped; an informative leading comment (a Korean docstring) is
|
|
46
|
-
// exactly what made the
|
|
46
|
+
// exactly what made the consumer corpus's judgments strong and must survive.
|
|
47
47
|
const LICENSE_RE = /license|copyright|spdx/i;
|
|
48
48
|
function skipLicenseHeader(text) {
|
|
49
49
|
let rest = text;
|
|
@@ -37,7 +37,7 @@ export declare function hopContribution(slice: HopSlice): number;
|
|
|
37
37
|
/** Case-weighted mean contribution — the single number, with its smallness visible. */
|
|
38
38
|
export declare function weightedHopContribution(slices: readonly HopSlice[]): number;
|
|
39
39
|
/**
|
|
40
|
-
* Why the
|
|
40
|
+
* Why the consumer corpus's `union recall` floor fell from 0.8813 to 0.8508 when the hop went in.
|
|
41
41
|
*
|
|
42
42
|
* It was recorded as an open question, with a hypothesis: the hop pushes lexically-matched files out
|
|
43
43
|
* of the top ten, which shrinks the symbols the call closure is seeded from, so `impactedFiles`
|
|
@@ -66,7 +66,7 @@ export interface UnionDrop {
|
|
|
66
66
|
impactRecallWithHop: number;
|
|
67
67
|
impactRecallWithoutHop: number;
|
|
68
68
|
}
|
|
69
|
-
/** Measured 2026-08-29 on `casesFor(
|
|
69
|
+
/** Measured 2026-08-29 on `casesFor(CONSUMER_CORPUS, 30)` — the set the floors are pinned on. */
|
|
70
70
|
export declare const UNION_DROP: UnionDrop;
|
|
71
71
|
/** Net answers the hop put into the union, counted as files rather than averaged over cases. */
|
|
72
72
|
export declare function unionFileDelta(d: UnionDrop): number;
|
|
@@ -74,12 +74,12 @@ export declare function unionFileDelta(d: UnionDrop): number;
|
|
|
74
74
|
* What the rank fusion (A-SPEC-405) is worth, measured the same way the hop was.
|
|
75
75
|
*
|
|
76
76
|
* A-SPEC-405 was approved under a criterion of its own writing — "no existing figure falls on either
|
|
77
|
-
* clean slice" — and then adopted with
|
|
77
|
+
* clean slice" — and then adopted with consumer-corpus Top-10 precision down from 0.145 to 0.135. I recorded
|
|
78
78
|
* the violation and left the revert decision open. This is the number that decision needs, taken
|
|
79
79
|
* through the product path rather than the arm the original used.
|
|
80
80
|
*
|
|
81
81
|
* The violation is REAL and is confirmed here, and a second cost the original never measured shows
|
|
82
|
-
* up with it: on
|
|
82
|
+
* up with it: on the consumer corpus the fusion also leaves two fewer answers inside the forty the caller sees.
|
|
83
83
|
*
|
|
84
84
|
* It is kept anyway, and the trade is stated rather than smoothed: +0.172 and +0.069 of Top-5 recall
|
|
85
85
|
* against −0.012 of precision and two answers. Nobody should read this as the criterion being met.
|
|
@@ -14,14 +14,14 @@ exports.HOP_ABLATION = [
|
|
|
14
14
|
withoutHop: { top1: 0.300, top5Recall: 0.493, top10Recall: 0.633, top10Precision: 0.127, truthInsideExposed: 45 },
|
|
15
15
|
},
|
|
16
16
|
{
|
|
17
|
-
slice: '
|
|
17
|
+
slice: 'consumer 0-29',
|
|
18
18
|
cases: 30,
|
|
19
19
|
withHop: { top1: 0.533, top5Recall: 0.528, top10Recall: 0.612, top10Precision: 0.133, truthInsideExposed: 52 },
|
|
20
20
|
withoutHop: { top1: 0.533, top5Recall: 0.488, top10Recall: 0.612, top10Precision: 0.135, truthInsideExposed: 53 },
|
|
21
21
|
},
|
|
22
22
|
{
|
|
23
23
|
// The slice the adoption never saw. It is the one that disagrees.
|
|
24
|
-
slice: '
|
|
24
|
+
slice: 'consumer 32-63',
|
|
25
25
|
cases: 32,
|
|
26
26
|
withHop: { top1: 0.469, top5Recall: 0.463, top10Recall: 0.611, top10Precision: 0.204, truthInsideExposed: 87 },
|
|
27
27
|
withoutHop: { top1: 0.469, top5Recall: 0.510, top10Recall: 0.627, top10Precision: 0.204, truthInsideExposed: 88 },
|
|
@@ -38,9 +38,9 @@ function weightedHopContribution(slices) {
|
|
|
38
38
|
return 0;
|
|
39
39
|
return slices.reduce((a, s) => a + hopContribution(s) * s.cases, 0) / cases;
|
|
40
40
|
}
|
|
41
|
-
/** Measured 2026-08-29 on `casesFor(
|
|
41
|
+
/** Measured 2026-08-29 on `casesFor(CONSUMER_CORPUS, 30)` — the set the floors are pinned on. */
|
|
42
42
|
exports.UNION_DROP = {
|
|
43
|
-
slice: '
|
|
43
|
+
slice: 'consumer newest-30',
|
|
44
44
|
lostFiles: 2,
|
|
45
45
|
lostFromRanked: 2,
|
|
46
46
|
lostFromImpacted: 0,
|
|
@@ -64,7 +64,7 @@ exports.FUSION_ABLATION = [
|
|
|
64
64
|
withoutFusion: { top1: 0.300, top5Recall: 0.382, top10Recall: 0.604, top10Precision: 0.117, truthInsideExposed: 44 },
|
|
65
65
|
},
|
|
66
66
|
{
|
|
67
|
-
slice: '
|
|
67
|
+
slice: 'consumer clean-30',
|
|
68
68
|
cases: 30,
|
|
69
69
|
withFusion: { top1: 0.533, top5Recall: 0.528, top10Recall: 0.612, top10Precision: 0.133, truthInsideExposed: 52 },
|
|
70
70
|
withoutFusion: { top1: 0.533, top5Recall: 0.459, top10Recall: 0.612, top10Precision: 0.145, truthInsideExposed: 54 },
|