@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,85 @@
|
|
|
1
|
+
import { LockLayout } from './owned-lock';
|
|
2
|
+
import { SpendIdentity } from './spend-lock';
|
|
3
|
+
export declare const REQUEST_LOCKS_DIR = ".ax/state/request-locks";
|
|
4
|
+
export declare const REQUEST_CLAIMS_DIR = ".ax/state/request-lock-claims";
|
|
5
|
+
export declare const REQUEST_RETIRED_DIR = ".ax/state/request-retired-locks";
|
|
6
|
+
export declare const REQUEST_LEAKS_FILE = ".ax/state/request-lock-leaks.jsonl";
|
|
7
|
+
export declare function requestLockLayout(id: string): LockLayout;
|
|
8
|
+
/** A holder whose liveness cannot be judged is recovered once held longer than this many times its bound. */
|
|
9
|
+
export declare const AGE_FACTOR = 4;
|
|
10
|
+
/** A claim of a claimant whose liveness cannot be judged is recovered once older than this. */
|
|
11
|
+
export declare const CLAIM_STALE_MS = 60000;
|
|
12
|
+
/** The holder's lock was recovered, replaced or claimed by a successor: it must write nothing. */
|
|
13
|
+
export declare class FenceLost extends Error {
|
|
14
|
+
readonly holmesRefusal = true;
|
|
15
|
+
constructor(message: string);
|
|
16
|
+
}
|
|
17
|
+
/** A publish found its name taken; the existing file is untouched. */
|
|
18
|
+
export declare class PublishConflict extends Error {
|
|
19
|
+
readonly holmesRefusal = true;
|
|
20
|
+
constructor(message: string);
|
|
21
|
+
}
|
|
22
|
+
/** The file system refused the hard link a publish needs; nothing is copied in its place. */
|
|
23
|
+
export declare class PublishUnsupported extends Error {
|
|
24
|
+
readonly holmesRefusal = true;
|
|
25
|
+
constructor(message: string);
|
|
26
|
+
}
|
|
27
|
+
export interface Fence {
|
|
28
|
+
/** Throws FenceLost unless this holder still owns the lock. */
|
|
29
|
+
check(): void;
|
|
30
|
+
/** check(), then `fn`. */
|
|
31
|
+
write<T>(fn: () => T): T;
|
|
32
|
+
/** check(), then publish `bytes` at `dirRel/name` without replacing an existing file. */
|
|
33
|
+
publish(dirRel: string, name: string, bytes: string): void;
|
|
34
|
+
}
|
|
35
|
+
export interface RequestLockOptions {
|
|
36
|
+
budgetMs: number;
|
|
37
|
+
/** The step bound of the work held under the lock. */
|
|
38
|
+
boundMs?: number;
|
|
39
|
+
identity?: SpendIdentity;
|
|
40
|
+
platform?: NodeJS.Platform;
|
|
41
|
+
/** Liveness of another pid; injected by tests. */
|
|
42
|
+
probe?: (pid: number) => 'dead' | 'alive';
|
|
43
|
+
}
|
|
44
|
+
export interface RequestHolder {
|
|
45
|
+
kind: 'request';
|
|
46
|
+
token: string;
|
|
47
|
+
pid: number;
|
|
48
|
+
host: string | null;
|
|
49
|
+
bootId: string | null;
|
|
50
|
+
acquiredAt: string;
|
|
51
|
+
boundMs: number;
|
|
52
|
+
id: string;
|
|
53
|
+
}
|
|
54
|
+
/**
|
|
55
|
+
* Take the request lock of `id` within `opts.budgetMs`, run `act` with the fence, and release. Busy past the budget is
|
|
56
|
+
* `lock-busy`; this process's own hold of the id is `lock-leak`; an id outside `req-<12 hex>`, or a root without `.ax`,
|
|
57
|
+
* is refused before any file is touched. A release that fails after `act` returned does not hide the result; when
|
|
58
|
+
* `act` threw, its error is the one thrown.
|
|
59
|
+
*/
|
|
60
|
+
export declare function withRequestLock<T>(root: string, id: string, opts: RequestLockOptions, act: (fence: Fence) => T): T;
|
|
61
|
+
/** The held request locks with a readable holder, for doctor. */
|
|
62
|
+
export declare function requestLockHolders(root: string): RequestHolder[];
|
|
63
|
+
export type RequestOperatorRecovery = {
|
|
64
|
+
recovered: RequestHolder;
|
|
65
|
+
reason: string;
|
|
66
|
+
} | {
|
|
67
|
+
refused: string;
|
|
68
|
+
} | {
|
|
69
|
+
nothing: true;
|
|
70
|
+
};
|
|
71
|
+
/**
|
|
72
|
+
* The operator's recovery of one request lock, by `recoverSpendLockAsOperator`'s rules: a dead holder is recovered;
|
|
73
|
+
* an unjudgeable one needs `confirmHolderDead`; an answering one needs it and a hold longer than 4x its bound; this
|
|
74
|
+
* process's own hold is refused; a lock that changed hands since it was read is refused.
|
|
75
|
+
*/
|
|
76
|
+
export declare function recoverRequestLockAsOperator(root: string, id: string, opts: {
|
|
77
|
+
confirmHolderDead: boolean;
|
|
78
|
+
expectToken?: string | null;
|
|
79
|
+
identity?: SpendIdentity;
|
|
80
|
+
platform?: NodeJS.Platform;
|
|
81
|
+
now?: () => number;
|
|
82
|
+
probe?: (pid: number) => 'dead' | 'alive';
|
|
83
|
+
}): RequestOperatorRecovery;
|
|
84
|
+
/** 1 + the largest `lockEpoch` among the events of `id` that is a safe integer in [0, 2^32), or 1 when there is none. */
|
|
85
|
+
export declare function nextLockEpoch(events: ReadonlyArray<Record<string, unknown>>, id: string): number;
|
|
@@ -0,0 +1,459 @@
|
|
|
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.PublishUnsupported = exports.PublishConflict = exports.FenceLost = exports.CLAIM_STALE_MS = exports.AGE_FACTOR = exports.REQUEST_LEAKS_FILE = exports.REQUEST_RETIRED_DIR = exports.REQUEST_CLAIMS_DIR = exports.REQUEST_LOCKS_DIR = void 0;
|
|
37
|
+
exports.requestLockLayout = requestLockLayout;
|
|
38
|
+
exports.withRequestLock = withRequestLock;
|
|
39
|
+
exports.requestLockHolders = requestLockHolders;
|
|
40
|
+
exports.recoverRequestLockAsOperator = recoverRequestLockAsOperator;
|
|
41
|
+
exports.nextLockEpoch = nextLockEpoch;
|
|
42
|
+
// @implements A-SPEC-794.2, A-SPEC-794.6
|
|
43
|
+
/**
|
|
44
|
+
* The request lock (design draft 4 §4.1, §4.4): one holder per approval request id, on the owned-lock protocol, and
|
|
45
|
+
* the fence a holder checks before every queue append and grant publish.
|
|
46
|
+
*
|
|
47
|
+
* - The lock lives at `.ax/state/request-locks/<id>`; its successor claims and retired generations sit beside the
|
|
48
|
+
* other locks' under `.ax/state`. The id is `req-<12 hex>` or nothing is touched.
|
|
49
|
+
* - Lock order (A-SPEC-245.7 extended by A-SPEC-794.6): entity-store → request → spend → chain. A spend holder never
|
|
50
|
+
* takes this lock; request-lock-order.test.ts holds that no spend-context module reaches it.
|
|
51
|
+
* - Acquisition never waits past its budget plus one pass. A certainly dead holder (spendVerdict's rules, the probe
|
|
52
|
+
* injectable) is recovered and the lock taken fresh. A holder whose liveness cannot be judged (another or an unknown
|
|
53
|
+
* host, an unknown boot, an earlier boot on darwin) is recovered once held longer than 4x its bound; a holder judged
|
|
54
|
+
* alive is never recovered by age; this process asking again for an id it holds is a leak. Past that, the operator
|
|
55
|
+
* runs `holmes-kit lock recover request <id>`.
|
|
56
|
+
* - The fence holds while the owner record carries this holder's token, the lock directory keeps the inode it had at
|
|
57
|
+
* acquisition, and no successor claim names the token; it reads through the LockFs, so a symlinked path is lost.
|
|
58
|
+
* - A publish links a private temp file to its name, so it never replaces a file.
|
|
59
|
+
*
|
|
60
|
+
* Limits: the fence narrows the window between check and write and does not close it — the no-clobber publish and
|
|
61
|
+
* lockEpoch carry the rest (tamper evidence, not prevention). Age-based recovery is a judgement, not a proof. A reused
|
|
62
|
+
* pid reads as alive. The wait is Atomics.wait, which blocks the event loop: an MCP path must keep its budget short.
|
|
63
|
+
*/
|
|
64
|
+
const fs = __importStar(require("node:fs"));
|
|
65
|
+
const path = __importStar(require("node:path"));
|
|
66
|
+
const node_crypto_1 = require("node:crypto");
|
|
67
|
+
const owned_lock_1 = require("./owned-lock");
|
|
68
|
+
const spend_lock_1 = require("./spend-lock");
|
|
69
|
+
const plain_lock_fs_1 = require("./plain-lock-fs");
|
|
70
|
+
exports.REQUEST_LOCKS_DIR = '.ax/state/request-locks';
|
|
71
|
+
exports.REQUEST_CLAIMS_DIR = '.ax/state/request-lock-claims';
|
|
72
|
+
exports.REQUEST_RETIRED_DIR = '.ax/state/request-retired-locks';
|
|
73
|
+
exports.REQUEST_LEAKS_FILE = '.ax/state/request-lock-leaks.jsonl';
|
|
74
|
+
function requestLockLayout(id) { return { parent: exports.REQUEST_LOCKS_DIR, name: id, claims: exports.REQUEST_CLAIMS_DIR, retired: exports.REQUEST_RETIRED_DIR }; }
|
|
75
|
+
const REQUEST_ID = /^req-[0-9a-f]{12}$/;
|
|
76
|
+
const TRANSIENT = /^\.lock-[0-9a-f-]{36}\.tmp$/;
|
|
77
|
+
/** A holder whose liveness cannot be judged is recovered once held longer than this many times its bound. */
|
|
78
|
+
exports.AGE_FACTOR = 4;
|
|
79
|
+
/** A claim of a claimant whose liveness cannot be judged is recovered once older than this. */
|
|
80
|
+
exports.CLAIM_STALE_MS = 60_000;
|
|
81
|
+
const UNJUDGEABLE = new Set(['host', 'boot-unknown', 'case-1-off']);
|
|
82
|
+
const EPOCH_LIMIT = 2 ** 32;
|
|
83
|
+
/** The holder's lock was recovered, replaced or claimed by a successor: it must write nothing. */
|
|
84
|
+
class FenceLost extends Error {
|
|
85
|
+
holmesRefusal = true;
|
|
86
|
+
constructor(message) { super(message); this.name = 'FenceLost'; }
|
|
87
|
+
}
|
|
88
|
+
exports.FenceLost = FenceLost;
|
|
89
|
+
/** A publish found its name taken; the existing file is untouched. */
|
|
90
|
+
class PublishConflict extends Error {
|
|
91
|
+
holmesRefusal = true;
|
|
92
|
+
constructor(message) { super(message); this.name = 'PublishConflict'; }
|
|
93
|
+
}
|
|
94
|
+
exports.PublishConflict = PublishConflict;
|
|
95
|
+
/** The file system refused the hard link a publish needs; nothing is copied in its place. */
|
|
96
|
+
class PublishUnsupported extends Error {
|
|
97
|
+
holmesRefusal = true;
|
|
98
|
+
constructor(message) { super(message); this.name = 'PublishUnsupported'; }
|
|
99
|
+
}
|
|
100
|
+
exports.PublishUnsupported = PublishUnsupported;
|
|
101
|
+
const lockFsOf = (root) => (0, plain_lock_fs_1.plainLockFs)(root, (name) => TRANSIENT.test(name));
|
|
102
|
+
/** Tokens of request locks this copy of the module holds. */
|
|
103
|
+
const held = new Set();
|
|
104
|
+
function identityOf(given) {
|
|
105
|
+
if (given)
|
|
106
|
+
return given;
|
|
107
|
+
const m = require('./machine-identity');
|
|
108
|
+
return { host: m.hostId(), bootId: m.bootId() };
|
|
109
|
+
}
|
|
110
|
+
function validHolder(r, id) {
|
|
111
|
+
if (typeof r !== 'object' || r === null)
|
|
112
|
+
return false;
|
|
113
|
+
const o = r;
|
|
114
|
+
const keys = ['kind', 'token', 'pid', 'host', 'bootId', 'acquiredAt', 'boundMs', 'id'];
|
|
115
|
+
return Object.keys(o).every((k) => keys.includes(k)) && o.kind === 'request' && (0, owned_lock_1.isLockToken)(o.token)
|
|
116
|
+
&& Number.isSafeInteger(o.pid) && o.pid > 0
|
|
117
|
+
&& (o.host === null || typeof o.host === 'string') && (o.bootId === null || typeof o.bootId === 'string')
|
|
118
|
+
&& typeof o.acquiredAt === 'string' && typeof o.boundMs === 'number' && o.boundMs > 0 && o.id === id;
|
|
119
|
+
}
|
|
120
|
+
function validClaim(r) {
|
|
121
|
+
if (typeof r !== 'object' || r === null)
|
|
122
|
+
return false;
|
|
123
|
+
const o = r;
|
|
124
|
+
const keys = ['kind', 'token', 'pid', 'host', 'bootId', 'claimedAt', 'recovers', 'released'];
|
|
125
|
+
return Object.keys(o).every((k) => keys.includes(k)) && o.kind === 'request-recovery' && (0, owned_lock_1.isLockToken)(o.token)
|
|
126
|
+
&& Number.isSafeInteger(o.pid) && o.pid > 0
|
|
127
|
+
&& (o.host === null || typeof o.host === 'string') && (o.bootId === null || typeof o.bootId === 'string')
|
|
128
|
+
&& typeof o.claimedAt === 'string' && (0, owned_lock_1.isLockToken)(o.recovers) && (o.released === undefined || o.released === true);
|
|
129
|
+
}
|
|
130
|
+
/** This process's pid is never dead: its own token is a leak, any other is alive. Otherwise spendVerdict's rules. */
|
|
131
|
+
function verdictOf(r, me, platform, probe) {
|
|
132
|
+
if (r.pid === process.pid)
|
|
133
|
+
return { dead: false, reason: held.has(r.token) ? 'leak' : 'alive' };
|
|
134
|
+
const v = (0, spend_lock_1.spendVerdict)(r, me, platform, probe);
|
|
135
|
+
return v.dead ? { dead: true } : { dead: false, reason: v.reason };
|
|
136
|
+
}
|
|
137
|
+
const ageOf = (iso, now) => now - Date.parse(String(iso));
|
|
138
|
+
/** An unjudgeable holder held longer than AGE_FACTOR x its bound. */
|
|
139
|
+
const pastBound = (h, reason, now) => UNJUDGEABLE.has(reason) && ageOf(h.acquiredAt, now) > exports.AGE_FACTOR * h.boundMs;
|
|
140
|
+
function busyMessage(id, h, reason) {
|
|
141
|
+
const route = `if the holder is dead, the operator runs \`holmes-kit lock recover request ${id} --confirm-holder-dead\` from a terminal`;
|
|
142
|
+
return reason === 'alive' || reason === 'leak'
|
|
143
|
+
? `The request lock of ${id} is held by pid ${h.pid}, which is running. Retry when it is released; ${route} once it is held longer than ${exports.AGE_FACTOR}x its bound.`
|
|
144
|
+
: `The request lock of ${id} is held by pid ${h.pid}, whose liveness cannot be judged here (${reason}). It is recovered automatically once held longer than ${exports.AGE_FACTOR}x its bound of ${(h.boundMs / 1000).toFixed(1)} s; sooner, ${route}.`;
|
|
145
|
+
}
|
|
146
|
+
function policyOf(id, me, platform, probe, force) {
|
|
147
|
+
return {
|
|
148
|
+
kind: 'request',
|
|
149
|
+
valid: (r, first) => (first ? validHolder(r, id) : validClaim(r)),
|
|
150
|
+
judgeDead: (r, first) => {
|
|
151
|
+
if (force !== undefined && first) {
|
|
152
|
+
if (r.token === force.token)
|
|
153
|
+
return;
|
|
154
|
+
throw new owned_lock_1.LockError('lock-busy', 'recover-live', `The request lock of ${id} changed hands after it was judged; it is not recovered. Judge it again.`);
|
|
155
|
+
}
|
|
156
|
+
const now = force?.now ?? Date.now();
|
|
157
|
+
const v = verdictOf(r, me, platform, probe);
|
|
158
|
+
if (v.dead)
|
|
159
|
+
return;
|
|
160
|
+
if (first) {
|
|
161
|
+
if (pastBound(r, v.reason, now))
|
|
162
|
+
return;
|
|
163
|
+
throw new owned_lock_1.LockError('lock-busy', 'recover-live', busyMessage(id, r, v.reason));
|
|
164
|
+
}
|
|
165
|
+
// a successor claim: a recoverer that published it and may have died
|
|
166
|
+
const age = ageOf(r.claimedAt, now);
|
|
167
|
+
if ((UNJUDGEABLE.has(v.reason) || force?.confirmClaims) && age > exports.CLAIM_STALE_MS)
|
|
168
|
+
return;
|
|
169
|
+
throw new owned_lock_1.LockError('lock-busy', 'recover-claim', `A recovery claim by pid ${r.pid} (${(Math.max(0, age) / 1000).toFixed(1)} s old, ${v.reason}) blocks the recovery of the request lock of ${id}.`);
|
|
170
|
+
},
|
|
171
|
+
claim: (recovers) => ({ kind: 'request-recovery', token: (0, node_crypto_1.randomUUID)(), pid: process.pid, host: me.host, bootId: me.bootId, claimedAt: new Date().toISOString(), recovers }),
|
|
172
|
+
};
|
|
173
|
+
}
|
|
174
|
+
const sleepSync = (ms) => { try {
|
|
175
|
+
Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
|
|
176
|
+
}
|
|
177
|
+
catch { /* retry without waiting */ } };
|
|
178
|
+
const unwrapAct = (f) => { try {
|
|
179
|
+
return f();
|
|
180
|
+
}
|
|
181
|
+
catch (e) {
|
|
182
|
+
throw e instanceof owned_lock_1.ActError ? e.inner : e;
|
|
183
|
+
} };
|
|
184
|
+
function fenceOf(root, lfs, id, token, ownership) {
|
|
185
|
+
const lost = (why) => new FenceLost(`The request lock of ${id} ${why}; this holder writes nothing.`);
|
|
186
|
+
const check = () => {
|
|
187
|
+
let dir, claims;
|
|
188
|
+
try {
|
|
189
|
+
dir = path.join(lfs.directory(exports.REQUEST_LOCKS_DIR), id);
|
|
190
|
+
claims = lfs.directory(exports.REQUEST_CLAIMS_DIR);
|
|
191
|
+
}
|
|
192
|
+
catch {
|
|
193
|
+
throw lost('cannot be read through its locator');
|
|
194
|
+
}
|
|
195
|
+
let s, owner;
|
|
196
|
+
try {
|
|
197
|
+
s = lfs.stat(dir);
|
|
198
|
+
}
|
|
199
|
+
catch {
|
|
200
|
+
s = undefined;
|
|
201
|
+
}
|
|
202
|
+
if (!s || !s.isDirectory())
|
|
203
|
+
throw lost('is gone');
|
|
204
|
+
if (s.dev !== ownership.dev || s.ino !== ownership.ino)
|
|
205
|
+
throw lost('was replaced');
|
|
206
|
+
try {
|
|
207
|
+
owner = JSON.parse(lfs.readBytes(path.join(dir, 'owner.json'))?.toString('utf8') ?? 'null');
|
|
208
|
+
}
|
|
209
|
+
catch {
|
|
210
|
+
owner = null;
|
|
211
|
+
}
|
|
212
|
+
if (owner?.token !== token)
|
|
213
|
+
throw lost('has another holder');
|
|
214
|
+
for (const claim of [path.join(dir, `successor-${token}.json`), path.join(claims, `successor-${token}.json`)]) {
|
|
215
|
+
let c;
|
|
216
|
+
try {
|
|
217
|
+
c = lfs.stat(claim);
|
|
218
|
+
}
|
|
219
|
+
catch {
|
|
220
|
+
throw lost('cannot be read through its locator');
|
|
221
|
+
}
|
|
222
|
+
if (c)
|
|
223
|
+
throw lost('is claimed by a successor');
|
|
224
|
+
}
|
|
225
|
+
};
|
|
226
|
+
return {
|
|
227
|
+
check,
|
|
228
|
+
write: (fn) => { check(); return fn(); },
|
|
229
|
+
publish: (dirRel, name, bytes) => {
|
|
230
|
+
if (path.basename(name) !== name || name === '' || name.startsWith('.'))
|
|
231
|
+
throw new PublishConflict(`Not a publishable name: ${JSON.stringify(name)}.`);
|
|
232
|
+
check();
|
|
233
|
+
const target = lfs.directory(dirRel, true);
|
|
234
|
+
const temp = path.join(target, `.publishing.${(0, node_crypto_1.randomUUID)()}.tmp`);
|
|
235
|
+
fs.writeFileSync(temp, bytes, { flag: 'wx', mode: 0o600 });
|
|
236
|
+
try {
|
|
237
|
+
fs.linkSync(temp, path.join(target, name));
|
|
238
|
+
}
|
|
239
|
+
catch (e) {
|
|
240
|
+
const code = e.code;
|
|
241
|
+
if (code === 'EEXIST')
|
|
242
|
+
throw new PublishConflict(`${path.join(dirRel, name)} exists; it is not replaced.`);
|
|
243
|
+
if (code === 'EPERM' || code === 'ENOTSUP' || code === 'EXDEV' || code === 'ENOSYS')
|
|
244
|
+
throw new PublishUnsupported(`This file system refused the hard link a publish needs (${code}); ${path.join(dirRel, name)} is not written.`);
|
|
245
|
+
throw e;
|
|
246
|
+
}
|
|
247
|
+
finally {
|
|
248
|
+
try {
|
|
249
|
+
fs.unlinkSync(temp);
|
|
250
|
+
}
|
|
251
|
+
catch { /* a leftover temp file is read by reconcile */ }
|
|
252
|
+
}
|
|
253
|
+
},
|
|
254
|
+
};
|
|
255
|
+
}
|
|
256
|
+
function recordLeak(root, lfs, id, e) {
|
|
257
|
+
const message = e instanceof Error ? e.message : String(e);
|
|
258
|
+
try {
|
|
259
|
+
lfs.appendLine(path.join(root, exports.REQUEST_LEAKS_FILE), JSON.stringify({ at: new Date().toISOString(), pid: process.pid, id, error: message }));
|
|
260
|
+
}
|
|
261
|
+
catch { /* stderr still says it */ }
|
|
262
|
+
try {
|
|
263
|
+
process.stderr.write(`[Holmes-Kit] the request lock of ${id} was not released (${message}); it is recovered like a dead holder's, or by the operator.\n`);
|
|
264
|
+
}
|
|
265
|
+
catch { /* best effort */ }
|
|
266
|
+
}
|
|
267
|
+
/**
|
|
268
|
+
* Take the request lock of `id` within `opts.budgetMs`, run `act` with the fence, and release. Busy past the budget is
|
|
269
|
+
* `lock-busy`; this process's own hold of the id is `lock-leak`; an id outside `req-<12 hex>`, or a root without `.ax`,
|
|
270
|
+
* is refused before any file is touched. A release that fails after `act` returned does not hide the result; when
|
|
271
|
+
* `act` threw, its error is the one thrown.
|
|
272
|
+
*/
|
|
273
|
+
function withRequestLock(root, id, opts, act) {
|
|
274
|
+
if (!REQUEST_ID.test(id))
|
|
275
|
+
throw new owned_lock_1.LockError('unknown-owner', 'acquire', `Not a request id: ${JSON.stringify(id)}.`);
|
|
276
|
+
let ax;
|
|
277
|
+
try {
|
|
278
|
+
ax = fs.lstatSync(path.join(root, '.ax'));
|
|
279
|
+
}
|
|
280
|
+
catch {
|
|
281
|
+
ax = undefined;
|
|
282
|
+
}
|
|
283
|
+
if (!ax?.isDirectory())
|
|
284
|
+
throw new owned_lock_1.LockError('unknown-owner', 'acquire', 'A request lock is taken only inside an existing .ax directory.');
|
|
285
|
+
const lfs = lockFsOf(root);
|
|
286
|
+
const layout = requestLockLayout(id);
|
|
287
|
+
const me = identityOf(opts.identity);
|
|
288
|
+
const platform = opts.platform ?? process.platform;
|
|
289
|
+
const record = { kind: 'request', token: (0, node_crypto_1.randomUUID)(), pid: process.pid, host: me.host, bootId: me.bootId,
|
|
290
|
+
acquiredAt: new Date().toISOString(), boundMs: opts.boundMs ?? 1000, id };
|
|
291
|
+
const deadline = Date.now() + opts.budgetMs;
|
|
292
|
+
let lastBusy = `The request lock of ${id} is held.`;
|
|
293
|
+
let orphan = false;
|
|
294
|
+
for (;;) {
|
|
295
|
+
let release;
|
|
296
|
+
try {
|
|
297
|
+
release = (0, owned_lock_1.acquireOwnedLock)(lfs, layout, record);
|
|
298
|
+
}
|
|
299
|
+
catch (e) {
|
|
300
|
+
if (!(e instanceof owned_lock_1.LockError) || e.code !== 'lock-busy')
|
|
301
|
+
throw e;
|
|
302
|
+
}
|
|
303
|
+
if (release) {
|
|
304
|
+
held.add(record.token);
|
|
305
|
+
let result, failure;
|
|
306
|
+
try {
|
|
307
|
+
const ownership = lfs.stat(path.join(lfs.directory(exports.REQUEST_LOCKS_DIR), id));
|
|
308
|
+
if (!ownership)
|
|
309
|
+
throw new FenceLost(`The request lock of ${id} vanished as it was taken; this holder writes nothing.`);
|
|
310
|
+
result = act(fenceOf(root, lfs, id, record.token, ownership));
|
|
311
|
+
}
|
|
312
|
+
catch (e) {
|
|
313
|
+
failure = { error: e };
|
|
314
|
+
}
|
|
315
|
+
try {
|
|
316
|
+
release();
|
|
317
|
+
}
|
|
318
|
+
catch (e) {
|
|
319
|
+
recordLeak(root, lfs, id, e);
|
|
320
|
+
}
|
|
321
|
+
finally {
|
|
322
|
+
held.delete(record.token);
|
|
323
|
+
}
|
|
324
|
+
if (failure)
|
|
325
|
+
throw failure.error;
|
|
326
|
+
return result;
|
|
327
|
+
}
|
|
328
|
+
const bytes = lfs.readBytes(path.join(lfs.directory(exports.REQUEST_LOCKS_DIR), id, 'owner.json'));
|
|
329
|
+
orphan = false;
|
|
330
|
+
if (bytes !== undefined) {
|
|
331
|
+
let raw;
|
|
332
|
+
try {
|
|
333
|
+
raw = JSON.parse(bytes.toString('utf8'));
|
|
334
|
+
}
|
|
335
|
+
catch {
|
|
336
|
+
throw new owned_lock_1.LockError('unknown-owner', 'inspect', 'Malformed lock ownership must be preserved.');
|
|
337
|
+
}
|
|
338
|
+
if (!validHolder(raw, id))
|
|
339
|
+
throw new owned_lock_1.LockError('unknown-owner', 'inspect', 'Invalid lock ownership must be preserved.');
|
|
340
|
+
const v = verdictOf(raw, me, platform, opts.probe);
|
|
341
|
+
if (!v.dead && v.reason === 'leak')
|
|
342
|
+
throw new owned_lock_1.LockError('lock-leak', 'acquire', `This process already holds the request lock of ${id}; a second acquisition is a leak.`);
|
|
343
|
+
if (v.dead || pastBound(raw, v.reason, Date.now())) {
|
|
344
|
+
try {
|
|
345
|
+
unwrapAct(() => (0, owned_lock_1.recoverOwnedLock)(lfs, layout, policyOf(id, me, platform, opts.probe), () => undefined, () => () => undefined));
|
|
346
|
+
}
|
|
347
|
+
catch (e) {
|
|
348
|
+
if (!(e instanceof owned_lock_1.LockError) || e.code !== 'lock-busy')
|
|
349
|
+
throw e;
|
|
350
|
+
lastBusy = e.message;
|
|
351
|
+
}
|
|
352
|
+
if (Date.now() < deadline)
|
|
353
|
+
continue;
|
|
354
|
+
}
|
|
355
|
+
else
|
|
356
|
+
lastBusy = busyMessage(id, raw, v.reason);
|
|
357
|
+
}
|
|
358
|
+
else if (lfs.stat(path.join(lfs.directory(exports.REQUEST_LOCKS_DIR), id))) {
|
|
359
|
+
// a directory between its rename and its owner read, or one left without a record: read again on the next pass
|
|
360
|
+
orphan = true;
|
|
361
|
+
lastBusy = `The request lock of ${id} has no holder record yet.`;
|
|
362
|
+
}
|
|
363
|
+
if (Date.now() >= deadline) {
|
|
364
|
+
if (orphan)
|
|
365
|
+
throw new owned_lock_1.LockError('unknown-owner', 'inspect', 'A request lock without a holder record is preserved for inspection.');
|
|
366
|
+
throw new owned_lock_1.LockError('lock-busy', 'acquire', lastBusy);
|
|
367
|
+
}
|
|
368
|
+
sleepSync(Math.min(15, Math.max(1, deadline - Date.now())));
|
|
369
|
+
}
|
|
370
|
+
}
|
|
371
|
+
/** The held request locks with a readable holder, for doctor. */
|
|
372
|
+
function requestLockHolders(root) {
|
|
373
|
+
const lfs = lockFsOf(root);
|
|
374
|
+
let dir, names;
|
|
375
|
+
try {
|
|
376
|
+
dir = lfs.directory(exports.REQUEST_LOCKS_DIR);
|
|
377
|
+
names = lfs.list(dir);
|
|
378
|
+
}
|
|
379
|
+
catch {
|
|
380
|
+
return [];
|
|
381
|
+
}
|
|
382
|
+
const out = [];
|
|
383
|
+
for (const name of names) {
|
|
384
|
+
if (!REQUEST_ID.test(name))
|
|
385
|
+
continue;
|
|
386
|
+
try {
|
|
387
|
+
const r = JSON.parse(lfs.readBytes(path.join(dir, name, 'owner.json'))?.toString('utf8') ?? 'null');
|
|
388
|
+
if (validHolder(r, name))
|
|
389
|
+
out.push(r);
|
|
390
|
+
}
|
|
391
|
+
catch { /* unreadable: doctor says nothing it cannot read */ }
|
|
392
|
+
}
|
|
393
|
+
return out;
|
|
394
|
+
}
|
|
395
|
+
/**
|
|
396
|
+
* The operator's recovery of one request lock, by `recoverSpendLockAsOperator`'s rules: a dead holder is recovered;
|
|
397
|
+
* an unjudgeable one needs `confirmHolderDead`; an answering one needs it and a hold longer than 4x its bound; this
|
|
398
|
+
* process's own hold is refused; a lock that changed hands since it was read is refused.
|
|
399
|
+
*/
|
|
400
|
+
function recoverRequestLockAsOperator(root, id, opts) {
|
|
401
|
+
if (!REQUEST_ID.test(id))
|
|
402
|
+
return { refused: `Not a request id: ${JSON.stringify(id)}.` };
|
|
403
|
+
const lfs = lockFsOf(root);
|
|
404
|
+
let holder = null, present = false;
|
|
405
|
+
try {
|
|
406
|
+
const dir = path.join(lfs.directory(exports.REQUEST_LOCKS_DIR), id);
|
|
407
|
+
present = lfs.stat(dir) !== undefined;
|
|
408
|
+
const r = JSON.parse(lfs.readBytes(path.join(dir, 'owner.json'))?.toString('utf8') ?? 'null');
|
|
409
|
+
holder = validHolder(r, id) ? r : null;
|
|
410
|
+
}
|
|
411
|
+
catch {
|
|
412
|
+
holder = null;
|
|
413
|
+
}
|
|
414
|
+
if (!holder)
|
|
415
|
+
return present ? { refused: `The request lock of ${id} has no readable holder record; it is preserved for inspection.` } : { nothing: true };
|
|
416
|
+
if (opts.expectToken !== undefined && holder.token !== opts.expectToken)
|
|
417
|
+
return { refused: `The request lock of ${id} changed hands after it was read; run again to judge the current holder.` };
|
|
418
|
+
const me = identityOf(opts.identity);
|
|
419
|
+
const platform = opts.platform ?? process.platform;
|
|
420
|
+
const now = (opts.now ?? Date.now)();
|
|
421
|
+
const v = verdictOf(holder, me, platform, opts.probe);
|
|
422
|
+
let reason;
|
|
423
|
+
if (v.dead)
|
|
424
|
+
reason = 'the holder is dead';
|
|
425
|
+
else if (v.reason === 'leak')
|
|
426
|
+
return { refused: `This process holds the request lock of ${id}; it is released when its act ends.` };
|
|
427
|
+
else if (v.reason === 'alive') {
|
|
428
|
+
if (!opts.confirmHolderDead)
|
|
429
|
+
return { refused: `The request 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 ${exports.AGE_FACTOR}x its bound.` };
|
|
430
|
+
if (!(ageOf(holder.acquiredAt, now) > exports.AGE_FACTOR * holder.boundMs))
|
|
431
|
+
return { refused: `The request lock's holder, pid ${holder.pid}, answers and has not been held longer than ${exports.AGE_FACTOR}x its bound; it is not recovered.` };
|
|
432
|
+
reason = `confirmed dead by the operator: pid ${holder.pid} answers, held past ${exports.AGE_FACTOR}x its bound`;
|
|
433
|
+
}
|
|
434
|
+
else {
|
|
435
|
+
if (!opts.confirmHolderDead)
|
|
436
|
+
return { refused: `The request lock's holder, pid ${holder.pid}, cannot be judged dead here (${v.reason}); if it is dead, run again with --confirm-holder-dead.` };
|
|
437
|
+
reason = `confirmed dead by the operator (${v.reason})`;
|
|
438
|
+
}
|
|
439
|
+
const force = { token: holder.token, confirmClaims: opts.confirmHolderDead, now };
|
|
440
|
+
try {
|
|
441
|
+
unwrapAct(() => (0, owned_lock_1.recoverOwnedLock)(lfs, requestLockLayout(id), policyOf(id, me, platform, opts.probe, force), () => undefined, () => () => undefined));
|
|
442
|
+
}
|
|
443
|
+
catch (e) {
|
|
444
|
+
if (e instanceof owned_lock_1.LockError && e.code === 'lock-busy')
|
|
445
|
+
return { refused: e.message };
|
|
446
|
+
throw e;
|
|
447
|
+
}
|
|
448
|
+
return { recovered: holder, reason };
|
|
449
|
+
}
|
|
450
|
+
/** 1 + the largest `lockEpoch` among the events of `id` that is a safe integer in [0, 2^32), or 1 when there is none. */
|
|
451
|
+
function nextLockEpoch(events, id) {
|
|
452
|
+
let max = 0;
|
|
453
|
+
for (const e of events) {
|
|
454
|
+
const n = e.lockEpoch;
|
|
455
|
+
if (e.id === id && typeof n === 'number' && Number.isSafeInteger(n) && n >= 0 && n < EPOCH_LIMIT && n > max)
|
|
456
|
+
max = n;
|
|
457
|
+
}
|
|
458
|
+
return max + 1;
|
|
459
|
+
}
|
|
@@ -32,14 +32,22 @@ export interface ProjectRoot {
|
|
|
32
32
|
}
|
|
33
33
|
/** The marker directory that makes a directory a Holmes-Kit project. */
|
|
34
34
|
export declare const MARKER = ".ax";
|
|
35
|
+
/**
|
|
36
|
+
* @implements A-SPEC-102.31 — the one rule of what a project is: `dir/.ax` is a directory, a link to one included. The
|
|
37
|
+
* file system's own case rule applies (macOS answers `.AX` for `.ax`). A regular file named `.ax` is no project: it made a
|
|
38
|
+
* new catalog boundary (A, N5). resolveProjectRoot and the autonomy scope search both ask this.
|
|
39
|
+
*/
|
|
40
|
+
export declare function isProjectDir(dir: string, opts?: {
|
|
41
|
+
strict?: boolean;
|
|
42
|
+
}): boolean;
|
|
35
43
|
/**
|
|
36
44
|
* The one canonical spelling of an existing path.
|
|
37
45
|
*
|
|
38
46
|
* `fs.realpathSync.native`, not `fs.realpathSync`. The JS implementation resolves symlinks only;
|
|
39
|
-
* on Windows it leaves 8.3 short-name aliases (`C:\Users\
|
|
47
|
+
* on Windows it leaves 8.3 short-name aliases (`C:\Users\FIRSTL~1`, which is what `%TEMP%` and
|
|
40
48
|
* `os.tmpdir()` hand out) exactly as spelled, while `git rev-parse --show-toplevel` prints the
|
|
41
|
-
* long name. Measured 2026-08-23: `resolveProjectRoot('C:/
|
|
42
|
-
* `root: C:\
|
|
49
|
+
* long name. Measured 2026-08-23: `resolveProjectRoot('C:/WORKSP~1/MYPROJ~1')` reported
|
|
50
|
+
* `root: C:\WORKSP~1\MYPROJ~1` beside `git.topLevel: C:\workspace\my-project` for ONE
|
|
43
51
|
* directory, and GitChangeSource refused it as a mismatch. The native call expands both symlinks
|
|
44
52
|
* and 8.3 names (a strict superset, same ENOENT behaviour), so `root` keeps the promise its type
|
|
45
53
|
* makes: one spelling per directory, the spelling every path key is built from.
|
|
@@ -51,7 +59,7 @@ export declare const canonicalPath: (p: string) => string;
|
|
|
51
59
|
* so 8.3 aliases and symlinks collapse); a path that does not exist compares by its resolved spelling.
|
|
52
60
|
* `realpath` is injectable so the 8.3 scenario runs on every OS in the tests. Measured 2026-09-14
|
|
53
61
|
* (WIN0200-20260914-SHORTPATH): `entityStoreBinding` compared JS `fs.realpathSync` output against a
|
|
54
|
-
* native-canonical root, so a workspace entered as `C:\Users\
|
|
62
|
+
* native-canonical root, so a workspace entered as `C:\Users\FIRSTL~1\…` was refused as foreign.
|
|
55
63
|
*/
|
|
56
64
|
export declare function sameCanonicalDirectory(a: string, b: string, realpath?: (p: string) => string): boolean;
|
|
57
65
|
export declare function resolveProjectRoot(dir: string, opts?: {
|
|
@@ -36,9 +36,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
|
|
|
36
36
|
exports.canonicalPath = exports.MARKER = void 0;
|
|
37
37
|
exports.cleanSubprocessEnv = cleanSubprocessEnv;
|
|
38
38
|
exports.cleanTestEnv = cleanTestEnv;
|
|
39
|
+
exports.isProjectDir = isProjectDir;
|
|
39
40
|
exports.sameCanonicalDirectory = sameCanonicalDirectory;
|
|
40
41
|
exports.resolveProjectRoot = resolveProjectRoot;
|
|
41
|
-
// @implements A-SPEC-205, A-SPEC-627, A-SPEC-734
|
|
42
|
+
// @implements A-SPEC-205, A-SPEC-627, A-SPEC-734, A-SPEC-102.31, A-SPEC-102.32, A-SPEC-794.47, A-SPEC-794.57, A-SPEC-794.58
|
|
42
43
|
// @implements A-SPEC-128
|
|
43
44
|
const fs = __importStar(require("node:fs"));
|
|
44
45
|
const path = __importStar(require("node:path"));
|
|
@@ -97,7 +98,7 @@ function cleanSubprocessEnv(env = process.env) {
|
|
|
97
98
|
// under test; an evidence run must judge the same in an autonomous workspace and a human-gated one.
|
|
98
99
|
// @implements A-SPEC-695
|
|
99
100
|
// `NPM_CONFIG_DRY_RUN` is the fourth of the same family and the first that is not ours. Measured
|
|
100
|
-
// 2026-09-20: `npm publish --dry-run` —
|
|
101
|
+
// 2026-09-20: `npm publish --dry-run` — which the publish playbook prescribed until A-SPEC-794.46 — exports
|
|
101
102
|
// `npm_config_dry_run=true` to `prepublishOnly`; the release gate handed it to jest; and the
|
|
102
103
|
// mcp-launcher suite's own `npx -p <tarball>` then installed NOTHING, so the handshake returned null
|
|
103
104
|
// and the gate refused a green tree twice with "this source is not publishable". Load was suspected
|
|
@@ -116,14 +117,32 @@ function cleanTestEnv(env = process.env) {
|
|
|
116
117
|
}
|
|
117
118
|
/** The marker directory that makes a directory a Holmes-Kit project. */
|
|
118
119
|
exports.MARKER = '.ax';
|
|
120
|
+
/**
|
|
121
|
+
* @implements A-SPEC-102.31 — the one rule of what a project is: `dir/.ax` is a directory, a link to one included. The
|
|
122
|
+
* file system's own case rule applies (macOS answers `.AX` for `.ax`). A regular file named `.ax` is no project: it made a
|
|
123
|
+
* new catalog boundary (A, N5). resolveProjectRoot and the autonomy scope search both ask this.
|
|
124
|
+
*/
|
|
125
|
+
function isProjectDir(dir, opts = {}) {
|
|
126
|
+
try {
|
|
127
|
+
return fs.statSync(path.join(dir, exports.MARKER)).isDirectory();
|
|
128
|
+
}
|
|
129
|
+
catch (e) {
|
|
130
|
+
// @implements A-SPEC-102.32 — strict (the catalog union): only an absent `.ax` is no project; one that cannot be
|
|
131
|
+
// stat'ed (a parent closed with chmod 000) dropped its additions silently while doctor said PASS (A, low 4)
|
|
132
|
+
const code = e.code;
|
|
133
|
+
if (opts.strict === true && code !== 'ENOENT' && code !== 'ENOTDIR')
|
|
134
|
+
throw e;
|
|
135
|
+
return false;
|
|
136
|
+
}
|
|
137
|
+
}
|
|
119
138
|
/**
|
|
120
139
|
* The one canonical spelling of an existing path.
|
|
121
140
|
*
|
|
122
141
|
* `fs.realpathSync.native`, not `fs.realpathSync`. The JS implementation resolves symlinks only;
|
|
123
|
-
* on Windows it leaves 8.3 short-name aliases (`C:\Users\
|
|
142
|
+
* on Windows it leaves 8.3 short-name aliases (`C:\Users\FIRSTL~1`, which is what `%TEMP%` and
|
|
124
143
|
* `os.tmpdir()` hand out) exactly as spelled, while `git rev-parse --show-toplevel` prints the
|
|
125
|
-
* long name. Measured 2026-08-23: `resolveProjectRoot('C:/
|
|
126
|
-
* `root: C:\
|
|
144
|
+
* long name. Measured 2026-08-23: `resolveProjectRoot('C:/WORKSP~1/MYPROJ~1')` reported
|
|
145
|
+
* `root: C:\WORKSP~1\MYPROJ~1` beside `git.topLevel: C:\workspace\my-project` for ONE
|
|
127
146
|
* directory, and GitChangeSource refused it as a mismatch. The native call expands both symlinks
|
|
128
147
|
* and 8.3 names (a strict superset, same ENOENT behaviour), so `root` keeps the promise its type
|
|
129
148
|
* makes: one spelling per directory, the spelling every path key is built from.
|
|
@@ -137,7 +156,7 @@ const canonical = exports.canonicalPath;
|
|
|
137
156
|
* so 8.3 aliases and symlinks collapse); a path that does not exist compares by its resolved spelling.
|
|
138
157
|
* `realpath` is injectable so the 8.3 scenario runs on every OS in the tests. Measured 2026-09-14
|
|
139
158
|
* (WIN0200-20260914-SHORTPATH): `entityStoreBinding` compared JS `fs.realpathSync` output against a
|
|
140
|
-
* native-canonical root, so a workspace entered as `C:\Users\
|
|
159
|
+
* native-canonical root, so a workspace entered as `C:\Users\FIRSTL~1\…` was refused as foreign.
|
|
141
160
|
*/
|
|
142
161
|
function sameCanonicalDirectory(a, b, realpath = exports.canonicalPath) {
|
|
143
162
|
const spell = (p) => { try {
|
|
@@ -199,7 +218,7 @@ function resolveProjectRoot(dir, opts = {}) {
|
|
|
199
218
|
const insideAx = (p) => p.split(path.sep).some((seg) => seg.toLowerCase() === exports.MARKER.toLowerCase());
|
|
200
219
|
let found;
|
|
201
220
|
for (let cur = start;; cur = path.dirname(cur)) {
|
|
202
|
-
if (!insideAx(cur) &&
|
|
221
|
+
if (!insideAx(cur) && isProjectDir(cur)) {
|
|
203
222
|
found = cur;
|
|
204
223
|
break;
|
|
205
224
|
}
|