@holmes-lab/holmes-kit 0.39.0 → 0.40.1
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 +578 -6
- package/README.md +120 -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 +226 -442
- package/dist/holmes/cli/init.js +33 -0
- package/dist/holmes/cli/interactive-prompt.d.ts +39 -2
- package/dist/holmes/cli/interactive-prompt.js +98 -16
- 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 +19 -0
- package/dist/holmes/config/config.js +18 -3
- 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 +12 -0
- package/dist/holmes/governance/autonomy.js +51 -15
- 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.d.ts +2 -0
- package/dist/holmes/governance/push-gate-runner.js +50 -9
- package/dist/holmes/governance/push-gate.d.ts +13 -2
- package/dist/holmes/governance/push-gate.js +106 -14
- 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/advisory-line.d.ts +102 -0
- package/dist/holmes/guardrail/advisory-line.js +718 -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 +7 -0
- package/dist/holmes/guardrail/impact-gate.js +33 -6
- 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 +116 -1
- package/dist/holmes/hooks/pre-tool-use.js +1176 -170
- package/dist/holmes/hooks/rtm-refresh-child.d.ts +1 -1
- package/dist/holmes/hooks/rtm-refresh-child.js +1 -1
- package/dist/holmes/hooks/session-start.js +17 -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/maintenance-analysis.d.ts +13 -0
- package/dist/holmes/mcp/handlers/maintenance-analysis.js +59 -2
- 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 +471 -4
- package/dist/holmes/mcp/handlers/test-execution.js +199 -21
- package/dist/holmes/mcp/handlers/workspace-queries.d.ts +2 -2
- package/dist/holmes/mcp/handlers.d.ts +557 -82
- package/dist/holmes/mcp/handlers.js +74 -23
- 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 +6 -1
- package/dist/holmes/mcp/maintenance-analyze.js +13 -11
- package/dist/holmes/mcp/maintenance-evidence.d.ts +9 -0
- package/dist/holmes/mcp/maintenance-evidence.js +35 -3
- 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 +42 -9
- package/dist/holmes/project/act-root.d.ts +19 -0
- package/dist/holmes/project/act-root.js +100 -0
- package/dist/holmes/project/baseline.d.ts +15 -2
- package/dist/holmes/project/baseline.js +14 -8
- 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 +51 -2
- package/dist/holmes/project/bounded-io.js +140 -6
- package/dist/holmes/project/change-source.d.ts +4 -0
- package/dist/holmes/project/change-source.js +14 -6
- 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 +29 -8
- 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/evidence-mode.d.ts +21 -0
- package/dist/holmes/review/evidence-mode.js +33 -0
- package/dist/holmes/review/head-worktree.d.ts +55 -0
- package/dist/holmes/review/head-worktree.js +329 -0
- package/dist/holmes/review/hop-ablation.d.ts +4 -4
- package/dist/holmes/review/hop-ablation.js +5 -5
- package/dist/holmes/review/mrp.js +13 -3
- 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/run-provenance.d.ts +45 -0
- package/dist/holmes/review/run-provenance.js +314 -0
- package/dist/holmes/review/semantic-arm.d.ts +3 -3
- package/dist/holmes/review/semantic-arm.js +3 -3
- package/dist/holmes/review/test-evidence.d.ts +174 -0
- package/dist/holmes/review/test-evidence.js +330 -2
- package/dist/holmes/review/test-outcomes.js +3 -1
- package/dist/holmes/review/test-reports.d.ts +94 -0
- package/dist/holmes/review/test-reports.js +382 -0
- package/dist/holmes/review/test-runner.d.ts +180 -58
- package/dist/holmes/review/test-runner.js +560 -324
- package/dist/holmes/review/test-selection-breadth.js +2 -2
- package/dist/holmes/review/test-units.d.ts +159 -0
- package/dist/holmes/review/test-units.js +814 -0
- 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 +47 -34
- 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;
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The one place the full-run tokens live (A-SPEC-128.4 §5): the mode a full run records, the provenance input that says
|
|
3
|
+
* a baseline was verified by such a run, and the call a refusal names. The write side, the predicate, the trust check, the
|
|
4
|
+
* push gate and the merge-ready package all read these, so the spelling cannot drift between them.
|
|
5
|
+
*/
|
|
6
|
+
export declare const FULL_MODE: "full";
|
|
7
|
+
/** @implements A-SPEC-128.5 — the mode a full record and a full anchor carry, as a type. */
|
|
8
|
+
export type FullMode = typeof FULL_MODE;
|
|
9
|
+
/** The provenance input a baseline anchor carries for the mode of the run that verified it. */
|
|
10
|
+
export declare function modeAnchor(mode: FullMode): string;
|
|
11
|
+
/** @implements A-SPEC-128.4 — the one call that clears a refusal: the refusal names it, and running it reaches allow. */
|
|
12
|
+
export declare const FULL_RUN_CALL = "test_run({root, full: true})";
|
|
13
|
+
/** @implements A-SPEC-128.5 — the default budget of a full run, and the ceiling a next call may ask for. */
|
|
14
|
+
export declare const FULL_RUN_DEFAULT_MINUTES = 120;
|
|
15
|
+
export declare const RUN_MINUTES_CEILING = 180;
|
|
16
|
+
/**
|
|
17
|
+
* @implements A-SPEC-128.8 — the one builder of what follows a stopped full run: the call with a doubled budget (up to the
|
|
18
|
+
* ceiling), keeping the worker count, or at the ceiling the sentence that says so. The test_run answer's `nextCall` and the
|
|
19
|
+
* push gate's stopped-attempt refusal both read it, so the two cannot drift (A L1, B M1).
|
|
20
|
+
*/
|
|
21
|
+
export declare function nextFullCall(timeoutMinutes: number, workers?: number | null): string;
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.RUN_MINUTES_CEILING = exports.FULL_RUN_DEFAULT_MINUTES = exports.FULL_RUN_CALL = exports.FULL_MODE = void 0;
|
|
4
|
+
exports.modeAnchor = modeAnchor;
|
|
5
|
+
exports.nextFullCall = nextFullCall;
|
|
6
|
+
// @implements A-SPEC-128.4, A-SPEC-128.5, A-SPEC-128.8, A-SPEC-128.9
|
|
7
|
+
/**
|
|
8
|
+
* The one place the full-run tokens live (A-SPEC-128.4 §5): the mode a full run records, the provenance input that says
|
|
9
|
+
* a baseline was verified by such a run, and the call a refusal names. The write side, the predicate, the trust check, the
|
|
10
|
+
* push gate and the merge-ready package all read these, so the spelling cannot drift between them.
|
|
11
|
+
*/
|
|
12
|
+
exports.FULL_MODE = 'full';
|
|
13
|
+
/** The provenance input a baseline anchor carries for the mode of the run that verified it. */
|
|
14
|
+
function modeAnchor(mode) {
|
|
15
|
+
return `mode:${mode}`;
|
|
16
|
+
}
|
|
17
|
+
/** @implements A-SPEC-128.4 — the one call that clears a refusal: the refusal names it, and running it reaches allow. */
|
|
18
|
+
exports.FULL_RUN_CALL = 'test_run({root, full: true})';
|
|
19
|
+
/** @implements A-SPEC-128.5 — the default budget of a full run, and the ceiling a next call may ask for. */
|
|
20
|
+
exports.FULL_RUN_DEFAULT_MINUTES = 120;
|
|
21
|
+
exports.RUN_MINUTES_CEILING = 180;
|
|
22
|
+
/**
|
|
23
|
+
* @implements A-SPEC-128.8 — the one builder of what follows a stopped full run: the call with a doubled budget (up to the
|
|
24
|
+
* ceiling), keeping the worker count, or at the ceiling the sentence that says so. The test_run answer's `nextCall` and the
|
|
25
|
+
* push gate's stopped-attempt refusal both read it, so the two cannot drift (A L1, B M1).
|
|
26
|
+
*/
|
|
27
|
+
function nextFullCall(timeoutMinutes, workers) {
|
|
28
|
+
if (timeoutMinutes >= exports.RUN_MINUTES_CEILING) {
|
|
29
|
+
// @implements A-SPEC-128.9 — E4: no exclusion is suggested (following one hid a red suite); split it or ask the owner
|
|
30
|
+
return `budget ceiling reached (${exports.RUN_MINUTES_CEILING} minutes) — the suite does not finish within it; split the suite or ask the owner how this repository is verified`;
|
|
31
|
+
}
|
|
32
|
+
return `test_run({root, full: true, timeoutMinutes: ${Math.min(exports.RUN_MINUTES_CEILING, timeoutMinutes * 2)}${typeof workers === 'number' ? `, workers: ${workers}` : ''}})`;
|
|
33
|
+
}
|