@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,133 @@
|
|
|
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.IDENTITY_NULL_RETRY_MS = exports.IDENTITY_TIMEOUT_MS = void 0;
|
|
37
|
+
exports.createIdentityReader = createIdentityReader;
|
|
38
|
+
exports.bootId = bootId;
|
|
39
|
+
exports.hostId = hostId;
|
|
40
|
+
// @implements A-SPEC-245.8, A-SPEC-245.10
|
|
41
|
+
/**
|
|
42
|
+
* Which machine and which boot a process runs on, for the spend lock's holder record and its automatic recovery.
|
|
43
|
+
*
|
|
44
|
+
* - bootId: Linux `/proc/sys/kernel/random/boot_id`; macOS `kern.bootsessionuuid`; Windows null.
|
|
45
|
+
* - hostId: Linux `/etc/machine-id` with the inode of `/proc/self/ns/pid` (containers share boot_id and may share or
|
|
46
|
+
* lack machine-id, so a live holder in another pid namespace must not look dead); macOS `IOPlatformUUID`; Windows
|
|
47
|
+
* `MachineGuid`.
|
|
48
|
+
*
|
|
49
|
+
* No environment seam: commands run by absolute path with an empty environment, so neither PATH nor any variable
|
|
50
|
+
* changes an identity. Tests inject the readers instead. Nothing runs at import; each value is read once per reader,
|
|
51
|
+
* bounded to 1 s, and null on any failure.
|
|
52
|
+
*/
|
|
53
|
+
const cp = __importStar(require("node:child_process"));
|
|
54
|
+
const fs = __importStar(require("node:fs"));
|
|
55
|
+
exports.IDENTITY_TIMEOUT_MS = 1000;
|
|
56
|
+
/** A-SPEC-245.10 (low): a null is kept this long, not for the process's life — a read that timed out under load retries. */
|
|
57
|
+
exports.IDENTITY_NULL_RETRY_MS = 60_000;
|
|
58
|
+
const UUID = /[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}/;
|
|
59
|
+
function createIdentityReader(deps) {
|
|
60
|
+
const run = (file, args) => {
|
|
61
|
+
try {
|
|
62
|
+
return deps.exec(file, args, { timeout: exports.IDENTITY_TIMEOUT_MS, env: {}, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
|
|
63
|
+
}
|
|
64
|
+
catch {
|
|
65
|
+
return null;
|
|
66
|
+
}
|
|
67
|
+
};
|
|
68
|
+
const read = (p) => { try {
|
|
69
|
+
const t = deps.readFile(p).trim();
|
|
70
|
+
return t === '' ? null : t;
|
|
71
|
+
}
|
|
72
|
+
catch {
|
|
73
|
+
return null;
|
|
74
|
+
} };
|
|
75
|
+
const now = deps.now ?? Date.now;
|
|
76
|
+
/** A value once read is kept; a null is read again after IDENTITY_NULL_RETRY_MS. */
|
|
77
|
+
const once = (f) => {
|
|
78
|
+
let value = null, readAt = null;
|
|
79
|
+
return () => {
|
|
80
|
+
if (readAt === null || (value === null && now() - readAt >= exports.IDENTITY_NULL_RETRY_MS)) {
|
|
81
|
+
value = f();
|
|
82
|
+
readAt = now();
|
|
83
|
+
}
|
|
84
|
+
return value;
|
|
85
|
+
};
|
|
86
|
+
};
|
|
87
|
+
const boot = once(() => {
|
|
88
|
+
if (deps.platform === 'linux')
|
|
89
|
+
return read('/proc/sys/kernel/random/boot_id');
|
|
90
|
+
if (deps.platform === 'darwin')
|
|
91
|
+
return UUID.exec(run('/usr/sbin/sysctl', ['-n', 'kern.bootsessionuuid']) ?? '')?.[0] ?? null;
|
|
92
|
+
return null;
|
|
93
|
+
});
|
|
94
|
+
const host = once(() => {
|
|
95
|
+
if (deps.platform === 'linux') {
|
|
96
|
+
const id = read('/etc/machine-id');
|
|
97
|
+
if (id === null)
|
|
98
|
+
return null;
|
|
99
|
+
try {
|
|
100
|
+
return `${id}:${deps.statIno('/proc/self/ns/pid')}`;
|
|
101
|
+
}
|
|
102
|
+
catch {
|
|
103
|
+
return null;
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
if (deps.platform === 'darwin') {
|
|
107
|
+
return /"IOPlatformUUID"\s*=\s*"([^"]+)"/.exec(run('/usr/sbin/ioreg', ['-rd1', '-c', 'IOPlatformExpertDevice']) ?? '')?.[1] ?? null;
|
|
108
|
+
}
|
|
109
|
+
if (deps.platform === 'win32') {
|
|
110
|
+
const reg = `${(deps.systemRoot ?? 'C:\\Windows').replace(/\\+$/, '')}\\System32\\reg.exe`;
|
|
111
|
+
return /MachineGuid\s+REG_SZ\s+(\S+)/.exec(run(reg, ['query', 'HKLM\\SOFTWARE\\Microsoft\\Cryptography', '/v', 'MachineGuid']) ?? '')?.[1] ?? null;
|
|
112
|
+
}
|
|
113
|
+
return null;
|
|
114
|
+
});
|
|
115
|
+
return { bootId: boot, hostId: host };
|
|
116
|
+
}
|
|
117
|
+
let shared = null;
|
|
118
|
+
/** The process's reader over the real system, made on first use. */
|
|
119
|
+
function real() {
|
|
120
|
+
if (shared === null) {
|
|
121
|
+
shared = createIdentityReader({
|
|
122
|
+
platform: process.platform,
|
|
123
|
+
exec: (file, args, opts) => cp.execFileSync(file, args, opts),
|
|
124
|
+
readFile: (p) => fs.readFileSync(p, 'utf8'),
|
|
125
|
+
statIno: (p) => fs.statSync(p).ino,
|
|
126
|
+
// read once, when Windows first asks; not a seam on the identity itself, only where the system's reg.exe is
|
|
127
|
+
systemRoot: process.platform === 'win32' ? (process.env.SystemRoot || 'C:\\Windows') : undefined,
|
|
128
|
+
});
|
|
129
|
+
}
|
|
130
|
+
return shared;
|
|
131
|
+
}
|
|
132
|
+
function bootId() { return real().bootId(); }
|
|
133
|
+
function hostId() { return real().hostId(); }
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
import type * as fs from 'node:fs';
|
|
2
|
+
export type LockCode = 'lock-busy' | 'unknown-owner' | 'cleanup-conflict' | 'retirement-conflict' | 'lock-leak';
|
|
3
|
+
/** Where a busy answer arose: acquisition, recovery meeting a live owner, or a lost recovery claim. */
|
|
4
|
+
export type LockSite = 'acquire' | 'recover-live' | 'recover-claim' | 'inspect' | 'retire';
|
|
5
|
+
export declare class LockError extends Error {
|
|
6
|
+
readonly code: LockCode;
|
|
7
|
+
readonly site: LockSite;
|
|
8
|
+
readonly holmesRefusal = true;
|
|
9
|
+
constructor(code: LockCode, site: LockSite, message: string);
|
|
10
|
+
}
|
|
11
|
+
/** The neutral busy message of acquisition; a store may say it in its own words. */
|
|
12
|
+
export declare const LOCK_HELD_MESSAGE = "The lock is held by another or an interrupted operation.";
|
|
13
|
+
/** Every file operation of the protocol. A store passes its own guarded primitives. */
|
|
14
|
+
export interface LockFs {
|
|
15
|
+
stat(file: string): fs.Stats | undefined;
|
|
16
|
+
/** A directory under the root, by canonical relative locator; created when asked. */
|
|
17
|
+
directory(relative: string, create?: boolean): string;
|
|
18
|
+
readBytes(file: string): Buffer | undefined;
|
|
19
|
+
/** Publish complete bytes at a relative locator without replacing an existing file (EEXIST when it exists). */
|
|
20
|
+
publish(relative: string, bytes: string): void;
|
|
21
|
+
/** Rename a lock directory out of the way (retirement); a store may retry transient failures here. */
|
|
22
|
+
rename(from: string, to: string): void;
|
|
23
|
+
/** Rename a staged directory into the lock path, once: a failure is an answer (busy), never retried. */
|
|
24
|
+
renameNew(from: string, to: string): void;
|
|
25
|
+
/** Append one line to a file under the root (diagnostics such as a leak record). */
|
|
26
|
+
appendLine(file: string, line: string): void;
|
|
27
|
+
/** Replace a record's bytes, given the bytes it must still hold. */
|
|
28
|
+
replace(relative: string, before: string, after: string): void;
|
|
29
|
+
list(dir: string): string[];
|
|
30
|
+
makeDir(dir: string): void;
|
|
31
|
+
/** Write a new file; EEXIST when it exists. */
|
|
32
|
+
writeNew(file: string, bytes: string): void;
|
|
33
|
+
unlink(file: string): void;
|
|
34
|
+
removeDir(dir: string): void;
|
|
35
|
+
removeTree(dir: string): void;
|
|
36
|
+
/** Whether a name inside a lock directory is this store's own publication transient. */
|
|
37
|
+
isOwnTransient(name: string): boolean;
|
|
38
|
+
}
|
|
39
|
+
/** Where one lock lives, relative to the root. */
|
|
40
|
+
export interface LockLayout {
|
|
41
|
+
/** The parent of the lock directory, where staging directories live. */
|
|
42
|
+
parent: string;
|
|
43
|
+
/** The lock directory's name inside `parent`. */
|
|
44
|
+
name: string;
|
|
45
|
+
/** The directory holding this lock's successor claims. */
|
|
46
|
+
claims: string;
|
|
47
|
+
/** The retired-locks namespace. */
|
|
48
|
+
retired: string;
|
|
49
|
+
}
|
|
50
|
+
export type OwnerRecord = {
|
|
51
|
+
token: string;
|
|
52
|
+
pid: number;
|
|
53
|
+
released?: true;
|
|
54
|
+
} & Record<string, unknown>;
|
|
55
|
+
/** One validator and one liveness judgement per kind. */
|
|
56
|
+
export interface RecoveryPolicy {
|
|
57
|
+
/** The lock kind this policy judges; any kind brings its own policy (A-SPEC-245.11: not a closed set). */
|
|
58
|
+
kind: string;
|
|
59
|
+
/** Whether a record of the chain is well formed; `first` is the lock's own owner record. */
|
|
60
|
+
valid(record: unknown, first: boolean): record is OwnerRecord;
|
|
61
|
+
/** Throws LockError when the record's holder is alive or cannot be judged; returns when it is certainly dead. */
|
|
62
|
+
judgeDead(record: OwnerRecord, first: boolean): void;
|
|
63
|
+
/** A new successor claim for this process, given the generation it recovers. */
|
|
64
|
+
claim(recovers: string): OwnerRecord;
|
|
65
|
+
}
|
|
66
|
+
/** Age after which a `.staging-*` entry beside the locks is treated as abandoned by a publisher that died before its rename (A-SPEC-633). */
|
|
67
|
+
export declare const LOCK_STAGING_STALE_MS: number;
|
|
68
|
+
export declare function isLockToken(t: unknown): t is string;
|
|
69
|
+
/**
|
|
70
|
+
* Take the lock once, without waiting: busy (`lock-busy`, site `acquire`) when it exists in any form. Returns the
|
|
71
|
+
* release function, which retires the lock only while it is still this holder's generation.
|
|
72
|
+
*/
|
|
73
|
+
export declare function acquireOwnedLock(lfs: LockFs, layout: LockLayout, record: OwnerRecord): () => void;
|
|
74
|
+
/** An error `act` threw, carried through the protocol's own error handling untouched. */
|
|
75
|
+
export declare class ActError extends Error {
|
|
76
|
+
readonly inner: unknown;
|
|
77
|
+
constructor(inner: unknown);
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* Claim a dead owner's immutable generation without deleting or replacing its lock, run `act`, and retire the lock.
|
|
81
|
+
* Without a lock, `act` runs under a fresh acquisition (`fresh`). An error `act` throws arrives as ActError, so the
|
|
82
|
+
* caller can tell it from the protocol's own.
|
|
83
|
+
*/
|
|
84
|
+
export declare function recoverOwnedLock<T>(lfs: LockFs, layout: LockLayout, policy: RecoveryPolicy, act: () => T, fresh: () => () => void): T;
|
|
@@ -0,0 +1,263 @@
|
|
|
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.ActError = exports.LOCK_STAGING_STALE_MS = exports.LOCK_HELD_MESSAGE = exports.LockError = void 0;
|
|
37
|
+
exports.isLockToken = isLockToken;
|
|
38
|
+
exports.acquireOwnedLock = acquireOwnedLock;
|
|
39
|
+
exports.recoverOwnedLock = recoverOwnedLock;
|
|
40
|
+
// @implements A-SPEC-245.8, A-SPEC-245.10, A-SPEC-245.11
|
|
41
|
+
/**
|
|
42
|
+
* An owned lock (A-SPEC-633, A-SPEC-638) behind a locator: the protocol the entity store lock and the workspace spend
|
|
43
|
+
* lock share. The spend lock's policy is spend-lock.ts; the entity store's is in entity-transaction.ts.
|
|
44
|
+
*
|
|
45
|
+
* - Acquire: the owner record is written inside a private staging directory that is renamed into the lock path, so a
|
|
46
|
+
* contender sees no lock or a complete one. An existing directory is busy whatever it holds.
|
|
47
|
+
* - Release: only by the holder whose token is in the owner record and whose directory inode is unchanged; the
|
|
48
|
+
* directory is renamed into the retired namespace and its known contents removed.
|
|
49
|
+
* - Recovery: a successor-generation claim published by exclusive create retires a dead generation. A live holder is
|
|
50
|
+
* never touched.
|
|
51
|
+
*
|
|
52
|
+
* Every file operation goes through the LockFs port, and the RecoveryPolicy is one validator and one liveness
|
|
53
|
+
* judgement per kind. Errors are LockError with a code and a site and a neutral message; a store translates them.
|
|
54
|
+
*
|
|
55
|
+
* Limits: one host and a local file system; no fsync, so visibility to concurrent processes is guaranteed and ordering
|
|
56
|
+
* across a power loss is not.
|
|
57
|
+
*/
|
|
58
|
+
const path = __importStar(require("node:path"));
|
|
59
|
+
const node_crypto_1 = require("node:crypto");
|
|
60
|
+
class LockError extends Error {
|
|
61
|
+
code;
|
|
62
|
+
site;
|
|
63
|
+
holmesRefusal = true;
|
|
64
|
+
constructor(code, site, message) {
|
|
65
|
+
super(message);
|
|
66
|
+
this.code = code;
|
|
67
|
+
this.site = site;
|
|
68
|
+
this.name = 'LockError';
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
exports.LockError = LockError;
|
|
72
|
+
/** The neutral busy message of acquisition; a store may say it in its own words. */
|
|
73
|
+
exports.LOCK_HELD_MESSAGE = 'The lock is held by another or an interrupted operation.';
|
|
74
|
+
/** Age after which a `.staging-*` entry beside the locks is treated as abandoned by a publisher that died before its rename (A-SPEC-633). */
|
|
75
|
+
exports.LOCK_STAGING_STALE_MS = 10 * 60_000;
|
|
76
|
+
const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
|
|
77
|
+
function isLockToken(t) { return typeof t === 'string' && UUID_V4.test(t); }
|
|
78
|
+
/** Remove `.staging-*` entries older than the bound: a publisher that died before its rename. Younger entries may belong to a live acquirer; lock directories are never touched. */
|
|
79
|
+
function sweepAbandonedStaging(lfs, locks) {
|
|
80
|
+
let names;
|
|
81
|
+
try {
|
|
82
|
+
names = lfs.list(locks);
|
|
83
|
+
}
|
|
84
|
+
catch {
|
|
85
|
+
return;
|
|
86
|
+
}
|
|
87
|
+
for (const name of names) {
|
|
88
|
+
if (!name.startsWith('.staging-'))
|
|
89
|
+
continue;
|
|
90
|
+
const entry = path.join(locks, name);
|
|
91
|
+
try {
|
|
92
|
+
const s = lfs.stat(entry);
|
|
93
|
+
if (s && Date.now() - s.mtimeMs > exports.LOCK_STAGING_STALE_MS)
|
|
94
|
+
lfs.removeTree(entry);
|
|
95
|
+
}
|
|
96
|
+
catch { /* raced with its owner or already gone */ }
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
function retire(lfs, layout, dir, expected, owned) {
|
|
100
|
+
const current = lfs.stat(dir);
|
|
101
|
+
if (current?.dev !== expected.dev || current?.ino !== expected.ino)
|
|
102
|
+
throw new LockError('unknown-owner', 'retire', 'Lock directory changed before retirement.');
|
|
103
|
+
for (const name of lfs.list(dir))
|
|
104
|
+
if (!owned.has(path.join(dir, name)))
|
|
105
|
+
throw new LockError('cleanup-conflict', 'retire', 'Unknown lock contents must be preserved.');
|
|
106
|
+
const retired = lfs.directory(layout.retired, true);
|
|
107
|
+
const destination = path.join(retired, (0, node_crypto_1.randomUUID)());
|
|
108
|
+
if (lfs.stat(destination))
|
|
109
|
+
throw new LockError('retirement-conflict', 'retire', 'Lock retirement destination is occupied.');
|
|
110
|
+
// Release the active pathname in one step, retaining owner evidence until then.
|
|
111
|
+
lfs.rename(dir, destination);
|
|
112
|
+
for (const file of owned)
|
|
113
|
+
lfs.unlink(path.join(destination, path.basename(file)));
|
|
114
|
+
lfs.removeDir(destination);
|
|
115
|
+
}
|
|
116
|
+
/**
|
|
117
|
+
* Take the lock once, without waiting: busy (`lock-busy`, site `acquire`) when it exists in any form. Returns the
|
|
118
|
+
* release function, which retires the lock only while it is still this holder's generation.
|
|
119
|
+
*/
|
|
120
|
+
function acquireOwnedLock(lfs, layout, record) {
|
|
121
|
+
const locks = lfs.directory(layout.parent, true);
|
|
122
|
+
const dir = path.join(locks, layout.name);
|
|
123
|
+
sweepAbandonedStaging(lfs, locks);
|
|
124
|
+
// An existing directory is busy whatever it holds: rename(2) would silently REPLACE an empty one, and an empty lock
|
|
125
|
+
// directory is exactly the legacy/foreign state that must be preserved for explicit recovery.
|
|
126
|
+
if (lfs.stat(dir))
|
|
127
|
+
throw new LockError('lock-busy', 'acquire', exports.LOCK_HELD_MESSAGE);
|
|
128
|
+
const staging = path.join(locks, '.staging-' + (0, node_crypto_1.randomUUID)());
|
|
129
|
+
lfs.makeDir(staging);
|
|
130
|
+
try {
|
|
131
|
+
// No fsync: the guarantee is atomic visibility to concurrent processes (the rename), not durability across power
|
|
132
|
+
// loss; measured 2026-09-13, an fsync per acquisition cut throughput from thousands to ~76 per second.
|
|
133
|
+
lfs.writeNew(path.join(staging, 'owner.json'), JSON.stringify(record));
|
|
134
|
+
lfs.renameNew(staging, dir);
|
|
135
|
+
}
|
|
136
|
+
catch (e) {
|
|
137
|
+
try {
|
|
138
|
+
lfs.removeTree(staging);
|
|
139
|
+
}
|
|
140
|
+
catch { /* best effort */ }
|
|
141
|
+
const code = e.code;
|
|
142
|
+
if (code === 'EEXIST' || code === 'ENOTEMPTY' || code === 'EPERM')
|
|
143
|
+
throw new LockError('lock-busy', 'acquire', exports.LOCK_HELD_MESSAGE);
|
|
144
|
+
throw e;
|
|
145
|
+
}
|
|
146
|
+
const ownership = lfs.stat(dir);
|
|
147
|
+
return () => {
|
|
148
|
+
const current = lfs.stat(dir);
|
|
149
|
+
if (current?.dev === ownership.dev && current?.ino === ownership.ino) {
|
|
150
|
+
const ownerFile = path.join(dir, 'owner.json');
|
|
151
|
+
const owner = lfs.readBytes(ownerFile);
|
|
152
|
+
if (owner && JSON.parse(owner.toString('utf8')).token === record.token)
|
|
153
|
+
retire(lfs, layout, dir, ownership, new Set([ownerFile]));
|
|
154
|
+
}
|
|
155
|
+
};
|
|
156
|
+
}
|
|
157
|
+
/** An error `act` threw, carried through the protocol's own error handling untouched. */
|
|
158
|
+
class ActError extends Error {
|
|
159
|
+
inner;
|
|
160
|
+
constructor(inner) {
|
|
161
|
+
super('act failed');
|
|
162
|
+
this.inner = inner;
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
exports.ActError = ActError;
|
|
166
|
+
/**
|
|
167
|
+
* Claim a dead owner's immutable generation without deleting or replacing its lock, run `act`, and retire the lock.
|
|
168
|
+
* Without a lock, `act` runs under a fresh acquisition (`fresh`). An error `act` throws arrives as ActError, so the
|
|
169
|
+
* caller can tell it from the protocol's own.
|
|
170
|
+
*/
|
|
171
|
+
function recoverOwnedLock(lfs, layout, policy, act, fresh) {
|
|
172
|
+
const run = () => { try {
|
|
173
|
+
return act();
|
|
174
|
+
}
|
|
175
|
+
catch (e) {
|
|
176
|
+
throw new ActError(e);
|
|
177
|
+
} };
|
|
178
|
+
const dir = lfs.directory(path.join(layout.parent, layout.name));
|
|
179
|
+
if (!lfs.stat(dir)) {
|
|
180
|
+
const release = fresh();
|
|
181
|
+
try {
|
|
182
|
+
return run();
|
|
183
|
+
}
|
|
184
|
+
finally {
|
|
185
|
+
release();
|
|
186
|
+
}
|
|
187
|
+
}
|
|
188
|
+
const directory = lfs.stat(dir), records = [], tokens = new Set();
|
|
189
|
+
let file = path.join(dir, 'owner.json');
|
|
190
|
+
for (let depth = 0; depth < 128; depth++) {
|
|
191
|
+
const bytes = lfs.readBytes(file);
|
|
192
|
+
let owner;
|
|
193
|
+
try {
|
|
194
|
+
owner = JSON.parse(bytes?.toString('utf8') ?? 'null');
|
|
195
|
+
}
|
|
196
|
+
catch {
|
|
197
|
+
throw new LockError('unknown-owner', 'inspect', 'Malformed lock ownership must be preserved.');
|
|
198
|
+
}
|
|
199
|
+
const first = records.length === 0;
|
|
200
|
+
if (!policy.valid(owner, first) || (first && owner.released) || tokens.has(owner.token)) {
|
|
201
|
+
throw new LockError('unknown-owner', 'inspect', 'Invalid or cyclic lock ownership must be preserved.');
|
|
202
|
+
}
|
|
203
|
+
tokens.add(owner.token);
|
|
204
|
+
records.push(file);
|
|
205
|
+
if (!owner.released)
|
|
206
|
+
policy.judgeDead(owner, first);
|
|
207
|
+
const legacySuccessor = path.join(dir, 'successor-' + owner.token + '.json');
|
|
208
|
+
const claims = lfs.directory(layout.claims, true);
|
|
209
|
+
const externalSuccessor = path.join(claims, 'successor-' + owner.token + '.json');
|
|
210
|
+
if (lfs.stat(legacySuccessor) && lfs.stat(externalSuccessor))
|
|
211
|
+
throw new LockError('unknown-owner', 'inspect', 'Conflicting ownership generations must be preserved.');
|
|
212
|
+
const successor = lfs.stat(legacySuccessor) ? legacySuccessor : externalSuccessor;
|
|
213
|
+
if (lfs.stat(successor)) {
|
|
214
|
+
file = successor;
|
|
215
|
+
continue;
|
|
216
|
+
}
|
|
217
|
+
const claim = policy.claim(owner.token);
|
|
218
|
+
const claimText = JSON.stringify(claim);
|
|
219
|
+
const successorRelative = path.relative(lfs.directory('.'), successor);
|
|
220
|
+
try {
|
|
221
|
+
lfs.publish(successorRelative, claimText);
|
|
222
|
+
}
|
|
223
|
+
catch (e) {
|
|
224
|
+
if (e.code === 'EEXIST')
|
|
225
|
+
throw new LockError('lock-busy', 'recover-claim', 'Another recovery owns this generation.');
|
|
226
|
+
throw e;
|
|
227
|
+
}
|
|
228
|
+
records.push(successor);
|
|
229
|
+
try {
|
|
230
|
+
const current = lfs.stat(dir);
|
|
231
|
+
if (current?.dev !== directory.dev || current?.ino !== directory.ino)
|
|
232
|
+
throw new LockError('unknown-owner', 'inspect', 'Lock directory changed during recovery claim.');
|
|
233
|
+
// Only known generation files and their same-inode publication hardlinks belong to us. External generation
|
|
234
|
+
// claims survive retirement so delayed contenders cannot claim an old token against a newer directory at the
|
|
235
|
+
// reused active path.
|
|
236
|
+
const localRecords = records.filter(r => path.dirname(r) === dir);
|
|
237
|
+
const owned = new Set(localRecords);
|
|
238
|
+
const inodes = localRecords.map(r => lfs.stat(r));
|
|
239
|
+
for (const name of lfs.list(dir)) {
|
|
240
|
+
const candidate = path.join(dir, name);
|
|
241
|
+
if (owned.has(candidate))
|
|
242
|
+
continue;
|
|
243
|
+
const s = lfs.stat(candidate);
|
|
244
|
+
if (s && lfs.isOwnTransient(name) && s.isFile() && !s.isSymbolicLink() && inodes.some(i => i.dev === s.dev && i.ino === s.ino))
|
|
245
|
+
owned.add(candidate);
|
|
246
|
+
else
|
|
247
|
+
throw new LockError('cleanup-conflict', 'retire', 'Unknown lock contents are preserved for inspection.');
|
|
248
|
+
}
|
|
249
|
+
const result = run();
|
|
250
|
+
retire(lfs, layout, dir, directory, owned);
|
|
251
|
+
return result;
|
|
252
|
+
}
|
|
253
|
+
catch (e) {
|
|
254
|
+
// A failed live recovery must not strand its PID as an active owner forever. Mark only our generation released;
|
|
255
|
+
// another claimant appends a new generation.
|
|
256
|
+
const now = lfs.readBytes(successor);
|
|
257
|
+
if (now?.toString('utf8') === claimText)
|
|
258
|
+
lfs.replace(successorRelative, claimText, JSON.stringify({ ...claim, released: true }));
|
|
259
|
+
throw e;
|
|
260
|
+
}
|
|
261
|
+
}
|
|
262
|
+
throw new LockError('unknown-owner', 'inspect', 'Recovery ownership chain exceeds the supported inspection bound.');
|
|
263
|
+
}
|
|
@@ -0,0 +1,126 @@
|
|
|
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.plainLockFs = plainLockFs;
|
|
37
|
+
// @implements A-SPEC-794.6
|
|
38
|
+
/**
|
|
39
|
+
* The plain LockFs of the owned-lock protocol under one root (moved out of request-lock.ts by A-SPEC-794.6): canonical
|
|
40
|
+
* relative locators, no symlinked directories, regular files only, exclusive publication. spend-lock.ts keeps its own
|
|
41
|
+
* copy until A-SPEC-245.x is next amended (backlog).
|
|
42
|
+
*/
|
|
43
|
+
const fs = __importStar(require("node:fs"));
|
|
44
|
+
const path = __importStar(require("node:path"));
|
|
45
|
+
const node_crypto_1 = require("node:crypto");
|
|
46
|
+
const owned_lock_1 = require("./owned-lock");
|
|
47
|
+
function plainLockFs(root, isOwnTransient) {
|
|
48
|
+
const stat = (file) => {
|
|
49
|
+
try {
|
|
50
|
+
return fs.lstatSync(file);
|
|
51
|
+
}
|
|
52
|
+
catch (e) {
|
|
53
|
+
if (e.code === 'ENOENT')
|
|
54
|
+
return undefined;
|
|
55
|
+
throw e;
|
|
56
|
+
}
|
|
57
|
+
};
|
|
58
|
+
const directory = (relative, create = false) => {
|
|
59
|
+
let current = root;
|
|
60
|
+
for (const part of relative.replace(/\\/g, '/').split('/').filter((p) => p !== '' && p !== '.')) {
|
|
61
|
+
if (part === '..')
|
|
62
|
+
throw new owned_lock_1.LockError('unknown-owner', 'inspect', 'Lock paths must be canonical relative locators.');
|
|
63
|
+
current = path.join(current, part);
|
|
64
|
+
if (create && !stat(current)) {
|
|
65
|
+
try {
|
|
66
|
+
fs.mkdirSync(current);
|
|
67
|
+
}
|
|
68
|
+
catch (e) {
|
|
69
|
+
if (e.code !== 'EEXIST')
|
|
70
|
+
throw e;
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
const s = stat(current);
|
|
74
|
+
if (s && (!s.isDirectory() || s.isSymbolicLink()))
|
|
75
|
+
throw new owned_lock_1.LockError('unknown-owner', 'inspect', 'Lock directories must not be symlinks or non-directories.');
|
|
76
|
+
}
|
|
77
|
+
return current;
|
|
78
|
+
};
|
|
79
|
+
const readBytes = (file) => {
|
|
80
|
+
const s = stat(file);
|
|
81
|
+
if (!s)
|
|
82
|
+
return undefined;
|
|
83
|
+
if (!s.isFile())
|
|
84
|
+
throw new owned_lock_1.LockError('unknown-owner', 'inspect', 'Lock records must be regular files.');
|
|
85
|
+
try {
|
|
86
|
+
return fs.readFileSync(file);
|
|
87
|
+
}
|
|
88
|
+
catch (e) {
|
|
89
|
+
if (e.code === 'ENOENT')
|
|
90
|
+
return undefined;
|
|
91
|
+
throw new owned_lock_1.LockError('unknown-owner', 'inspect', `A lock record that cannot be read (${e.code ?? 'error'}) is preserved for inspection.`);
|
|
92
|
+
}
|
|
93
|
+
};
|
|
94
|
+
return {
|
|
95
|
+
stat, directory, readBytes,
|
|
96
|
+
publish: (relative, bytes) => {
|
|
97
|
+
const dir = directory(path.dirname(relative), true);
|
|
98
|
+
const temp = path.join(dir, `.lock-${(0, node_crypto_1.randomUUID)()}.tmp`);
|
|
99
|
+
fs.writeFileSync(temp, bytes, { flag: 'wx', mode: 0o600 });
|
|
100
|
+
try {
|
|
101
|
+
fs.linkSync(temp, path.join(dir, path.basename(relative)));
|
|
102
|
+
}
|
|
103
|
+
finally {
|
|
104
|
+
fs.unlinkSync(temp);
|
|
105
|
+
}
|
|
106
|
+
},
|
|
107
|
+
rename: (from, to) => fs.renameSync(from, to),
|
|
108
|
+
renameNew: (from, to) => fs.renameSync(from, to),
|
|
109
|
+
appendLine: (file, line) => { directory(path.relative(root, path.dirname(file)), true); fs.appendFileSync(file, line + '\n'); },
|
|
110
|
+
replace: (relative, before, after) => {
|
|
111
|
+
const file = path.join(root, relative);
|
|
112
|
+
if (fs.readFileSync(file, 'utf8') !== before)
|
|
113
|
+
return;
|
|
114
|
+
const temp = `${file}.${(0, node_crypto_1.randomUUID)()}.tmp`;
|
|
115
|
+
fs.writeFileSync(temp, after, { flag: 'wx', mode: 0o600 });
|
|
116
|
+
fs.renameSync(temp, file);
|
|
117
|
+
},
|
|
118
|
+
list: (dir) => fs.readdirSync(dir),
|
|
119
|
+
makeDir: (dir) => fs.mkdirSync(dir),
|
|
120
|
+
writeNew: (file, bytes) => fs.writeFileSync(file, bytes, { flag: 'wx', mode: 0o600 }),
|
|
121
|
+
unlink: (file) => fs.unlinkSync(file),
|
|
122
|
+
removeDir: (dir) => fs.rmdirSync(dir),
|
|
123
|
+
removeTree: (dir) => fs.rmSync(dir, { recursive: true, force: true }),
|
|
124
|
+
isOwnTransient,
|
|
125
|
+
};
|
|
126
|
+
}
|