@holmes-lab/holmes-kit 0.38.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 +370 -6
- package/README.md +58 -40
- 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 +50 -13
- package/dist/holmes/cli/approve.js +260 -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 +45 -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 +206 -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.d.ts +32 -0
- package/dist/holmes/cli/mcp-processes.js +132 -0
- 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 +8 -0
- package/dist/holmes/cli/run-provision.js +325 -0
- 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 +26 -0
- package/dist/holmes/cli/run.js +364 -83
- 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 +31 -0
- package/dist/holmes/governance/approval-queue.js +122 -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/governance/tool-actions.js +2 -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 +70 -10
- package/dist/holmes/guardrail/risk-classifier.d.ts +15 -9
- package/dist/holmes/guardrail/risk-classifier.js +245 -15
- 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.d.ts +6 -1
- package/dist/holmes/guardrail/run-refusals.js +36 -14
- package/dist/holmes/guardrail/run-stages.d.ts +10 -0
- package/dist/holmes/guardrail/run-stages.js +46 -6
- 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 +1167 -168
- package/dist/holmes/hooks/rtm-refresh-child.d.ts +1 -1
- package/dist/holmes/hooks/rtm-refresh-child.js +1 -1
- package/dist/holmes/hooks/session-start.d.ts +5 -0
- package/dist/holmes/hooks/session-start.js +29 -1
- package/dist/holmes/hooks/stop.d.ts +23 -0
- package/dist/holmes/hooks/stop.js +88 -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 +14 -0
- package/dist/holmes/mcp/handlers/approval-ask.js +31 -6
- 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-preflight.d.ts +5 -0
- package/dist/holmes/mcp/handlers/workspace-preflight.js +10 -2
- package/dist/holmes/mcp/handlers/workspace-queries.d.ts +2 -2
- package/dist/holmes/mcp/handlers.d.ts +99 -79
- package/dist/holmes/mcp/handlers.js +93 -25
- 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.d.ts +43 -0
- package/dist/holmes/mcp/server-staleness.js +158 -0
- package/dist/holmes/mcp/server.js +34 -9
- package/dist/holmes/mcp/spec-id-guard.js +1 -1
- package/dist/holmes/mcp/tool-schemas.d.ts +13 -0
- package/dist/holmes/mcp/tool-schemas.js +42 -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/project/workspace-preflight.d.ts +5 -0
- package/dist/holmes/project/workspace-preflight.js +24 -1
- 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 +109 -7
- package/dist/holmes/review/verdicts.js +653 -34
- 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,233 @@
|
|
|
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.INSTANCE_ID_RELPATH = void 0;
|
|
37
|
+
exports.readInstanceId = readInstanceId;
|
|
38
|
+
exports.ensureInstanceId = ensureInstanceId;
|
|
39
|
+
// @implements A-SPEC-794.2, A-SPEC-794.6
|
|
40
|
+
/**
|
|
41
|
+
* This clone's instance id (design draft 4 §1.1): what "issued by this replica" means for approval cycles. The S1
|
|
42
|
+
* cycles that read it were reverted for 0.40.0 (A-SPEC-794.30); the id stays, as the S2 skeleton made it. It is a local fact in `.ax/state/instance-id.json`, never the HOLMES_REPLICA_ID environment
|
|
43
|
+
* value, which a process can set.
|
|
44
|
+
*
|
|
45
|
+
* - The file is `{ v: 1, id, realpath, dev, ino }`, the last three being those of `.ax/state`. A file whose dev and
|
|
46
|
+
* ino do not match was copied or moved with its directory and names another instance: it reads as none. realpath is
|
|
47
|
+
* kept for a reader and not compared, so letter case or a mount path does not change the id (A-SPEC-794.6).
|
|
48
|
+
* - A read never creates it. A missing file is published by a no-clobber link, so two creators agree on one id.
|
|
49
|
+
* - A mismatched file is repaired only under the repair lock `instance-id.lock` (exclusive create; one older than 30 s
|
|
50
|
+
* is taken over by inode). Under the lock the file is judged again through one fd (bytes and fstat), moved aside
|
|
51
|
+
* only while that inode is still at the path, and a moved file that is not the judged one is linked back.
|
|
52
|
+
* - Nothing is created without an existing `.ax`.
|
|
53
|
+
*
|
|
54
|
+
* Limits: a repairer paused past the 30 s takeover can race a new one; the inode checks keep a just-published file,
|
|
55
|
+
* but two ids can then be returned. A file system whose device number changes across mounts renews the id.
|
|
56
|
+
*/
|
|
57
|
+
const fs = __importStar(require("node:fs"));
|
|
58
|
+
const path = __importStar(require("node:path"));
|
|
59
|
+
const node_crypto_1 = require("node:crypto");
|
|
60
|
+
exports.INSTANCE_ID_RELPATH = '.ax/state/instance-id.json';
|
|
61
|
+
const LOCK_RELPATH = '.ax/state/instance-id.lock';
|
|
62
|
+
const LOCK_STALE_MS = 30_000;
|
|
63
|
+
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}$/;
|
|
64
|
+
const lstat = (p) => { try {
|
|
65
|
+
return fs.lstatSync(p);
|
|
66
|
+
}
|
|
67
|
+
catch {
|
|
68
|
+
return undefined;
|
|
69
|
+
} };
|
|
70
|
+
function stateFingerprint(root) {
|
|
71
|
+
const state = path.join(root, '.ax', 'state');
|
|
72
|
+
const s = lstat(state);
|
|
73
|
+
if (!s?.isDirectory())
|
|
74
|
+
return null;
|
|
75
|
+
try {
|
|
76
|
+
return { realpath: fs.realpathSync(state), dev: s.dev, ino: s.ino };
|
|
77
|
+
}
|
|
78
|
+
catch {
|
|
79
|
+
return null;
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
/** The file as one fd sees it: its id when it matches (or null), and the inode that was judged. Absent: undefined. */
|
|
83
|
+
function judge(root) {
|
|
84
|
+
const fp = stateFingerprint(root);
|
|
85
|
+
let fd;
|
|
86
|
+
try {
|
|
87
|
+
fd = fs.openSync(path.join(root, exports.INSTANCE_ID_RELPATH), fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
|
|
88
|
+
}
|
|
89
|
+
catch {
|
|
90
|
+
return undefined;
|
|
91
|
+
}
|
|
92
|
+
try {
|
|
93
|
+
const st = fs.fstatSync(fd);
|
|
94
|
+
let r = null;
|
|
95
|
+
try {
|
|
96
|
+
r = JSON.parse(fs.readFileSync(fd, 'utf8'));
|
|
97
|
+
}
|
|
98
|
+
catch {
|
|
99
|
+
r = null;
|
|
100
|
+
}
|
|
101
|
+
const o = (typeof r === 'object' && r !== null ? r : {});
|
|
102
|
+
const ok = fp !== null && o.v === 1 && typeof o.id === 'string' && UUID_V4.test(o.id) && o.dev === fp.dev && o.ino === fp.ino;
|
|
103
|
+
return { id: ok ? o.id : null, ino: st.ino, dev: st.dev };
|
|
104
|
+
}
|
|
105
|
+
finally {
|
|
106
|
+
fs.closeSync(fd);
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
/** The instance id, or null when it is absent, malformed or another directory's. Never writes. */
|
|
110
|
+
function readInstanceId(root) {
|
|
111
|
+
return judge(root)?.id ?? null;
|
|
112
|
+
}
|
|
113
|
+
/** Publish a new id by link; true when it is in place, false when another file took the name first. */
|
|
114
|
+
function publish(root, hooks) {
|
|
115
|
+
const fp = stateFingerprint(root);
|
|
116
|
+
if (!fp)
|
|
117
|
+
throw new Error('.ax/state is not a directory; no instance id is created.');
|
|
118
|
+
const temp = path.join(root, '.ax', 'state', `.instance-id.${(0, node_crypto_1.randomUUID)()}.tmp`);
|
|
119
|
+
fs.writeFileSync(temp, JSON.stringify({ v: 1, id: (0, node_crypto_1.randomUUID)(), ...fp }), { flag: 'wx', mode: 0o600 });
|
|
120
|
+
try {
|
|
121
|
+
hooks.beforePublish?.();
|
|
122
|
+
fs.linkSync(temp, path.join(root, exports.INSTANCE_ID_RELPATH));
|
|
123
|
+
return true;
|
|
124
|
+
}
|
|
125
|
+
catch (e) {
|
|
126
|
+
if (e.code === 'EEXIST')
|
|
127
|
+
return false;
|
|
128
|
+
throw e;
|
|
129
|
+
}
|
|
130
|
+
finally {
|
|
131
|
+
try {
|
|
132
|
+
fs.unlinkSync(temp);
|
|
133
|
+
}
|
|
134
|
+
catch { /* removed already */ }
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
/** Run `fn` under the repair lock, or answer null when another repairer holds it. */
|
|
138
|
+
function underRepairLock(root, fn) {
|
|
139
|
+
const lock = path.join(root, LOCK_RELPATH);
|
|
140
|
+
let fd;
|
|
141
|
+
try {
|
|
142
|
+
fd = fs.openSync(lock, 'wx', 0o600);
|
|
143
|
+
}
|
|
144
|
+
catch (e) {
|
|
145
|
+
if (e.code !== 'EEXIST')
|
|
146
|
+
throw e;
|
|
147
|
+
const s = lstat(lock);
|
|
148
|
+
if (s && Date.now() - s.mtimeMs > LOCK_STALE_MS) {
|
|
149
|
+
// take over an abandoned lock: only the inode judged stale is removed
|
|
150
|
+
const again = lstat(lock);
|
|
151
|
+
if (again && again.ino === s.ino && again.dev === s.dev) {
|
|
152
|
+
try {
|
|
153
|
+
fs.unlinkSync(lock);
|
|
154
|
+
}
|
|
155
|
+
catch { /* raced */ }
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
return null;
|
|
159
|
+
}
|
|
160
|
+
fs.closeSync(fd);
|
|
161
|
+
const mine = lstat(lock);
|
|
162
|
+
try {
|
|
163
|
+
return fn();
|
|
164
|
+
}
|
|
165
|
+
finally {
|
|
166
|
+
const now = lstat(lock);
|
|
167
|
+
if (now && mine && now.ino === mine.ino && now.dev === mine.dev) {
|
|
168
|
+
try {
|
|
169
|
+
fs.unlinkSync(lock);
|
|
170
|
+
}
|
|
171
|
+
catch { /* gone */ }
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
/** Move the judged inode aside; a file that is not the judged one is linked back. */
|
|
176
|
+
function setAside(root, judged) {
|
|
177
|
+
const file = path.join(root, exports.INSTANCE_ID_RELPATH);
|
|
178
|
+
const aside = `${file}.stale-${(0, node_crypto_1.randomUUID)()}`;
|
|
179
|
+
try {
|
|
180
|
+
fs.renameSync(file, aside);
|
|
181
|
+
}
|
|
182
|
+
catch {
|
|
183
|
+
return;
|
|
184
|
+
}
|
|
185
|
+
const moved = lstat(aside);
|
|
186
|
+
if (moved && (moved.dev !== judged.dev || moved.ino !== judged.ino)) {
|
|
187
|
+
try {
|
|
188
|
+
fs.linkSync(aside, file);
|
|
189
|
+
fs.unlinkSync(aside);
|
|
190
|
+
}
|
|
191
|
+
catch { /* a newer file is in place; this one stays aside */ }
|
|
192
|
+
}
|
|
193
|
+
}
|
|
194
|
+
/** This clone's instance id, created when absent or mismatched. Refuses without an existing `.ax`. */
|
|
195
|
+
function ensureInstanceId(root, hooks = {}) {
|
|
196
|
+
if (!lstat(path.join(root, '.ax'))?.isDirectory())
|
|
197
|
+
throw new Error('An instance id is created only inside an existing .ax directory.');
|
|
198
|
+
const state = path.join(root, '.ax', 'state');
|
|
199
|
+
if (!lstat(state)) {
|
|
200
|
+
try {
|
|
201
|
+
fs.mkdirSync(state);
|
|
202
|
+
}
|
|
203
|
+
catch (e) {
|
|
204
|
+
if (e.code !== 'EEXIST')
|
|
205
|
+
throw e;
|
|
206
|
+
}
|
|
207
|
+
}
|
|
208
|
+
for (let attempt = 0; attempt < 200; attempt++) {
|
|
209
|
+
const seen = judge(root);
|
|
210
|
+
if (seen?.id)
|
|
211
|
+
return seen.id;
|
|
212
|
+
if (seen === undefined) {
|
|
213
|
+
publish(root, hooks);
|
|
214
|
+
continue;
|
|
215
|
+
}
|
|
216
|
+
underRepairLock(root, () => {
|
|
217
|
+
const now = judge(root);
|
|
218
|
+
if (now === undefined || now.id !== null)
|
|
219
|
+
return;
|
|
220
|
+
hooks.beforeAside?.();
|
|
221
|
+
setAside(root, now);
|
|
222
|
+
if (judge(root) === undefined)
|
|
223
|
+
publish(root, hooks);
|
|
224
|
+
});
|
|
225
|
+
if (attempt > 0) {
|
|
226
|
+
try {
|
|
227
|
+
Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5);
|
|
228
|
+
}
|
|
229
|
+
catch { /* retry */ }
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
throw new Error('The instance id kept changing under this process; no id is returned.');
|
|
233
|
+
}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
export declare const IDENTITY_TIMEOUT_MS = 1000;
|
|
2
|
+
export interface IdentityDeps {
|
|
3
|
+
platform: NodeJS.Platform;
|
|
4
|
+
exec: (file: string, args: string[], opts: {
|
|
5
|
+
timeout: number;
|
|
6
|
+
env: Record<string, string>;
|
|
7
|
+
encoding: 'utf8';
|
|
8
|
+
stdio: ['ignore', 'pipe', 'ignore'];
|
|
9
|
+
}) => string;
|
|
10
|
+
readFile: (p: string) => string;
|
|
11
|
+
statIno: (p: string) => number;
|
|
12
|
+
/** Windows only: where reg.exe lives. */
|
|
13
|
+
systemRoot?: string;
|
|
14
|
+
/** The clock a null value's retry is timed on. */
|
|
15
|
+
now?: () => number;
|
|
16
|
+
}
|
|
17
|
+
/** 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. */
|
|
18
|
+
export declare const IDENTITY_NULL_RETRY_MS = 60000;
|
|
19
|
+
export interface IdentityReader {
|
|
20
|
+
bootId(): string | null;
|
|
21
|
+
hostId(): string | null;
|
|
22
|
+
}
|
|
23
|
+
export declare function createIdentityReader(deps: IdentityDeps): IdentityReader;
|
|
24
|
+
export declare function bootId(): string | null;
|
|
25
|
+
export declare function hostId(): string | null;
|
|
@@ -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;
|