@edgehero/pi-dispatch 2.1.0 → 3.1.0

package/src/scoped-limits.mjs

@@ -23,21 +23,102 @@
  * worker drops would be a silently WIDENED spend limit. Pause-windows shipping without a version is a
  * sunk decision, not a precedent to extend to enforcement config.
  *
+ * Version 2 (issues #501 part 5, #502 part 6) is exactly that case made real: dollar windows (`dayUsd`,
+ * `weekUsd`, `monthUsd`) on a scope row, and `model:<provider>/<model>` rows carrying those alone. They are
+ * DOLLAR ledgers (dollar-budget.mjs, built here by `dollarCapsFor` and `modelDollarRows`), never job-count ones,
+ * so `budgetCapsFor`, `concurrencyFor` and the mutex never see them.
+ *
+ * Issue #498 adds the forge-qualified scope (`github:acme/web`), which names one forge's repo where a bare
+ * `acme/web` names that repo on every forge. A job matches its qualified row first, then its bare row, and a file
+ * holding both for one repo is refused. EVERY key (the job-count windows, the dollar windows, the in-process slot and
+ * the fleet lease) is built from the MATCHED ROW's scope, never from the job's, so a bare row keeps exactly the key
+ * it always had and a qualified row counts on its own.
+ *
+ * Issue #499 part B adds the project row (`project:<id>`, the id from projects.json; version 2). It carries the job-count windows,
+ * `concurrent` and the dollar windows, and it caps every member of the project as one: a job reserves in
+ * its repo or folder row, then its project's row, then the global windows (`scopedLedgers`), and its keys are built from
+ * the project ROW's scope like every other row's, so a project needs no keyspace of its own.
+ *
  * Custom: scoped limits validated inline per triggers.mjs/pause-windows.mjs precedent; zod not in deps
  */
 
-import { createHash } from "node:crypto";
 import { existsSync as fsExistsSync, readFileSync as fsReadFileSync } from "node:fs";
 import { isAbsolute, resolve } from "node:path";
 import { configError } from "./config.mjs";
-import { scopeOf } from "./pause-windows.mjs";
+import { DOLLAR_KEY_PREFIX } from "./dollar-budget.mjs";
+import { hash16 } from "./fleet-lease.mjs";
+import { splitModelEntry } from "./model-ref.mjs";
+import { formatMicros, parseUsdMicros } from "./money.mjs";
+import { parseScopeString, qualifiedScopeOf, scopeOf } from "./pause-windows.mjs";
+import { PROJECT_ID_RE, isProjectId } from "./project-id.mjs";
 
-/** The schema version this build reads and writes. A file declaring a higher one is refused loudly. */
-export const SCOPED_LIMITS_VERSION = 1;
+/**
+ * The highest schema version this build reads. A file declaring a higher one is refused loudly. The admin writes the
+ * LOWEST version that expresses a file (`scopedLimitsVersionFor`), so a file with no dollar or model row stays 1.
+ *
+ * Version 2 (issues #501 part 5 and #502 part 6) adds dollar windows: `dayUsd`, `weekUsd` and `monthUsd` on a repo or
+ * folder row, and `model:<provider>/<model>` rows that carry those three fields only. A version 1 file that uses
+ * either is refused with an error naming version 2: a version 1 worker drops unknown fields, so a file that says 1
+ * while it means 2 would read as a narrower cap on one build and no cap on another.
+ *
+ * A forge-qualified row (`github:acme/web`, issue #498) needs version 2 as well, for the same reason: every released
+ * build reads `github:acme/web` as a plain repo string no job ever has, so a version 1 file holding one would be a
+ * cap, a concurrency limit and a lease that one build enforces and another silently ignores. Version 2 makes every
+ * older build refuse the file loudly instead.
+ */
+export const SCOPED_LIMITS_VERSION = 2;
 
-/** The four limit fields a row may carry, in display order. */
+/** The four job-count limit fields a row may carry, in display order. */
 const LIMIT_FIELDS = ["day", "week", "month", "concurrent"];
 
+/** The three dollar window fields (version 2), in display order. Each maps to a dollar window: day, week, month. */
+export const USD_LIMIT_FIELDS = Object.freeze(["dayUsd", "weekUsd", "monthUsd"]);
+
+/**
+ * The scope prefix of a per-model row (issue #502 part 6): `model:<provider>/<model>`. Reserved in BOTH versions. A
+ * version 1 file naming it is refused (naming version 2) rather than read as a folder called `model:...`.
+ */
+export const MODEL_SCOPE_PREFIX = "model:";
+
+/** The dollar key prefix of a repo or folder row: `budget:usd:s:<hash16>` (the deployment's is `budget:usd`). */
+export const SCOPE_DOLLAR_KEY_PREFIX = `${DOLLAR_KEY_PREFIX}:s`;
+/** The dollar key prefix of a model row: `budget:usd:mdl:<hash16>`. */
+export const MODEL_DOLLAR_KEY_PREFIX = `${DOLLAR_KEY_PREFIX}:mdl`;
+
+/** A scope that LOOKS like a model row (any case, `models`, spaces before the colon) but is not the exact prefix form. */
+const MODEL_NEAR_MISS = /^models?\s*:/i;
+
+/**
+ * The scope prefix of a project row (issue #499 part B): `project:<id>`, the id from projects.json. A project row needs
+ * version 2 in EVERY field, its job counts and `concurrent` included, for the forge-qualified row's reason: the last
+ * released build (2.1.0) reads `project:shop` as a plain repo string no job has, so a version 1 file holding one would
+ * be a cap and a concurrency limit that one build enforces and another silently drops. Version 2 makes that build
+ * refuse the file as newer instead.
+ */
+export const PROJECT_SCOPE_PREFIX = "project:";
+/** A scope that LOOKS like a project row (any case, `projects`, spaces before the colon). Only the exact form parses. */
+const PROJECT_NEAR_MISS = /^projects?\s*:/i;
+
+/** Is this row scope a per-model row? */
+export function isModelScope(scope) {
+	return typeof scope === "string" && scope.startsWith(MODEL_SCOPE_PREFIX);
+}
+
+/** Is this row scope a project row? */
+export function isProjectScope(scope) {
+	return typeof scope === "string" && scope.startsWith(PROJECT_SCOPE_PREFIX);
+}
+
+/** The row scope of a project: `project:<id>`. Every key of a project row hashes this string. */
+export function projectScope(id) {
+	return `${PROJECT_SCOPE_PREFIX}${id}`;
+}
+
+/** A row that is never a job's own scope: a model row or a project row. `limitFor` and the scope advisories skip them. */
+function isGroupScope(scope) {
+	return isModelScope(scope) || isProjectScope(scope);
+}
+
 function isNonEmptyString(value) {
 	return typeof value === "string" && value.trim() !== "";
 }
@@ -75,7 +156,8 @@ export function canonicalScope(job) {
 
 /**
  * Parse, validate, and normalize the scoped-limits file TEXT. Returns the normalized `limits` array
- * (every row rebuilt as an explicit `{ scope, day, week, month, concurrent }` literal, `null` for absent
+ * (every row rebuilt as an explicit `{ scope, day, week, month, concurrent }` literal in a version 1 file, and
+ * `{ scope, day, week, month, concurrent, dayUsd, weekUsd, monthUsd }` in a version 2 one, `null` for absent
  * fields, unknown fields dropped -- the operator-file policy). Throws `configError` (fail-loud) on any
  * malformed entry. `path` is for error messages only -- this function touches no filesystem.
  */
@@ -91,7 +173,7 @@ export function parseScopedLimits(text, path) {
 	}
 	const version = parsed.version;
 	if (!Number.isInteger(version) || version < 1) {
-		throw configError(`scoped-limits file must have "version": 1 (an integer >= 1): ${path}`);
+		throw configError(`scoped-limits file must have "version": 1 or ${SCOPED_LIMITS_VERSION} (an integer >= 1): ${path}`);
 	}
 	if (version > SCOPED_LIMITS_VERSION) {
 		throw configError(`scoped-limits file written by a newer pi-dispatch (version ${version}; this build understands ${SCOPED_LIMITS_VERSION}): ${path}`);
@@ -99,26 +181,98 @@ export function parseScopedLimits(text, path) {
 	if (!Array.isArray(parsed.limits)) {
 		throw configError(`scoped-limits file must have a "limits" array: ${path}`);
 	}
-	const rows = parsed.limits.map((row, index) => normalizeLimit(row, index, path));
+	const rows = parsed.limits.map((row, index) => normalizeLimit(row, index, path, version));
+	refuseMixedForms(rows, path);
 	const seen = new Map();
 	rows.forEach((row, index) => {
-		if (seen.has(row.scope)) {
+		// A model row's identity is its LOWERCASED ref, the one its dollar key hashes (`modelDollarKeyPrefix`): two rows
+		// differing only in case would be two caps on one counter.
+		const id = isModelScope(row.scope) ? row.scope.toLowerCase() : row.scope;
+		if (seen.has(id)) {
 			// Two rows for one scope is a precedence question with no right answer; the admin's
 			// edit-in-place never produces one, so a duplicate is always a hand-edit mistake.
-			throw configError(`scoped limit at index ${index}: duplicate scope ${JSON.stringify(row.scope)} (first at index ${seen.get(row.scope)}): ${path}`);
+			throw configError(`scoped limit at index ${index}: duplicate scope ${JSON.stringify(row.scope)} (first at index ${seen.get(id)}): ${path}`);
 		}
-		seen.set(row.scope, index);
+		seen.set(id, index);
 	});
 	return rows;
 }
 
-function normalizeLimit(row, index, path) {
+/**
+ * A bare row and a qualified row for one repo (`acme/web` beside `github:acme/web`) refuse the file, naming both
+ * indexes (issue #498). Whatever fields either carries, count or dollar: one row applies to a job, and with both forms
+ * present that rule would need a precedence ladder, which reads as one cap while the other silently stops counting.
+ * Refusing is the simpler rule, and it is loud. Two qualified rows for one repo on two forges are fine.
+ */
+function refuseMixedForms(rows, path) {
+	const bare = new Map();
+	rows.forEach((row, index) => {
+		if (!isGroupScope(row.scope) && parseScopeString(row.scope).type === "bare") bare.set(row.scope, index);
+	});
+	rows.forEach((row, index) => {
+		if (isGroupScope(row.scope)) return;
+		const parsed = parseScopeString(row.scope);
+		if (parsed.type !== "qualified" || !bare.has(parsed.repo)) return;
+		const other = bare.get(parsed.repo);
+		throw configError(`scoped limit at index ${index}: ${JSON.stringify(row.scope)} and the bare ${JSON.stringify(parsed.repo)} at index ${other} name the same repo; keep one form (a bare row covers every forge, a qualified row one forge): ${path}`);
+	});
+}
+
+/** A dollar field's value, or the refusal: `parseUsdMicros`'s rules (strings recommended), named by row and field. */
+function usdField(value, field, at, path) {
+	try {
+		return parseUsdMicros(value, field);
+	} catch (error) {
+		throw configError(`${at}: ${error.message}: ${path}`);
+	}
+}
+
+/**
+ * A per-model row (version 2): `{ scope: "model:<provider>/<model>", dayUsd?, weekUsd?, monthUsd? }`. The ref follows
+ * the allowed-model list's rule (`splitModelEntry`: split at the first `/`, each half a valid id). `day`, `week`,
+ * `month` and `concurrent` are refused here: a model is not a scope a job runs IN, so a job-count cap or a
+ * concurrency limit on it would read as enforced while nothing counts it.
+ */
+function normalizeModelLimit(row, trimmed, at, path, version) {
+	if (version < 2) throw configError(`${at}: a "model:" row needs "version": 2 (this file says ${version}): ${path}`);
+	const ref = splitModelEntry(trimmed.slice(MODEL_SCOPE_PREFIX.length));
+	if (ref === null) throw configError(`${at}: a model row's scope must be model:<provider>/<model> (each 1 to 64 characters, no spaces): ${path}`);
+	// The runner folds model-less and overflow calls into an `other/other` usage row, so a row naming that pair
+	// could never be told apart from the fold.
+	if (`${ref.provider}/${ref.model}`.toLowerCase() === "other/other") throw configError(`${at}: model:other/other names the usage ledger's fold row, not a model: ${path}`);
+	for (const field of LIMIT_FIELDS) {
+		if (row[field] !== undefined && row[field] !== null) throw configError(`${at}: a model row carries dayUsd, weekUsd and monthUsd only (${field} is refused): ${path}`);
+	}
+	const norm = { scope: `${MODEL_SCOPE_PREFIX}${ref.provider}/${ref.model}`, day: null, week: null, month: null, concurrent: null, dayUsd: null, weekUsd: null, monthUsd: null };
+	let any = false;
+	for (const field of USD_LIMIT_FIELDS) {
+		if (row[field] === undefined || row[field] === null) continue;
+		norm[field] = formatMicros(usdField(row[field], field, at, path));
+		any = true;
+	}
+	if (!any) throw configError(`${at}: a model row needs at least one of dayUsd, weekUsd, monthUsd: ${path}`);
+	return norm;
+}
+
+function normalizeLimit(row, index, path, version = SCOPED_LIMITS_VERSION) {
 	const at = `scoped limit at index ${index}`;
 	if (row === null || typeof row !== "object" || Array.isArray(row)) {
 		throw configError(`${at}: must be an object: ${path}`);
 	}
 	if (!isNonEmptyString(row.scope)) throw configError(`${at}: scope must be a non-empty string: ${path}`);
 	const trimmed = row.scope.trim().normalize("NFC"); // the same NFC canonicalScope applies job-side
+	if (isModelScope(trimmed)) return normalizeModelLimit(row, trimmed, at, path, version);
+	// A NEAR MISS of a reserved prefix is refused, never read as a repo or folder row (PR #549's review): a
+	// mistyped `Model:openai/x`, `models:...` or `model :...` would otherwise parse as a repo scope no job ever has,
+	// a dollar cap that governs nothing while the file reads as capping a model.
+	if (MODEL_NEAR_MISS.test(trimmed)) throw configError(`${at}: a model row's scope is written exactly model:<provider>/<model> (lowercase "model", no space before the colon): ${path}`);
+	// Issue #499 part B: `project:<id>` is a project row. Exactly that form: a near miss (`Project:shop`, `projects:shop`,
+	// `project :shop`) or a malformed id is refused, never read as a repo row no job has, for the model row's reason.
+	if (PROJECT_NEAR_MISS.test(trimmed)) {
+		const id = trimmed.startsWith(PROJECT_SCOPE_PREFIX) ? trimmed.slice(PROJECT_SCOPE_PREFIX.length) : null;
+		if (id === null) throw configError(`${at}: a project row's scope is written exactly project:<id> (lowercase "project", no space before the colon): ${path}`);
+		if (!isProjectId(id)) throw configError(`${at}: a project row's id must match ${PROJECT_ID_RE.source} (the id in projects.json): ${path}`);
+	}
 	if (trimmed === "*") {
 		// "*" as ONE shared counter is redundant with the global caps, so the only useful reading is a
 		// per-scope default -- the OPPOSITE of what "*" means one file over (pause-windows: one rule
@@ -131,19 +285,42 @@ function normalizeLimit(row, index, path) {
 		// nothing, and a silently inert money limit is the failure class this repo refuses outright.
 		throw configError(`${at}: scopes match exactly; a scope containing "*" is refused (no globs): ${path}`);
 	}
+	// Issue #498: `<forge kind>:<repo>` names one forge's repo; an unknown `<word>:` prefix is refused naming the kinds.
+	// A project row is not a scope string a job carries, so the scope grammar does not apply to it.
+	let form = { type: "project" };
+	if (!isProjectScope(trimmed)) {
+		try {
+			form = parseScopeString(trimmed);
+		} catch (error) {
+			throw configError(`${at}: ${error.message}: ${path}`);
+		}
+	}
+	if (form.type === "project" && version < 2) throw configError(`${at}: a project row needs "version": 2 (this file says ${version}), so a build that predates project rows refuses the file rather than reading an inert repo string: ${path}`);
+	if (form.type === "qualified" && version < 2) throw configError(`${at}: a forge-qualified scope needs "version": 2 (this file says ${version}), so a build that predates it refuses the file rather than reading an inert repo string: ${path}`);
 	const norm = {
 		// An absolute path is stored resolved so a `/srv/site/` row governs `/srv/site` jobs -- the same
 		// collapse canonicalScope applies on the job side. isAbsolute is PLATFORM-NATIVE on purpose, so a
 		// foreign-platform row (a windows drive path on a POSIX worker) stays verbatim and is inert here;
 		// the doctor's unreferenced-scope advisory names it. Resolving it instead would "work" only by
 		// both sides mangling into the same cwd-prefixed string -- a match by accident, not by contract.
-		scope: isAbsolute(trimmed) ? resolve(trimmed) : trimmed,
+		scope: isProjectScope(trimmed) ? trimmed : form.type === "qualified" ? `${form.kind}:${form.repo}` : isAbsolute(trimmed) ? resolve(trimmed) : trimmed,
 		day: null,
 		week: null,
 		month: null,
 		concurrent: null,
+		// Version 2's dollar windows, each the canonical decimal string (`formatMicros`), so the admin's
+		// read-modify-write writes back exactly what the parser accepts. `dollarCapsFor` turns them into integers.
+		// Only in a version 2 file's rows: a version 1 file reads into exactly the five-key literal it always did.
+		...(version >= 2 ? { dayUsd: null, weekUsd: null, monthUsd: null } : {}),
 	};
 	let any = false;
+	for (const field of USD_LIMIT_FIELDS) {
+		const value = row[field];
+		if (value === undefined || value === null) continue;
+		if (version < 2) throw configError(`${at}: ${field} needs "version": 2 (this file says ${version}): ${path}`);
+		norm[field] = formatMicros(usdField(value, field, at, path));
+		any = true;
+	}
 	for (const field of LIMIT_FIELDS) {
 		const value = row[field];
 		// Absent-or-null (subscriptions.mjs's rule): null is the normalizer's OWN output for an unset
@@ -161,7 +338,7 @@ function normalizeLimit(row, index, path) {
 		any = true;
 	}
 	if (!any) {
-		throw configError(`${at}: at least one of day, week, month, concurrent is required (a row that limits nothing is a row an operator sets and then trusts): ${path}`);
+		throw configError(`${at}: at least one of day, week, month, concurrent${version >= 2 ? ", dayUsd, weekUsd, monthUsd" : ""} is required (a row that limits nothing is a row an operator sets and then trusts): ${path}`);
 	}
 	return norm;
 }
@@ -179,24 +356,238 @@ export function loadScopedLimits(config, { readFileSync = fsReadFileSync, exists
 }
 
 /**
- * The exact-match row for a canonical scope, or null. Exact string equality only -- the pause matcher's
- * semantics minus its "*" (refused above). With duplicates refused there is no precedence ladder.
+ * The row that applies to this job, or null. Exact string equality only -- the pause matcher's semantics minus
+ * its "*" (refused above). A forge job matches the row equal to its `qualifiedScopeOf` first (`github:acme/web`),
+ * then the row equal to its canonical bare repo (`acme/web`); a local job matches its resolved folder. With
+ * duplicates refused and a bare row beside a qualified row for one repo refused too, at most one of the two can
+ * exist, so the order is not a precedence ladder: it only says where to look.
+ */
+export function limitFor(limits, job) {
+	if (!Array.isArray(limits)) return null;
+	// A model row is never a job's scope: it caps a model wherever it runs (`modelDollarRows`). Nor is a project row: it
+	// applies through the job's project (`projectRowFor`), never because a scope string happens to equal it.
+	const find = (scope) => (isNonEmptyString(scope) ? limits.find((l) => l.scope === scope && !isGroupScope(l.scope)) ?? null : null);
+	if (job?.kind !== "local") {
+		const qualified = find(qualifiedScopeOf(job));
+		if (qualified !== null) return qualified;
+	}
+	return find(canonicalScope(job));
+}
+
+/**
+ * The scope every per-scope KEY of this job is built from (issue #498): the matched row's scope, or the job's
+ * canonical scope when no row matches. The in-process slot, the fleet lease (`slot:s:<hash16>`), and through
+ * `budgetCapsFor`/`dollarCapsFor` the job-count and dollar windows all hash this one string. Keyed by the ROW, never
+ * the job: a bare `acme/web` row then keeps the exact key it had before qualified scopes existed (its counts carry
+ * over, and the admin, which recomputes keys from rows, keeps reading them), and it stays ONE shared cap across
+ * forges as written. The boot sweeper already hashes row scopes, so the gate and the sweeper are one rule.
  */
-export function limitFor(limits, scope) {
-	if (!Array.isArray(limits) || !isNonEmptyString(scope)) return null;
-	return limits.find((l) => l.scope === scope) ?? null;
+export function rowScopeFor(job, limits) {
+	return limitFor(limits, job)?.scope ?? canonicalScope(job);
 }
 
 /**
  * The scoped budget windows this job reserves against, or null when nothing applies (no row for the
- * scope, or the row is concurrency-only). The returned `scope` is CANONICAL so the redis counters are
- * spelling-stable. Shaped like the global `caps` object so `reserveBudget` consumes it unchanged.
+ * scope, or the row is concurrency-only). The returned `scope` is the MATCHED ROW's (issue #498), so the redis
+ * counters are spelling-stable and a bare row keeps its key. Shaped like the global `caps` object so
+ * `reserveBudget` consumes it unchanged.
  */
 export function budgetCapsFor(job, limits) {
-	const scope = canonicalScope(job);
-	const row = limitFor(limits, scope);
+	const row = limitFor(limits, job);
 	if (!row || (row.day === null && row.week === null && row.month === null)) return null;
-	return { scope, caps: { day: row.day, week: row.week, month: row.month } };
+	return { scope: row.scope, caps: { day: row.day, week: row.week, month: row.month } };
+}
+
+/**
+ * The project row of this project id, or null (no id, or no row for it). A job's project is resolved ONCE at pickup
+ * (`projectOf`, projects.mjs), and every project-row consumer below takes that id, never the job: the gate, the ledgers
+ * and the record then agree for the attempt whatever an operator does to projects.json mid-run.
+ */
+export function projectRowFor(limits, projectId) {
+	if (!Array.isArray(limits) || !isProjectId(projectId)) return null;
+	const scope = projectScope(projectId);
+	return limits.find((l) => l?.scope === scope) ?? null;
+}
+
+/**
+ * The project rows whose id is not a project in `projects` (the parsed projects.json), as `[{ index, id }]` in file
+ * order. Such a row caps nothing (no job can belong to a project that does not exist), so it is a refusal wherever the
+ * two files meet: at boot, on a live reload of either file, and in the admin's write (issue #499 part B).
+ */
+export function danglingProjectRows(limits, projects) {
+	const ids = new Set((Array.isArray(projects) ? projects : []).map((p) => p?.id));
+	const out = [];
+	(Array.isArray(limits) ? limits : []).forEach((row, index) => {
+		if (!isProjectScope(row?.scope)) return;
+		const id = row.scope.slice(PROJECT_SCOPE_PREFIX.length);
+		if (!ids.has(id)) out.push({ index, id });
+	});
+	return out;
+}
+
+/**
+ * Refuse a limits list that names a project `projects` does not have, naming each such row's index and id (ids are
+ * charset-checked, never a path or a name) and BOTH files: the row lives in the scoped-limits file (`limitsPath`), the
+ * missing id in the projects file (`projectsPath`, null when PI_PROJECTS_FILE is unset), so an operator reading a
+ * refused projects.json edit looks for the index in the right file. Pure: the caller decides whether that is a boot
+ * refusal or a kept last-good copy.
+ */
+export function checkProjectRows(limits, projects, limitsPath, projectsPath = null) {
+	const dangling = danglingProjectRows(limits, projects);
+	if (dangling.length === 0) return;
+	const rows = dangling.map((d) => `index ${d.index} ("${PROJECT_SCOPE_PREFIX}${d.id}")`).join(", ");
+	const where = projectsPath ? `the projects file ${projectsPath}` : "the projects file (PI_PROJECTS_FILE is unset, so there are no projects)";
+	throw configError(`scoped-limits row(s) at ${rows} in ${limitsPath} name a project that is not in ${where}; add the project there first, or remove the row`);
+}
+
+/** The refusal reason of a full repo or folder job-count window. */
+export const SCOPE_CAP_REASON = "scope-cap";
+/** The refusal reason of a full project job-count window (issue #499 part B). */
+export const PROJECT_CAP_REASON = "project-cap";
+
+/**
+ * THE ordered job-count ledgers of one job's scoped rows (issue #499 part B), as `[{ scope, keyPrefix, caps, reason }]`:
+ * its repo or folder row, then its project's row. The processor appends the global ledger last and reserves them in
+ * this order through ONE helper (budget.mjs `reserveLedgers`), and gives them back in reverse (`releaseLedgers`).
+ *
+ * Narrowest first, for the reason the scoped ledger always reserved before the global one: a refusal by a narrow
+ * ledger never consumes a slot in a wider one, so a noisy repo cannot drain its project's day, and a full project
+ * cannot drain the deployment's. A row with no day, week or month (concurrency or dollars only) is no ledger here.
+ *
+ * `projectId` is the id resolved at pickup (`projectOf`), or null. One list instead of one hand-built pair per
+ * call site: every release site in the processor walks this list, so a ledger added here cannot be forgotten there.
+ */
+export function scopedLedgers(job, limits, projectId) {
+	const out = [];
+	const scoped = budgetCapsFor(job, limits);
+	if (scoped) out.push({ scope: scoped.scope, keyPrefix: scopeKeyPrefix(scoped.scope), caps: scoped.caps, reason: SCOPE_CAP_REASON });
+	const row = projectRowFor(limits, projectId);
+	if (row && (row.day !== null || row.week !== null || row.month !== null)) {
+		out.push({ scope: row.scope, keyPrefix: scopeKeyPrefix(row.scope), caps: { day: row.day, week: row.week, month: row.month }, reason: PROJECT_CAP_REASON });
+	}
+	return out;
+}
+
+/** A row's dollar windows as integer micro-dollars `{ day, week, month }`, each null when unset, or null when none is. */
+function usdCaps(row) {
+	const caps = {};
+	for (const [field, name] of [["dayUsd", "day"], ["weekUsd", "week"], ["monthUsd", "month"]]) {
+		caps[name] = row?.[field] === null || row?.[field] === undefined ? null : parseUsdMicros(row[field], field);
+	}
+	return caps.day === null && caps.week === null && caps.month === null ? null : caps;
+}
+
+/**
+ * The repo or folder dollar windows this job reserves in (issue #501 part 5), or null when its scope's row has none
+ * (or there is no row). Ledger-shaped for `reserveDollars`: `{ scope, keyPrefix, caps }`, the caps in integer
+ * micro-dollars and `keyPrefix` `budget:usd:s:<hash16>` of the same MATCHED ROW scope the job-count windows hash
+ * (issue #498). A sibling of `budgetCapsFor`: the job-count and dollar windows of one row are separate ledgers.
+ */
+export function dollarCapsFor(job, limits) {
+	const row = limitFor(limits, job);
+	const caps = row ? usdCaps(row) : null;
+	return caps === null ? null : { scope: row.scope, keyPrefix: scopeDollarKeyPrefix(row.scope), caps };
+}
+
+/**
+ * The project dollar windows this job reserves in (issue #499 part B), or null when its project (resolved at pickup) has
+ * no row or the row has no dollar window. Ledger-shaped like `dollarCapsFor`, with `keyPrefix`
+ * `scopeDollarKeyPrefix("project:<id>")`: the project row's own scope, the rule every row's key follows, so no second
+ * dollar keyspace exists for projects.
+ */
+export function projectDollarCapsFor(limits, projectId) {
+	const row = projectRowFor(limits, projectId);
+	const caps = row ? usdCaps(row) : null;
+	return caps === null ? null : { scope: row.scope, keyPrefix: scopeDollarKeyPrefix(row.scope), caps };
+}
+
+/**
+ * The model dollar windows this job reserves in (issue #502 part 6), as ledgers `{ ref, keyPrefix, caps }` in file
+ * order, where `ref` is the row's lowercased `provider/model`. `models` is the job's EFFECTIVE allowed-model list:
+ *   - a list reserves in the rows of its listed models, compared ignoring case (the ledger lowercases ids, so the
+ *     row and the usage row it settles from meet in lowercase);
+ *   - no list (`null` or `undefined`) reserves in EVERY model row. An unrestricted job may switch to any model
+ *     mid-run, so it could spend in any of them; reserving in none would let it run up a model's window unseen.
+ *     This fails closed: an unrestricted job is refused when any model window is full, and the remedy is a list.
+ * A job that reserves nothing at all (the zero-reservation rule, the processor's) reserves in none of these either.
+ */
+export function modelDollarRows(limits, models) {
+	if (!Array.isArray(limits)) return [];
+	const rows = limits.filter((l) => isModelScope(l?.scope));
+	let wanted = null;
+	if (Array.isArray(models)) wanted = new Set(models.filter((m) => typeof m === "string").map((m) => m.toLowerCase()));
+	const out = [];
+	for (const row of rows) {
+		const ref = row.scope.slice(MODEL_SCOPE_PREFIX.length).toLowerCase();
+		if (wanted !== null && !wanted.has(ref)) continue;
+		const caps = usdCaps(row);
+		if (caps !== null) out.push({ ref, keyPrefix: modelDollarKeyPrefix(ref), caps });
+	}
+	return out;
+}
+
+/** A row's kind for the dollar advisories: `model`, `project` (issue #499 part B) or `scope` (a repo or folder). */
+function rowKind(scope) {
+	return isModelScope(scope) ? "model" : isProjectScope(scope) ? "project" : "scope";
+}
+
+/**
+ * The rows that carry a dollar window, as `[{ index, kind }]` (`kind` is `scope`, `project` or `model`), when the deployment has
+ * NO per-job cap (`deploymentMaxCostUsd` null or undefined: env and overlay merged by the caller), else `[]` (PR #549's
+ * review). Such a row refuses every job it applies to as `config-refused` unless the job's trigger sets its own
+ * `run.maxCostUsd`, so the worker and doctor WARN, never refuse: a trigger may legitimately supply the cap. Index and
+ * kind only, never the scope string (a folder scope is a host path).
+ */
+export function dollarRowsWithoutCap(limits, deploymentMaxCostUsd) {
+	if (deploymentMaxCostUsd !== null && deploymentMaxCostUsd !== undefined) return [];
+	const out = [];
+	(limits ?? []).forEach((row, index) => {
+		if (USD_LIMIT_FIELDS.some((f) => row?.[f] !== null && row?.[f] !== undefined)) out.push({ index, kind: rowKind(row.scope) });
+	});
+	return out;
+}
+
+/**
+ * The windows of dollar rows whose cap is BELOW the deployment's per-job cap, as `[{ index, kind, window }]` (PR
+ * #549's review). A job reserves its whole per-job cap, so such a window refuses every job it applies to, every time,
+ * until the cap is raised or the per-job cap lowered (a trigger's smaller `run.maxCostUsd` still fits). Doctor names
+ * them; `[]` when no deployment cap is set or none is below it.
+ */
+export function dollarRowsBelowJobCap(limits, deploymentMaxCostUsd) {
+	if (deploymentMaxCostUsd === null || deploymentMaxCostUsd === undefined) return [];
+	const jobCap = parseUsdMicros(deploymentMaxCostUsd, "maxCostUsd");
+	const out = [];
+	(limits ?? []).forEach((row, index) => {
+		for (const [field, window] of [["dayUsd", "day"], ["weekUsd", "week"], ["monthUsd", "month"]]) {
+			if (row?.[field] === null || row?.[field] === undefined) continue;
+			if (parseUsdMicros(row[field], field) < jobCap) out.push({ index, kind: rowKind(row.scope), window });
+		}
+	});
+	return out;
+}
+
+/**
+ * The lowest file version that expresses `rows` (normalized or as the admin builds them): 2 when any row carries a
+ * dollar field, is a model row, is a project row (issue #499 part B) or has a forge-qualified scope (issue #498), else 1.
+ * The admin writes this, so a file
+ * with bare and folder job-count rows only stays a version 1 file that an older worker still reads.
+ */
+export function scopedLimitsVersionFor(rows) {
+	const v2 = (rows ?? []).some((l) => {
+		const scope = typeof l?.scope === "string" ? l.scope.trim() : l?.scope;
+		return isModelScope(scope) || isProjectScope(scope) || isQualifiedScope(scope) || USD_LIMIT_FIELDS.some((f) => l?.[f] !== null && l?.[f] !== undefined);
+	});
+	return v2 ? 2 : 1;
+}
+
+/** Is this written scope forge-qualified? False for anything `parseScopeString` refuses: the parser names that. */
+function isQualifiedScope(scope) {
+	if (typeof scope !== "string" || scope === "" || isModelScope(scope)) return false;
+	try {
+		return parseScopeString(scope).type === "qualified";
+	} catch {
+		return false;
+	}
 }
 
 /**
@@ -217,7 +608,7 @@ export function concurrencyFor(job, limits) {
 	const scope = canonicalScope(job);
 	if (scope === null) return Infinity;
 	const structural = job?.kind === "local" ? 1 : Infinity;
-	const configured = limitFor(limits, scope)?.concurrent ?? Infinity;
+	const configured = limitFor(limits, job)?.concurrent ?? Infinity;
 	return Math.min(structural, configured);
 }
 
@@ -233,8 +624,37 @@ export function concurrencyFor(job, limits) {
  * accepted cost.
  */
 export function scopeKeyPrefix(scope) {
-	const h = createHash("sha256").update(String(scope)).digest("hex").slice(0, 16);
-	return `budget:s:${h}`;
+	return `budget:s:${hash16(scope)}`;
+}
+
+/** A repo or folder's DOLLAR key prefix: `budget:usd:s:<hash16(scope)>`, the same hash as `scopeKeyPrefix`. */
+export function scopeDollarKeyPrefix(scope) {
+	return `${SCOPE_DOLLAR_KEY_PREFIX}:${hash16(scope)}`;
+}
+
+/**
+ * A model's DOLLAR key prefix: `budget:usd:mdl:<hash16(lowercase provider/model)>`. LOWERCASED before hashing,
+ * because the run record's ledger lowercases ids (`parseExitUsage`) and a model row settles from that ledger: one
+ * model must be one counter whatever case a row, a list or the runner spells it in. `ref` is `provider/model`,
+ * without the `model:` prefix.
+ */
+export function modelDollarKeyPrefix(ref) {
+	return `${MODEL_DOLLAR_KEY_PREFIX}:${hash16(String(ref).toLowerCase())}`;
+}
+
+/** The dollar key prefix of one normalized row, scope or model: what the admin reads its counters under. */
+export function dollarKeyPrefixFor(row) {
+	return isModelScope(row?.scope) ? modelDollarKeyPrefix(row.scope.slice(MODEL_SCOPE_PREFIX.length)) : scopeDollarKeyPrefix(row?.scope);
+}
+
+/**
+ * The rows the boot sweeper walks for this host's stale fleet claims (`makeScopeClaimSweeper`): every row as
+ * `{ concurrent, hash }`, the hash of its ROW scope, the string the pickup gate leases under. A project row's
+ * `concurrent` (issue #499 part B) is leased under `hash16("project:<id>")` and swept under the same hash; a row with no
+ * `concurrent` carries a null count, which the sweeper skips.
+ */
+export function scopeClaimRows(limits) {
+	return (Array.isArray(limits) ? limits : []).map((row) => ({ concurrent: row.concurrent, hash: hash16(row.scope) }));
 }
 
 /**

package/src/service.mjs

@@ -41,7 +41,7 @@
  * the rest of the config is broken.
  */
 import { spawn as nodeSpawn } from "node:child_process";
-import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, realpathSync, unlinkSync, writeFileSync } from "node:fs";
 import { lookup as dnsLookup } from "node:dns/promises";
 import { connect as netConnect } from "node:net";
 import { homedir, networkInterfaces, tmpdir, userInfo } from "node:os";
@@ -51,9 +51,13 @@ import { parseArgs } from "node:util";
 import { parseBackendList, venuesOf } from "./backends.mjs";
 import { sharedShellIgnored } from "./deployment-venue.mjs";
 import { egressArmed, egressProxyName } from "./egress.mjs";
-import { updateEnvFile } from "./env-file.mjs";
+import { ENV_WRITER_FS, updateEnvFile } from "./env-file.mjs";
+import { MODEL_ENDPOINTS_INCLUDE_NAME } from "./model-endpoints.mjs";
 import { VALKEY_HEALTH_SCRIPT, VALKEY_PASSWORD_KEY, VALKEY_START_SCRIPT, dollarsDoubled, newValkeyPassword, valkeyPasswordDecision } from "./valkey-auth.mjs";
-import { ALL_QUADLET_FILES, ALLOWLIST_PLACEHOLDER, NETNS_KEEPER, NETNS_KEEPER_FORMAT, judgeNetnsKeeper, keeperUnderRunningProxyHint, managerEnvRefusal, PROXY_CONF_PLACEHOLDER, QUADLET_FILES, applyStack, decideValkey, describeAction, passwdNameFrom, readSubuidRanges, readValkeyKeys, valkeySharedOn, VALKEY_SHARED_KEY, describeRollBack, journalWrite, rollBackWrites, foreignContainerRefusal, foreignContainers, lingerNote, planStack, proxyConfCopyPath, proxyRestartWarning, quadletDir, readLinger, readStackKeys, stackComponents, unknownContainerRefusal, userBusRefusal, valkeyEnvPath, valkeyPasswordRestartWarning, workerUnitDeps } from "./podman-stack.mjs";
+import { ALL_QUADLET_FILES, ALLOWLIST_PLACEHOLDER, MODEL_ENDPOINTS_PLACEHOLDER, NETNS_KEEPER, NETNS_KEEPER_FORMAT, judgeNetnsKeeper, keeperUnderRunningProxyHint, managerEnvRefusal, PROXY_CONF_PLACEHOLDER, QUADLET_FILES, applyStack, decideValkey, describeAction, passwdNameFrom, readSubuidRanges, readValkeyKeys, valkeySharedOn, VALKEY_SHARED_KEY, describeRollBack, journalWrite, rollBackWrites, foreignContainerRefusal, foreignContainers, lingerNote, planStack, proxyConfCopyPath, proxyRestartWarning, quadletDir, readLinger, readStackKeys, stackComponents, unknownContainerRefusal, userBusRefusal, valkeyEnvPath, valkeyPasswordRestartWarning, workerUnitDeps } from "./podman-stack.mjs";
+
+/** This command's default fs seam: its own calls, and every call the `.env` writer makes (`ENV_WRITER_FS`, issue #522). */
+export const SERVICE_FS = { existsSync, mkdirSync, ...ENV_WRITER_FS };
 
 // src/ is where this module lives in BOTH layouts (worker/src in a checkout,
 // node_modules/@edgehero/pi-dispatch/src under npm). Deploy templates resolve one level up from it
@@ -169,6 +173,7 @@ export const TEMPLATE_PINS = {
 	"pi-dispatch-egress-proxy.container": [
 		`Volume=${PROXY_CONF_PLACEHOLDER}:/etc/squid/squid.conf:ro,z`, // → the account-owned COPY of the package's egress-proxy.conf (~/.config/pi-dispatch/egress-proxy.conf, podman-stack.mjs proxyConfCopyPath), because `z` cannot relabel a root-owned package file (measured)
 		`Volume=${ALLOWLIST_PLACEHOLDER}:/etc/pi-dispatch/allowlist.conf:ro,z`, // → <deployDir>/egress-allowlist.conf, the list `init` scaffolds
+		`Volume=${MODEL_ENDPOINTS_PLACEHOLDER}:/etc/pi-dispatch/model-endpoints.conf:ro,z`, // → <deployDir>/model-endpoints.conf, the include `init` scaffolds and `egress render` rewrites in place (issue #503)
 		"ContainerName=pi-dispatch-egress-proxy",
 		"Network=pi-dispatch-egress-out.network",
 		"WantedBy=default.target",
@@ -343,7 +348,7 @@ export async function runService(argv = [], deps = {}) {
 		// this command. An operator changes it by running the command as someone else, not by declaring it.
 		user = env.USER || userInfo().username,
 		tmp = tmpdir(),
-		fs = { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, chmodSync, statSync, renameSync, realpathSync },
+		fs = SERVICE_FS,
 		spawn = nodeSpawn,
 		out = (s) => process.stdout.write(s),
 		err = (s) => process.stderr.write(s),
@@ -1056,6 +1061,12 @@ async function stackRefusal(ctx, paths, stack) {
 	if (stack.components.proxy && !ctx.fs.existsSync(allowlist)) {
 		blocking.push(`the egress policy is on, and ${allowlist} does not exist: a proxy unit mounting a missing file makes Podman create a DIRECTORY there and squid fail confusingly. Run \`pi-dispatch init\` in ${ctx.deployDir} first (it never overwrites), or set PI_EGRESS=0 in .env to opt out of the policy`);
 	}
+	// Issue #503: the rules include the declared model endpoints' file, and squid will not start when it is missing. Said
+	// only beside an allowlist that exists: without one, the reason above already names `init`, which writes both.
+	const endpointsInclude = join(ctx.deployDir, MODEL_ENDPOINTS_INCLUDE_NAME);
+	if (stack.components.proxy && ctx.fs.existsSync(allowlist) && !ctx.fs.existsSync(endpointsInclude)) {
+		blocking.push(`the egress policy is on, and ${endpointsInclude} does not exist: the proxy's rules include it, and squid will not start without it. Run \`pi-dispatch init\` in ${ctx.deployDir} first (it never overwrites), or set PI_EGRESS=0 in .env to opt out of the policy`);
+	}
 	const bus = stack.plan.actions.length > 0 ? userBusRefusal({ env: ctx.env, user: ctx.user, euid: ctx.euid }) : null;
 	if (bus) blocking.push(bus);
 	// The manager's own XDG_RUNTIME_DIR and XDG_CONFIG_HOME (PR #463 round 3, measured): another account's makes every