@gadicc/loom 2.3.1 → 2.5.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/.loom-source-manifest.json +10 -1
- package/esm/src/cli/machineSlots.d.ts +149 -0
- package/esm/src/cli/machineSlots.d.ts.map +1 -0
- package/esm/src/cli/machineSlots.js +417 -0
- package/esm/src/cli/machineSlots.js.map +1 -0
- package/esm/src/cli/machineSlotsCommand.d.ts +24 -0
- package/esm/src/cli/machineSlotsCommand.d.ts.map +1 -0
- package/esm/src/cli/machineSlotsCommand.js +431 -0
- package/esm/src/cli/machineSlotsCommand.js.map +1 -0
- package/esm/src/cli/machineSlotsHost.d.ts +50 -0
- package/esm/src/cli/machineSlotsHost.d.ts.map +1 -0
- package/esm/src/cli/machineSlotsHost.js +192 -0
- package/esm/src/cli/machineSlotsHost.js.map +1 -0
- package/esm/src/cli/mod.d.ts.map +1 -1
- package/esm/src/cli/mod.js +39 -1
- package/esm/src/cli/mod.js.map +1 -1
- package/esm/src/cli/testResourceLaunch.d.ts +29 -1
- package/esm/src/cli/testResourceLaunch.d.ts.map +1 -1
- package/esm/src/cli/testResourceLaunch.js +49 -12
- package/esm/src/cli/testResourceLaunch.js.map +1 -1
- package/esm/src/geo/client.d.ts +74 -0
- package/esm/src/geo/client.d.ts.map +1 -0
- package/esm/src/geo/client.js +135 -0
- package/esm/src/geo/client.js.map +1 -0
- package/esm/src/geo/mod.d.ts +5 -0
- package/esm/src/geo/mod.d.ts.map +1 -0
- package/esm/src/geo/mod.js +5 -0
- package/esm/src/geo/mod.js.map +1 -0
- package/esm/src/geo/place.d.ts +28 -0
- package/esm/src/geo/place.d.ts.map +1 -0
- package/esm/src/geo/place.js +41 -0
- package/esm/src/geo/place.js.map +1 -0
- package/esm/src/geo/places.d.ts +16 -0
- package/esm/src/geo/places.d.ts.map +1 -0
- package/esm/src/geo/places.js +154 -0
- package/esm/src/geo/places.js.map +1 -0
- package/esm/src/geo/placesFormat.d.ts +49 -0
- package/esm/src/geo/placesFormat.d.ts.map +1 -0
- package/esm/src/geo/placesFormat.js +38 -0
- package/esm/src/geo/placesFormat.js.map +1 -0
- package/esm/src/geo/preference.d.ts +15 -0
- package/esm/src/geo/preference.d.ts.map +1 -0
- package/esm/src/geo/preference.js +21 -0
- package/esm/src/geo/preference.js.map +1 -0
- package/esm/src/geo/timeZone.d.ts +20 -0
- package/esm/src/geo/timeZone.d.ts.map +1 -0
- package/esm/src/geo/timeZone.js +65 -0
- package/esm/src/geo/timeZone.js.map +1 -0
- package/esm/src/geo/vercel.d.ts +15 -0
- package/esm/src/geo/vercel.d.ts.map +1 -0
- package/esm/src/geo/vercel.js +64 -0
- package/esm/src/geo/vercel.js.map +1 -0
- package/package.json +26 -2
- package/skills/loom/SKILL.md +43 -15
- package/skills/loom/references/verification-workflow.md +128 -0
- package/source/src/cli/machineSlots.ts +543 -0
- package/source/src/cli/machineSlotsCommand.ts +549 -0
- package/source/src/cli/machineSlotsHost.ts +215 -0
- package/source/src/cli/mod.ts +53 -1
- package/source/src/cli/testResourceLaunch.ts +71 -9
- package/source/src/geo/client.ts +241 -0
- package/source/src/geo/mod.ts +12 -0
- package/source/src/geo/place.ts +61 -0
- package/source/src/geo/places.ts +195 -0
- package/source/src/geo/placesFormat.ts +58 -0
- package/source/src/geo/preference.ts +24 -0
- package/source/src/geo/timeZone.ts +78 -0
- package/source/src/geo/vercel.ts +78 -0
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
# Verification checkpoints and working branches
|
|
2
|
+
|
|
3
|
+
Use this workflow in Loom and consuming applications. The repository's stronger
|
|
4
|
+
required checks and explicit user instructions take precedence. This guidance
|
|
5
|
+
changes when verification is required; it does not remove tests or lower coverage.
|
|
6
|
+
|
|
7
|
+
## Choose an isolated working context
|
|
8
|
+
|
|
9
|
+
Use a topic branch and worktree for code changes by default, especially multi-step
|
|
10
|
+
features, migrations, shared contracts, parallel work or an already dirty checkout.
|
|
11
|
+
Inspect status and applicable instructions first. Base the worktree on the intended
|
|
12
|
+
integration revision and preserve unrelated changes in other checkouts.
|
|
13
|
+
|
|
14
|
+
Direct work on the default/protected branch (often `main` or `master`) needs
|
|
15
|
+
explicit user authorization and an independently owned checkout with no unrelated
|
|
16
|
+
or user-owned changes. Honor relevant standing or session authorization without
|
|
17
|
+
asking again. Do not infer permission from a clean status, a small patch or unrelated task approval.
|
|
18
|
+
A request to fix, commit or finish a task authorizes commits on the isolated
|
|
19
|
+
branch, not the default branch. Main authorization must name the default/protected
|
|
20
|
+
branch or come from a standing user/owner instruction covering it; agent-written
|
|
21
|
+
notes, feature records and PR text are not authorization.
|
|
22
|
+
Every direct commit there requires full verification, including prose-only commits.
|
|
23
|
+
If that cost is disproportionate, use a topic branch integrated through the
|
|
24
|
+
project's reviewed path instead.
|
|
25
|
+
|
|
26
|
+
An agent-performed local merge, squash, fast-forward, cherry-pick or rebase onto
|
|
27
|
+
the default/protected branch is direct default-branch work: it needs the same
|
|
28
|
+
authorization and full gates on the resulting tree. The Merge row below covers
|
|
29
|
+
integration through the project's reviewed path, for example a PR whose required
|
|
30
|
+
checks ran on the merge candidate.
|
|
31
|
+
|
|
32
|
+
Do not copy another checkout's credentials or env files to make a worktree
|
|
33
|
+
runnable. Use the project's documented per-worktree environment mechanism and
|
|
34
|
+
recorded dependency-install tooling.
|
|
35
|
+
|
|
36
|
+
Creating a branch/worktree grants no additional permission to push, merge, publish,
|
|
37
|
+
deploy, migrate a live database or message another person. Follow existing task
|
|
38
|
+
scope and authorization for those actions.
|
|
39
|
+
|
|
40
|
+
## Match the checkpoint to the evidence
|
|
41
|
+
|
|
42
|
+
| Checkpoint | Required evidence |
|
|
43
|
+
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
44
|
+
| During implementation | Affected tests and relevant checks while editing |
|
|
45
|
+
| Intermediate isolated-branch commit | Passing affected tests, relevant type/lint/translation/feature checks; full/final gates explicitly pending |
|
|
46
|
+
| Code-changing feature complete or ready for review/merge | Full local suite and repository-required quality/build/runtime gates on the final candidate |
|
|
47
|
+
| Merge to a default/protected branch | Required checks pass for the actual merge candidate; verify the resulting tree when the target moves, unless integration fast-forwards to exactly the tested tree |
|
|
48
|
+
| Direct default/protected-branch commit | Full local suite and required gates on the exact committed content, even for prose |
|
|
49
|
+
| Ordinary prose-only work on a topic branch | Formatting and reference checks; packaged skills/catalog/activation changes also need their relevant tests and package/link checks |
|
|
50
|
+
|
|
51
|
+
Use recorded tooling. Consumers use their authoritative `project.tooling` tasks.
|
|
52
|
+
|
|
53
|
+
Loom's full final gate is `bun run check`: it runs Oxc quality, Bun production
|
|
54
|
+
types/tests, isolated DB/resource fixture contracts, machine-slots contracts
|
|
55
|
+
(`test:slots`), and `deno task check:parity`
|
|
56
|
+
(Deno tests, DB/resource fixtures, browser types and package build). A successful
|
|
57
|
+
run already includes that parity sequence; running `deno task check` afterward
|
|
58
|
+
would duplicate it. `deno task check` alone omits the Bun production/type gates.
|
|
59
|
+
Preserve stronger coverage, integration, native database, bundler, browser, release
|
|
60
|
+
and CI gates. A filtered command returning success proves only its selected scope.
|
|
61
|
+
|
|
62
|
+
Broaden verification earlier when auth, persistence, compiler/format compatibility,
|
|
63
|
+
shared APIs, generated output or uncertain dependencies make local impact hard to
|
|
64
|
+
bound. Do not wait for final review to discover that a new boundary breaks another
|
|
65
|
+
consumer. This is a judgment about impact, not a requirement for a full run after
|
|
66
|
+
every small implementation step.
|
|
67
|
+
|
|
68
|
+
Choose checkpoints around coherent behavior and its tests. An unused helper need
|
|
69
|
+
not become a separate commit/full-verification cycle merely because it was written
|
|
70
|
+
first. Intermediate branch commits may be useful recovery/review checkpoints;
|
|
71
|
+
they do not require declaring a feature complete.
|
|
72
|
+
|
|
73
|
+
## Record what is known
|
|
74
|
+
|
|
75
|
+
For an intermediate checkpoint, record the relevant commands and outcomes and
|
|
76
|
+
state that the full suite/final gates are pending. Do not mark a shared PR ready
|
|
77
|
+
until its completion gates pass. Do not describe a branch checkpoint as fully verified,
|
|
78
|
+
merge-ready or production-ready just because its affected tests pass.
|
|
79
|
+
|
|
80
|
+
"Pending" means not yet run on this candidate; an observed or known failure is
|
|
81
|
+
reported as failing. A recovery checkpoint with failing affected tests needs
|
|
82
|
+
user agreement and that label. A deferred full suite is different from a failing
|
|
83
|
+
required check. Fix failures caused by the change. Disclose known failures and obtain user agreement before
|
|
84
|
+
making an exception to a required gate; never silently skip, weaken assertions,
|
|
85
|
+
raise timeouts, lower thresholds or declare a failing candidate complete.
|
|
86
|
+
|
|
87
|
+
Squash merging is one option when the project wants a fully verified Main
|
|
88
|
+
history while retaining cheap development checkpoints. A merge commit can verify
|
|
89
|
+
its resulting tree, but it does not make every intermediate branch commit fully
|
|
90
|
+
verified or guarantee they all pass a later bisect. Follow the project's chosen
|
|
91
|
+
history policy; this guidance does not authorize a history rewrite.
|
|
92
|
+
|
|
93
|
+
## Reuse evidence for the tree actually being committed
|
|
94
|
+
|
|
95
|
+
Format before final gates. Reuse results only while tested source/configuration,
|
|
96
|
+
generated inputs, dependencies and relevant environment remain unchanged. Later
|
|
97
|
+
code changes or modifying hooks invalidate earlier full/final results. Re-run the
|
|
98
|
+
necessary final gates on the final candidate rather than citing an earlier green
|
|
99
|
+
commit. Ordinary prose means documentation neither shipped nor parsed by
|
|
100
|
+
tools/tests; features.yaml, catalogs and packaged skills are inputs. "Explicitly excluded"
|
|
101
|
+
means excluded by the recorded tooling configuration, not an agent's ad-hoc
|
|
102
|
+
choice. Behavior-affecting packaged guidance uses the feature-completion gate.
|
|
103
|
+
|
|
104
|
+
Compare the index and working content; do not rely on an unstaged fix making tests
|
|
105
|
+
pass. If user-owned changes differ, verify an isolated snapshot of the intended
|
|
106
|
+
commit instead of stashing/resetting those changes. Check the intended base and
|
|
107
|
+
final merge result when integrating, and keep independent repositories' evidence
|
|
108
|
+
and commits separate. Cite CI only when it checked the candidate being merged/
|
|
109
|
+
released. If the target moved, the tested tree is stale unless integration
|
|
110
|
+
fast-forwards to exactly that tree; verify the merge result in an isolated
|
|
111
|
+
worktree or rely on CI that tested it. Updating a shared branch by rebase still
|
|
112
|
+
needs history-rewrite authorization.
|
|
113
|
+
|
|
114
|
+
## Reduce test cost at the correct boundary
|
|
115
|
+
|
|
116
|
+
Use the existing [database test-boundary guidance](../../loom-db/references/test-boundaries.md).
|
|
117
|
+
Plain decisions and orchestration do not all need a database engine; real SQL,
|
|
118
|
+
transactions, constraints and concurrency still need the appropriate backend.
|
|
119
|
+
Preserve production-loader coverage and use discriminating query faults when
|
|
120
|
+
separating a previously database-heavy test. A fake passing on its own is not SQL
|
|
121
|
+
or provider evidence.
|
|
122
|
+
|
|
123
|
+
For worker counts, setup/import/schema cost, caching and isolation experiments,
|
|
124
|
+
follow that existing reference and its recorded evidence before changing tooling.
|
|
125
|
+
|
|
126
|
+
Native browser/provider claims need native evidence, not only parser or DOM
|
|
127
|
+
simulations. Put app-specific contracts near their owning modules and route
|
|
128
|
+
agents there from local instructions.
|
|
@@ -0,0 +1,543 @@
|
|
|
1
|
+
import { spawnSync } from "node:child_process";
|
|
2
|
+
/**
|
|
3
|
+
* Machine-wide CPU slots (`loom-slots-v1`, docs/machine-slots.md): one
|
|
4
|
+
* per-user pool of CPUs shared by every Loom consumer on the machine.
|
|
5
|
+
* Holding a slot is holding an exclusive `flock` on `<dir>/cpu-<id>`; only the
|
|
6
|
+
* wrapper holds it, and the job runs pinned to its grant.
|
|
7
|
+
*/
|
|
8
|
+
import { randomBytes } from "node:crypto";
|
|
9
|
+
import {
|
|
10
|
+
closeSync,
|
|
11
|
+
ftruncateSync,
|
|
12
|
+
readdirSync,
|
|
13
|
+
readSync,
|
|
14
|
+
renameSync,
|
|
15
|
+
statSync,
|
|
16
|
+
unlinkSync,
|
|
17
|
+
writeSync,
|
|
18
|
+
} from "node:fs";
|
|
19
|
+
import { join } from "node:path";
|
|
20
|
+
import process from "node:process";
|
|
21
|
+
import {
|
|
22
|
+
ancestorKeys,
|
|
23
|
+
openPoolFile,
|
|
24
|
+
readProcessStat,
|
|
25
|
+
} from "./machineSlotsHost.ts";
|
|
26
|
+
import { parseCpuList } from "./testResourcePolicy.ts";
|
|
27
|
+
|
|
28
|
+
/** Spec identifier recorded in labels and shown by `loom slots status`. */
|
|
29
|
+
export const SLOTS_SPEC = "loom-slots-v1";
|
|
30
|
+
|
|
31
|
+
/** Exit code `flock(1)` is told to use when the lock is already held. */
|
|
32
|
+
const FLOCK_BUSY = 75;
|
|
33
|
+
|
|
34
|
+
/** A ticket older than this that nobody holds belongs to a dead waiter. */
|
|
35
|
+
const TICKET_GRACE_MS = 2_000;
|
|
36
|
+
|
|
37
|
+
/** Lock operations the grant loop needs; real ones use `flock(1)`. */
|
|
38
|
+
export interface SlotLocks {
|
|
39
|
+
/** Tries to take a slot without waiting; true if it is now held. */
|
|
40
|
+
tryTake(cpu: number): Promise<boolean>;
|
|
41
|
+
/** Gives a held slot back. */
|
|
42
|
+
release(cpu: number): Promise<void>;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/** A job's request: at least `min` CPUs, at most `max`. */
|
|
46
|
+
export interface SlotRequest {
|
|
47
|
+
min: number;
|
|
48
|
+
max: number;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* Parses and clamps `--min`/`--max` against the pool and any known quota.
|
|
53
|
+
* The floor defaults to 2 and the ceiling to `defaultMax` (never below the
|
|
54
|
+
* floor); both are clamped to what the pool and quota allow.
|
|
55
|
+
*/
|
|
56
|
+
export function resolveSlotRequest(
|
|
57
|
+
pool: number,
|
|
58
|
+
min: string | undefined,
|
|
59
|
+
max: string | undefined,
|
|
60
|
+
options: { defaultMax?: number; quota?: number } = {},
|
|
61
|
+
): SlotRequest {
|
|
62
|
+
const parse = (value: string | undefined, name: string) => {
|
|
63
|
+
if (value === undefined) return undefined;
|
|
64
|
+
if (!/^\d+$/.test(value) || Number(value) < 1)
|
|
65
|
+
throw new Error(`--${name} must be a positive whole number`);
|
|
66
|
+
return Number(value);
|
|
67
|
+
};
|
|
68
|
+
const limit = Math.min(pool, options.quota ?? pool);
|
|
69
|
+
if (limit < 1) throw new Error("The slot pool is empty");
|
|
70
|
+
const requestedMax = parse(max, "max");
|
|
71
|
+
// Without --min, the default floor never exceeds a given --max.
|
|
72
|
+
const floor = Math.min(
|
|
73
|
+
parse(min, "min") ?? Math.min(2, requestedMax ?? 2),
|
|
74
|
+
limit,
|
|
75
|
+
);
|
|
76
|
+
if (requestedMax !== undefined && requestedMax < floor)
|
|
77
|
+
throw new Error("--max must not be below --min");
|
|
78
|
+
const ceiling = Math.min(
|
|
79
|
+
requestedMax ?? Math.max(floor, options.defaultMax ?? Math.ceil(pool / 2)),
|
|
80
|
+
limit,
|
|
81
|
+
);
|
|
82
|
+
return { min: floor, max: ceiling };
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/**
|
|
86
|
+
* Orders the pool for scanning. With hybrid core types it interleaves them in
|
|
87
|
+
* proportion (one performance core to about three efficiency cores here), so
|
|
88
|
+
* each grant gets its share of fast cores; otherwise ascending CPU id. The
|
|
89
|
+
* order never affects which CPUs are shared, only which a job gets first.
|
|
90
|
+
*/
|
|
91
|
+
export function scanOrder(
|
|
92
|
+
pool: readonly number[],
|
|
93
|
+
coreTypes: readonly string[],
|
|
94
|
+
): number[] {
|
|
95
|
+
const sorted = [...pool].sort((a, b) => a - b);
|
|
96
|
+
let groups: number[][];
|
|
97
|
+
try {
|
|
98
|
+
const inPool = new Set(sorted);
|
|
99
|
+
groups = coreTypes
|
|
100
|
+
.map((text) => parseCpuList(text).filter((cpu) => inPool.has(cpu)))
|
|
101
|
+
.filter((group) => group.length > 0);
|
|
102
|
+
} catch {
|
|
103
|
+
return sorted;
|
|
104
|
+
}
|
|
105
|
+
const covered = new Set(groups.flat());
|
|
106
|
+
if (groups.length < 2 || covered.size !== sorted.length) return sorted;
|
|
107
|
+
const taken = groups.map(() => 0);
|
|
108
|
+
const order: number[] = [];
|
|
109
|
+
while (order.length < sorted.length) {
|
|
110
|
+
// Next from the type furthest behind its share; ties go to the first type.
|
|
111
|
+
let best = -1;
|
|
112
|
+
for (let index = 0; index < groups.length; index++) {
|
|
113
|
+
if (taken[index] >= groups[index].length) continue;
|
|
114
|
+
if (
|
|
115
|
+
best < 0 ||
|
|
116
|
+
taken[index] / groups[index].length < taken[best] / groups[best].length
|
|
117
|
+
)
|
|
118
|
+
best = index;
|
|
119
|
+
}
|
|
120
|
+
order.push(groups[best][taken[best]++]);
|
|
121
|
+
}
|
|
122
|
+
return order;
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
/**
|
|
126
|
+
* One pass over the pool in scan order, taking free slots until `max` are
|
|
127
|
+
* held. Fewer than `min` gives every slot back at once, so a job never holds
|
|
128
|
+
* slots while it waits; enough is topped up by one more pass for slots freed
|
|
129
|
+
* meanwhile.
|
|
130
|
+
*/
|
|
131
|
+
export async function scanForGrant(
|
|
132
|
+
pool: readonly number[],
|
|
133
|
+
request: SlotRequest,
|
|
134
|
+
locks: SlotLocks,
|
|
135
|
+
): Promise<number[] | null> {
|
|
136
|
+
const held: number[] = [];
|
|
137
|
+
const pass = async () => {
|
|
138
|
+
for (const cpu of pool) {
|
|
139
|
+
if (held.length >= request.max) return;
|
|
140
|
+
if (!held.includes(cpu) && (await locks.tryTake(cpu))) held.push(cpu);
|
|
141
|
+
}
|
|
142
|
+
};
|
|
143
|
+
await pass();
|
|
144
|
+
if (held.length < request.min) {
|
|
145
|
+
for (const cpu of held) await locks.release(cpu);
|
|
146
|
+
return null;
|
|
147
|
+
}
|
|
148
|
+
if (held.length < request.max) await pass();
|
|
149
|
+
return held;
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
/**
|
|
153
|
+
* Takes a non-blocking exclusive `flock` on an open descriptor through
|
|
154
|
+
* util-linux `flock(1)`, which receives it as fd 3. The lock belongs to the
|
|
155
|
+
* open file description, so it stays with `fd` after `flock(1)` exits.
|
|
156
|
+
*/
|
|
157
|
+
export function flockDescriptor(
|
|
158
|
+
fd: number,
|
|
159
|
+
flockPath = "flock",
|
|
160
|
+
): "taken" | "busy" | "interrupted" | "unavailable" {
|
|
161
|
+
const result = spawnSync(
|
|
162
|
+
flockPath,
|
|
163
|
+
[
|
|
164
|
+
"--nonblock",
|
|
165
|
+
"--exclusive",
|
|
166
|
+
"--conflict-exit-code",
|
|
167
|
+
String(FLOCK_BUSY),
|
|
168
|
+
"3",
|
|
169
|
+
],
|
|
170
|
+
{ stdio: ["ignore", "ignore", "ignore", fd] },
|
|
171
|
+
);
|
|
172
|
+
if (result.error) return "unavailable";
|
|
173
|
+
// A terminal's Ctrl-C reaches flock(1) too; that is an interrupt, not a fault.
|
|
174
|
+
if (result.signal) return "interrupted";
|
|
175
|
+
if (result.status === 0) return "taken";
|
|
176
|
+
if (result.status === FLOCK_BUSY) return "busy";
|
|
177
|
+
return "unavailable";
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
/** What a slot or ticket file says about its holder while it is locked. */
|
|
181
|
+
export interface SlotLabel {
|
|
182
|
+
spec: typeof SLOTS_SPEC;
|
|
183
|
+
kind: "slot" | "ticket";
|
|
184
|
+
lease: string;
|
|
185
|
+
pid: number;
|
|
186
|
+
/** The holder's start time from `/proc/<pid>/stat`, so a reused pid is not taken for it. */
|
|
187
|
+
pidStart: string | null;
|
|
188
|
+
label: string;
|
|
189
|
+
startedAt: string;
|
|
190
|
+
request?: SlotRequest;
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
/** Writes a label over a held file's contents. */
|
|
194
|
+
export function writeLabel(fd: number, label: SlotLabel): void {
|
|
195
|
+
ftruncateSync(fd, 0);
|
|
196
|
+
writeSync(fd, JSON.stringify(label), 0);
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
/** Reads a label from an open descriptor; anything unexpected is null. */
|
|
200
|
+
export function readLabel(fd: number): SlotLabel | null {
|
|
201
|
+
const buffer = Buffer.alloc(4096);
|
|
202
|
+
const length = readSync(fd, buffer, 0, buffer.length, 0);
|
|
203
|
+
try {
|
|
204
|
+
const value = JSON.parse(buffer.subarray(0, length).toString("utf8"));
|
|
205
|
+
if (
|
|
206
|
+
value?.spec === SLOTS_SPEC &&
|
|
207
|
+
(value.kind === "slot" || value.kind === "ticket") &&
|
|
208
|
+
typeof value.lease === "string" &&
|
|
209
|
+
Number.isSafeInteger(value.pid) &&
|
|
210
|
+
typeof value.label === "string" &&
|
|
211
|
+
typeof value.startedAt === "string"
|
|
212
|
+
)
|
|
213
|
+
return value as SlotLabel;
|
|
214
|
+
} catch {
|
|
215
|
+
/* An empty or partly written file has no label. */
|
|
216
|
+
}
|
|
217
|
+
return null;
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
/** Whether a label's holder is still the process that wrote it. */
|
|
221
|
+
export function holderAlive(label: SlotLabel): boolean {
|
|
222
|
+
const stat = readProcessStat(label.pid);
|
|
223
|
+
return Boolean(
|
|
224
|
+
stat && (label.pidStart === null || stat.start === label.pidStart),
|
|
225
|
+
);
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
/** A new label for this process. */
|
|
229
|
+
export function ownLabel(
|
|
230
|
+
kind: SlotLabel["kind"],
|
|
231
|
+
lease: string,
|
|
232
|
+
text: string,
|
|
233
|
+
request?: SlotRequest,
|
|
234
|
+
): SlotLabel {
|
|
235
|
+
return {
|
|
236
|
+
spec: SLOTS_SPEC,
|
|
237
|
+
kind,
|
|
238
|
+
lease,
|
|
239
|
+
pid: process.pid,
|
|
240
|
+
pidStart: readProcessStat(process.pid)?.start ?? null,
|
|
241
|
+
label: text,
|
|
242
|
+
startedAt: new Date().toISOString(),
|
|
243
|
+
...(request ? { request } : {}),
|
|
244
|
+
};
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
/** A fresh random lease id. */
|
|
248
|
+
export function newLease(): string {
|
|
249
|
+
return randomBytes(9).toString("base64url");
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
/** Raised when a signal ends a lock attempt: the caller is being interrupted. */
|
|
253
|
+
export class SlotsInterrupted extends Error {
|
|
254
|
+
constructor() {
|
|
255
|
+
super("interrupted");
|
|
256
|
+
}
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
/** Slot locks on `<dir>/cpu-<id>` files; this process alone holds them. */
|
|
260
|
+
export class FlockSlotLocks implements SlotLocks {
|
|
261
|
+
readonly #dir: string;
|
|
262
|
+
readonly #flock: string;
|
|
263
|
+
readonly #held = new Map<number, number>();
|
|
264
|
+
|
|
265
|
+
constructor(dir: string, flockPath = "flock") {
|
|
266
|
+
this.#dir = dir;
|
|
267
|
+
this.#flock = flockPath;
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
tryTake(cpu: number): Promise<boolean> {
|
|
271
|
+
if (this.#held.has(cpu)) return Promise.resolve(true);
|
|
272
|
+
try {
|
|
273
|
+
const fd = openPoolFile(join(this.#dir, `cpu-${cpu}`)) as number;
|
|
274
|
+
const outcome = flockDescriptor(fd, this.#flock);
|
|
275
|
+
if (outcome === "taken") {
|
|
276
|
+
this.#held.set(cpu, fd);
|
|
277
|
+
return Promise.resolve(true);
|
|
278
|
+
}
|
|
279
|
+
closeSync(fd);
|
|
280
|
+
if (outcome === "unavailable")
|
|
281
|
+
return Promise.reject(new Error("flock(1) is unavailable"));
|
|
282
|
+
if (outcome === "interrupted")
|
|
283
|
+
return Promise.reject(new SlotsInterrupted());
|
|
284
|
+
return Promise.resolve(false);
|
|
285
|
+
} catch (error) {
|
|
286
|
+
return Promise.reject(error);
|
|
287
|
+
}
|
|
288
|
+
}
|
|
289
|
+
|
|
290
|
+
release(cpu: number): Promise<void> {
|
|
291
|
+
const fd = this.#held.get(cpu);
|
|
292
|
+
if (fd !== undefined) {
|
|
293
|
+
this.#held.delete(cpu);
|
|
294
|
+
closeSync(fd);
|
|
295
|
+
}
|
|
296
|
+
return Promise.resolve();
|
|
297
|
+
}
|
|
298
|
+
|
|
299
|
+
/** Labels every held slot. */
|
|
300
|
+
label(label: SlotLabel): void {
|
|
301
|
+
for (const fd of this.#held.values()) writeLabel(fd, label);
|
|
302
|
+
}
|
|
303
|
+
|
|
304
|
+
/** Releases every held slot. */
|
|
305
|
+
releaseAll(): void {
|
|
306
|
+
for (const fd of this.#held.values()) closeSync(fd);
|
|
307
|
+
this.#held.clear();
|
|
308
|
+
}
|
|
309
|
+
}
|
|
310
|
+
|
|
311
|
+
/** One pool file's state: free, or held with the label its holder wrote. */
|
|
312
|
+
export type FileState =
|
|
313
|
+
| { state: "missing" }
|
|
314
|
+
| { state: "free" }
|
|
315
|
+
| { state: "held"; label: SlotLabel | null };
|
|
316
|
+
|
|
317
|
+
/**
|
|
318
|
+
* Probes a pool file without changing who holds it: a free file is locked for
|
|
319
|
+
* a moment and released (a concurrent taker may then see it busy and skip it);
|
|
320
|
+
* a held one has its label read. `whenFree` runs while the probe holds a free
|
|
321
|
+
* file, so a dead ticket can be removed under its own lock.
|
|
322
|
+
*/
|
|
323
|
+
export function probeFile(
|
|
324
|
+
path: string,
|
|
325
|
+
flockPath = "flock",
|
|
326
|
+
whenFree?: () => void,
|
|
327
|
+
): FileState {
|
|
328
|
+
const fd = openPoolFile(path, { existingOnly: true });
|
|
329
|
+
if (fd === null) return { state: "missing" };
|
|
330
|
+
try {
|
|
331
|
+
const outcome = flockDescriptor(fd, flockPath);
|
|
332
|
+
if (outcome === "unavailable") throw new Error("flock(1) is unavailable");
|
|
333
|
+
if (outcome === "interrupted") throw new SlotsInterrupted();
|
|
334
|
+
if (outcome === "taken") {
|
|
335
|
+
whenFree?.();
|
|
336
|
+
return { state: "free" };
|
|
337
|
+
}
|
|
338
|
+
return { state: "held", label: readLabel(fd) };
|
|
339
|
+
} finally {
|
|
340
|
+
closeSync(fd);
|
|
341
|
+
}
|
|
342
|
+
}
|
|
343
|
+
|
|
344
|
+
/** A waiter's place in line, held for as long as it waits. */
|
|
345
|
+
export interface Ticket {
|
|
346
|
+
name: string;
|
|
347
|
+
fd: number;
|
|
348
|
+
}
|
|
349
|
+
|
|
350
|
+
/**
|
|
351
|
+
* Joins the line: creates a ticket under a `pending-` name, locks and labels
|
|
352
|
+
* it, then renames it into the line, so no prober ever sees it unlocked.
|
|
353
|
+
*/
|
|
354
|
+
export function takeTicket(
|
|
355
|
+
dir: string,
|
|
356
|
+
label: SlotLabel,
|
|
357
|
+
flockPath = "flock",
|
|
358
|
+
): Ticket {
|
|
359
|
+
const stem = `${String(Date.now()).padStart(15, "0")}-${process.pid}-${randomBytes(4).toString("hex")}`;
|
|
360
|
+
const pending = join(dir, `pending-${stem}`);
|
|
361
|
+
const fd = openPoolFile(pending, { exclusive: true }) as number;
|
|
362
|
+
const outcome = flockDescriptor(fd, flockPath);
|
|
363
|
+
if (outcome !== "taken") {
|
|
364
|
+
unlinkSync(pending);
|
|
365
|
+
closeSync(fd);
|
|
366
|
+
if (outcome === "interrupted") throw new SlotsInterrupted();
|
|
367
|
+
throw new Error("Could not lock a new ticket");
|
|
368
|
+
}
|
|
369
|
+
writeLabel(fd, label);
|
|
370
|
+
const name = `ticket-${stem}`;
|
|
371
|
+
renameSync(pending, join(dir, name));
|
|
372
|
+
return { name, fd };
|
|
373
|
+
}
|
|
374
|
+
|
|
375
|
+
/** Leaves the line. */
|
|
376
|
+
export function dropTicket(dir: string, ticket: Ticket): void {
|
|
377
|
+
try {
|
|
378
|
+
unlinkSync(join(dir, ticket.name));
|
|
379
|
+
} catch {
|
|
380
|
+
/* Already removed by someone who found it unheld; that cannot happen while held. */
|
|
381
|
+
}
|
|
382
|
+
closeSync(ticket.fd);
|
|
383
|
+
}
|
|
384
|
+
|
|
385
|
+
/** A live waiter, for the head decision and for `status`. */
|
|
386
|
+
export interface Waiter {
|
|
387
|
+
name: string;
|
|
388
|
+
label: SlotLabel | null;
|
|
389
|
+
stopped: boolean;
|
|
390
|
+
}
|
|
391
|
+
|
|
392
|
+
/**
|
|
393
|
+
* Lists live tickets in arrival order. A ticket nobody holds, once past its
|
|
394
|
+
* short creation grace, belongs to a dead waiter and is removed under its own
|
|
395
|
+
* lock. Stopped holders (Ctrl-Z) are marked so they do not block the line.
|
|
396
|
+
*/
|
|
397
|
+
export function liveWaiters(
|
|
398
|
+
dir: string,
|
|
399
|
+
own: string | null,
|
|
400
|
+
flockPath = "flock",
|
|
401
|
+
now = Date.now(),
|
|
402
|
+
): Waiter[] {
|
|
403
|
+
const waiters: Waiter[] = [];
|
|
404
|
+
const all = readdirSync(dir);
|
|
405
|
+
// A pending ticket left by a waiter that died before renaming it.
|
|
406
|
+
for (const name of all.filter((one) => one.startsWith("pending-"))) {
|
|
407
|
+
const path = join(dir, name);
|
|
408
|
+
try {
|
|
409
|
+
if (now - statSync(path).mtimeMs > TICKET_GRACE_MS)
|
|
410
|
+
probeFile(path, flockPath, () => unlinkSync(path));
|
|
411
|
+
} catch {
|
|
412
|
+
/* Gone already, or not ours to judge. */
|
|
413
|
+
}
|
|
414
|
+
}
|
|
415
|
+
const names = all.filter((name) => name.startsWith("ticket-")).sort();
|
|
416
|
+
for (const name of names) {
|
|
417
|
+
const path = join(dir, name);
|
|
418
|
+
if (name === own) {
|
|
419
|
+
waiters.push({ name, label: null, stopped: false });
|
|
420
|
+
continue;
|
|
421
|
+
}
|
|
422
|
+
let old = false;
|
|
423
|
+
try {
|
|
424
|
+
old = now - statSync(path).mtimeMs > TICKET_GRACE_MS;
|
|
425
|
+
} catch {
|
|
426
|
+
continue;
|
|
427
|
+
}
|
|
428
|
+
let state: FileState;
|
|
429
|
+
try {
|
|
430
|
+
state = probeFile(path, flockPath, () => {
|
|
431
|
+
if (old) unlinkSync(path);
|
|
432
|
+
});
|
|
433
|
+
} catch {
|
|
434
|
+
continue;
|
|
435
|
+
}
|
|
436
|
+
if (state.state !== "held") continue;
|
|
437
|
+
const stat = state.label ? readProcessStat(state.label.pid) : null;
|
|
438
|
+
waiters.push({
|
|
439
|
+
name,
|
|
440
|
+
label: state.label,
|
|
441
|
+
stopped: Boolean(stat && (stat.state === "T" || stat.state === "t")),
|
|
442
|
+
});
|
|
443
|
+
}
|
|
444
|
+
return waiters;
|
|
445
|
+
}
|
|
446
|
+
|
|
447
|
+
/** Whether `own` is first in line among waiters that are not stopped. */
|
|
448
|
+
export function isHead(waiters: readonly Waiter[], own: string): boolean {
|
|
449
|
+
return waiters.find((waiter) => !waiter.stopped)?.name === own;
|
|
450
|
+
}
|
|
451
|
+
|
|
452
|
+
/**
|
|
453
|
+
* Verifies an inherited grant for nesting: every CPU it names is locked, by a
|
|
454
|
+
* live holder whose label carries the same lease, and this process's own
|
|
455
|
+
* affinity lies within it. Returns the grant's CPUs, or null when the
|
|
456
|
+
* variables are absent, stale or forged.
|
|
457
|
+
*/
|
|
458
|
+
export function verifyLease(
|
|
459
|
+
dir: string,
|
|
460
|
+
env: Readonly<Record<string, string | undefined>>,
|
|
461
|
+
inherited: readonly number[],
|
|
462
|
+
flockPath = "flock",
|
|
463
|
+
): number[] | null {
|
|
464
|
+
const lease = env.LOOM_SLOTS_LEASE;
|
|
465
|
+
const listed = env.LOOM_SLOT_CPUS;
|
|
466
|
+
if (!lease || !listed) return null;
|
|
467
|
+
let cpus: number[];
|
|
468
|
+
try {
|
|
469
|
+
cpus = parseCpuList(listed);
|
|
470
|
+
} catch {
|
|
471
|
+
return null;
|
|
472
|
+
}
|
|
473
|
+
if (cpus.length === 0 || !inherited.every((cpu) => cpus.includes(cpu)))
|
|
474
|
+
return null;
|
|
475
|
+
for (const cpu of cpus) {
|
|
476
|
+
let state: FileState;
|
|
477
|
+
try {
|
|
478
|
+
state = probeFile(join(dir, `cpu-${cpu}`), flockPath);
|
|
479
|
+
} catch {
|
|
480
|
+
return null;
|
|
481
|
+
}
|
|
482
|
+
if (
|
|
483
|
+
state.state !== "held" ||
|
|
484
|
+
state.label?.lease !== lease ||
|
|
485
|
+
!holderAlive(state.label)
|
|
486
|
+
)
|
|
487
|
+
return null;
|
|
488
|
+
}
|
|
489
|
+
return cpus;
|
|
490
|
+
}
|
|
491
|
+
|
|
492
|
+
/** `status` view of one CPU in the pool. */
|
|
493
|
+
export interface SlotStatus {
|
|
494
|
+
cpu: number;
|
|
495
|
+
state: "free" | "held" | "unknown";
|
|
496
|
+
label: SlotLabel | null;
|
|
497
|
+
}
|
|
498
|
+
|
|
499
|
+
/** Reads every pool CPU's state for `loom slots status`. */
|
|
500
|
+
export function readSlots(
|
|
501
|
+
dir: string,
|
|
502
|
+
pool: readonly number[],
|
|
503
|
+
flockPath = "flock",
|
|
504
|
+
): SlotStatus[] {
|
|
505
|
+
return pool.map((cpu): SlotStatus => {
|
|
506
|
+
let state: FileState;
|
|
507
|
+
try {
|
|
508
|
+
state = probeFile(join(dir, `cpu-${cpu}`), flockPath);
|
|
509
|
+
} catch {
|
|
510
|
+
return { cpu, state: "unknown", label: null };
|
|
511
|
+
}
|
|
512
|
+
return state.state === "held"
|
|
513
|
+
? { cpu, state: "held", label: state.label }
|
|
514
|
+
: { cpu, state: "free", label: null };
|
|
515
|
+
});
|
|
516
|
+
}
|
|
517
|
+
|
|
518
|
+
/**
|
|
519
|
+
* Finds a grant held by an ancestor of this process among the pool's slots,
|
|
520
|
+
* by matching each holder's pid and start time against this process's
|
|
521
|
+
* `/proc` parent chain. This recognises nesting even when an intermediary
|
|
522
|
+
* scrubbed the grant variables; without it an inner run would queue for CPUs
|
|
523
|
+
* its own ancestor holds and wait forever.
|
|
524
|
+
*/
|
|
525
|
+
export function ancestorGrant(
|
|
526
|
+
dir: string,
|
|
527
|
+
pool: readonly number[],
|
|
528
|
+
flockPath = "flock",
|
|
529
|
+
ancestors: Set<string> = ancestorKeys(),
|
|
530
|
+
): { lease: string; cpus: number[] } | null {
|
|
531
|
+
const byLease = new Map<string, number[]>();
|
|
532
|
+
for (const slot of readSlots(dir, pool, flockPath)) {
|
|
533
|
+
const label = slot.label;
|
|
534
|
+
if (
|
|
535
|
+
slot.state === "held" &&
|
|
536
|
+
label?.kind === "slot" &&
|
|
537
|
+
ancestors.has(`${label.pid}:${label.pidStart}`)
|
|
538
|
+
)
|
|
539
|
+
byLease.set(label.lease, [...(byLease.get(label.lease) ?? []), slot.cpu]);
|
|
540
|
+
}
|
|
541
|
+
const [first] = byLease;
|
|
542
|
+
return first ? { lease: first[0], cpus: first[1] } : null;
|
|
543
|
+
}
|