@edgehero/pi-dispatch 4.3.1 → 5.0.0

package/src/store-version.mjs

@@ -0,0 +1,139 @@
+/**
+ * The one version rule for a store that had no version and may need one (issue #761, `DES-STORE-VERSION-WHEN-NEEDED`).
+ * A LEAF: it imports nothing, so the admin console, the receiver and every worker module can share it.
+ *
+ * A version is an optional integer. A file or job without one is version 1, and a writer writes the LOWEST version its
+ * content needs, which is nothing at all while that is 1: so a store whose content every release can read stays
+ * byte-identical, and an older reader is turned away only by content it would misread. What needs a version is
+ * declared per store in a table, `field -> the version that introduced it`, frozen and empty until a field needs one;
+ * the store's own `*_VERSION` constant is the highest version its build reads and equals the table's largest value
+ * (or 1), which `versionTableProblems` holds every store to.
+ *
+ * Why not stamp the current version on every write: every reader older than the writer would then refuse every file,
+ * including the ones it could read perfectly well. Why not compare release numbers: a release number says nothing
+ * about which fields a file uses, so it refuses too much and protects nothing a field table does not.
+ *
+ * A field table cannot say "this EXISTING field now takes a wider value" (a new condition kind in a list, a new form of
+ * a scope), and an older build meeting such a value refuses it as broken, with no stamp to say an upgrade is the fix. So
+ * a store can also declare a value table, `field -> (value) => the version that value needs`, frozen and empty until a
+ * value needs one, and its writer stamps the version for exactly the values that need it (`valueNeededVersion`).
+ *
+ * Two different failures, told apart on purpose: a version newer than this build reads is not an error in the file
+ * (`newer: true`, the caller defers or refuses with an upgrade to name), while a version that is not an integer of 1
+ * or more is a broken file and keeps that store's ordinary refusal. The broken-file message never repeats the value it
+ * judged, and the newer one names only two integers: the version declared and the one this build reads.
+ */
+
+/**
+ * The problem with a declared version, or null when it is readable here: missing (version 1) or an integer from 1 to
+ * `supported`. `what` names the store in the message ("settings file", "pause windows file", ...).
+ */
+export function versionProblem(declared, { supported, what }) {
+	if (declared === undefined) return null;
+	if (!Number.isSafeInteger(declared) || declared < 1) return { newer: false, message: `${what} "version" must be an integer of 1 or more` };
+	if (declared > supported) return { newer: true, message: `${what} written by a newer pi-dispatch (version ${declared}; this build understands ${supported})` };
+	return null;
+}
+
+/** The lowest version that expresses content using `fields` (an iterable of names): 1 when no field needs more. */
+export function neededVersion(fields, table) {
+	let needed = 1;
+	for (const field of fields ?? []) {
+		if (typeof field === "string" && Object.hasOwn(table, field) && table[field] > needed) needed = table[field];
+	}
+	return needed;
+}
+
+/**
+ * The first field whose version is above the one the file declares (`declared` missing reads as 1), as
+ * `{ field, needs }`, or null. A file that uses such a field without saying so was written by hand or by a writer that
+ * dropped the stamp, and an older reader would read it without the field: refused like a broken file.
+ */
+export function underDeclared(fields, table, declared) {
+	const have = declared === undefined ? 1 : declared;
+	for (const field of fields ?? []) {
+		if (typeof field === "string" && Object.hasOwn(table, field) && table[field] > have) return { field, needs: table[field] };
+	}
+	return null;
+}
+
+/**
+ * The version `value` needs under `field`'s rule in `valueTable`: 1 without an own rule, or when the rule answers no
+ * integer above 1. A rule that THROWS answers 1 too: it runs over a file's raw content, and a value it was not written
+ * for (a `null` where it expects a list) is the store's own validator's to judge, never a reason to crash the reader.
+ */
+function ruleVersion(valueTable, field, value) {
+	if (!Object.hasOwn(valueTable, field) || typeof valueTable[field] !== "function") return 1;
+	let needs;
+	try {
+		needs = valueTable[field](value);
+	} catch {
+		return 1;
+	}
+	return Number.isSafeInteger(needs) && needs > 1 ? needs : 1;
+}
+
+/**
+ * The lowest version that expresses the VALUES of `record`'s own fields under `valueTable` (`field -> (value) =>
+ * version`, for a wider range of an existing field): the highest version any rule answers, 1 when none answers an
+ * integer above 1. A field-name table says which fields need a version; this says which values of a field do.
+ */
+export function valueNeededVersion(record, valueTable) {
+	let needed = 1;
+	if (record === null || typeof record !== "object") return needed;
+	for (const field of Object.keys(record)) {
+		const needs = ruleVersion(valueTable, field, record[field]);
+		if (needs > needed) needed = needs;
+	}
+	return needed;
+}
+
+/**
+ * The first own field of `record` whose value needs a version above the declared one (`declared` missing reads as 1),
+ * as `{ field, needs }`, or null: `underDeclared` for a value table, refused by the reader for the same reason.
+ */
+export function valueUnderDeclared(record, valueTable, declared) {
+	const have = declared === undefined ? 1 : declared;
+	if (record === null || typeof record !== "object") return null;
+	for (const field of Object.keys(record)) {
+		const needs = ruleVersion(valueTable, field, record[field]);
+		if (needs > have) return { field, needs };
+	}
+	return null;
+}
+
+/**
+ * Every way a store's table breaks the rule, as sentences (empty when it holds): a key that is not a field the store
+ * knows, a value that is not an integer from 2 to the store's version, and a version that is not the table's largest
+ * value (or 1). A store's test calls this with its own table, its known fields and its version.
+ */
+export function versionTableProblems(table, { known, version }) {
+	const problems = [];
+	if (!Object.isFrozen(table)) problems.push("the table is not frozen");
+	const knownSet = new Set(known);
+	let largest = 1;
+	for (const [field, needs] of Object.entries(table)) {
+		if (!knownSet.has(field)) problems.push(`${field} is not a field this store knows`);
+		if (!Number.isSafeInteger(needs) || needs < 2 || needs > version) problems.push(`${field} needs version ${needs}, outside 2 to ${version}`);
+		else if (needs > largest) largest = needs;
+	}
+	if (version !== largest) problems.push(`the store's version is ${version}, but its table's largest value is ${largest}`);
+	return problems;
+}
+
+/**
+ * `versionTableProblems` for a value table, as far as a rule can be judged without running it: frozen, every key a
+ * field the store knows and every value a function, and the store's version an integer of 1 or more. Which versions a
+ * rule answers depends on the value it is given, so the store's test probes each rule with the values that need it.
+ */
+export function valueTableProblems(table, { known, version }) {
+	const problems = [];
+	if (!Object.isFrozen(table)) problems.push("the table is not frozen");
+	const knownSet = new Set(known);
+	for (const [field, rule] of Object.entries(table)) {
+		if (!knownSet.has(field)) problems.push(`${field} is not a field this store knows`);
+		if (typeof rule !== "function") problems.push(`${field}'s rule is not a function of the value`);
+	}
+	if (!Number.isSafeInteger(version) || version < 1) problems.push(`the store's version is ${version}, not an integer of 1 or more`);
+	return problems;
+}

package/src/subscription-config.mjs

@@ -0,0 +1,56 @@
+import * as realFs from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+import { createAuthService, parseAuthConnections } from "./auth-connections.mjs";
+import { makeSubscriptionQuotaStore } from "./subscription-quota.mjs";
+import { makeSubscriptionRuntime } from "./subscription-runtime.mjs";
+import { readOverlayModels } from "./model-endpoints.mjs";
+import { failoverModelView } from "./model-status.mjs";
+import { CONTAINER_GLOBAL_PI_DIR } from "./container-spec.mjs";
+import { readStageManifest, containerPackagePaths } from "./packages.mjs";
+import { authError } from "./auth-store.mjs";
+import { COMMUNITY_AUTH_ADAPTERS } from "./community-auth-adapters.mjs";
+import { insideDirectory, privateStoreExposed } from "./private-store-boundary.mjs";
+import { isDeterminateFsCode } from "./transient.mjs";
+
+const inside = insideDirectory;
+export function readAuthPolicy(path, { uid = process.getuid?.(), fs = realFs } = {}) {
+	try {
+		const fd = fs.openSync(path, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+		try {
+			const stat = fs.fstatSync(fd);
+			if (!stat.isFile() || stat.size > 65_536 || (stat.mode & 0o022) !== 0 || (uid !== undefined && stat.uid !== uid && stat.uid !== 0)) throw Object.assign(new Error("the subscription connection policy must be a private, owned regular file"), { code: "auth-policy-invalid" });
+			return parseAuthConnections(fs.readFileSync(fd, "utf8"));
+		} finally { fs.closeSync(fd); }
+	} catch (error) {
+		if (error.code?.startsWith("auth-")) throw error;
+		const transient = !isDeterminateFsCode(error?.code) && !(error instanceof SyntaxError);
+		throw authError(transient ? "auth-policy-unavailable" : "auth-policy-invalid", { transient });
+	}
+}
+
+export function configuredSubscriptions({ config, redis, now = Date.now, adapters, fetch } = {}) {
+	if (!config.authConnectionsFile) return null;
+	const storeDir = config.authStoreDir ?? resolve(dirname(config.settingsFile), "subscription-auth");
+	for (const root of [config.globalPiDir, config.jobsDir, config.sandboxDir]) if (root && privateStoreExposed(root, storeDir)) throw Object.assign(new Error("the private subscription store must be outside every job or overlay root"), { code: "auth-store-location" });
+	const readPolicy = () => readAuthPolicy(config.authConnectionsFile);
+	readPolicy();
+	const auth = createAuthService({ readPolicy, storeDir, host: config.workerName, now, ...(adapters ? { adapters } : {}), ...(fetch ? { fetch } : {}) });
+	if (!redis) return { auth, quota: null, runtime: null, storeDir };
+	const quota = makeSubscriptionQuotaStore({ redis, now });
+	const runtime = makeSubscriptionRuntime({ auth, quota, now, defaultBackend: config.defaultBackend, isPrivateStoreExposed: (job) => job.kind === "local" && privateStoreExposed(job.folder, storeDir), lookup: (provider, id) => failoverModelView(`${provider}/${id}`, { models: readOverlayModels(config.globalPiDir) }), packageRootFor: (adapter) => {
+		const row = readPolicy().connections.find((entry) => entry.adapter === adapter && entry.ownerHost === config.workerName);
+		if (!row?.root || !config.globalPiDir || !inside(resolve(config.globalPiDir, "packages"), row.root)) return null;
+		const root = `${CONTAINER_GLOBAL_PI_DIR}/${relative(config.globalPiDir, row.root).split("\\").join("/")}`;
+		const manifest = readStageManifest({ globalPiDir: config.globalPiDir });
+		if (!manifest || !containerPackagePaths(manifest).includes(root)) return null;
+		if (stagedAuthConflict(manifest, adapter)) return { refused: "auth-adapter-conflicting" };
+		return { root, digest: row.digest };
+	} });
+	return { auth, quota, runtime, storeDir };
+}
+
+/** Both reviewed Claude packages replace the same provider; this conflict is knowable without executing either. */
+export function stagedAuthConflict(manifest, adapter) {
+	const selected = COMMUNITY_AUTH_ADAPTERS[adapter];
+	return selected?.community === true && (manifest?.packages ?? []).filter((row) => COMMUNITY_AUTH_ADAPTERS[`${row.name}@${row.version}`]?.provider === selected.provider).length > 1;
+}

package/src/subscription-limits.mjs

@@ -0,0 +1,3 @@
+/** Shared bounds for reviewed connections, quota persistence and safe status. */
+export const SUBSCRIPTION_CONNECTION_LIMIT = 32;
+export const SUBSCRIPTION_QUOTA_BYTES = 65_536;

package/src/subscription-quota.mjs

@@ -0,0 +1,259 @@
+import { SUBSCRIPTION_QUOTA_BYTES } from "./subscription-limits.mjs";
+/** Subscription evidence is account policy, separate from model cooldowns and dollar reservations. */
+import { createHash, randomUUID } from "node:crypto";
+
+export const SUBSCRIPTION_QUOTA_CODES = Object.freeze(["usage_limit_reached", "usage_not_included", "rate_limit_exceeded", "quota_exhausted"]);
+export const SUBSCRIPTION_QUOTA_REASONS = Object.freeze(["subscription-unknown", "subscription-available", "subscription-trial", "subscription-quota", "subscription-extra-usage", "subscription-stale-evidence", "subscription-stale-state", "subscription-stale-binding", "subscription-observation-required"]);
+export const SUBSCRIPTION_QUOTA_LIMITS = Object.freeze({ payloadBytes: SUBSCRIPTION_QUOTA_BYTES, windows: 64, limits: 32, freshMs: 300_000, casAttempts: 8, resetFutureMs: 32 * 86_400_000 });
+const WINDOWS = ["five-hour", "seven-day", "other"];
+const SOURCES = ["claude-community", "openai", "provider-error"];
+const hash = value => createHash("sha256").update(value).digest("hex");
+const token = value => typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value);
+const instant = value => Number.isSafeInteger(value) && value >= 0 && value <= 253_402_300_799_999;
+const percent = value => typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 10_000 ? value : null;
+const object = value => value !== null && typeof value === "object" && !Array.isArray(value);
+const emptyExtra = () => ({ enabled: null, usedPercent: null, usedCredits: null, monthlyLimit: null, currency: null, decimalPlaces: null });
+function quotaError(code) { return Object.assign(new Error(code), { code }); }
+function boundedObject(raw) {
+	try {
+		const text = typeof raw === "string" ? raw : JSON.stringify(raw);
+		if (typeof text !== "string" || Buffer.byteLength(text) > SUBSCRIPTION_QUOTA_LIMITS.payloadBytes) return null;
+		const parsed = JSON.parse(text);
+		return object(parsed) ? parsed : null;
+	} catch { return null; }
+}
+function atOf(options) {
+	if (!instant(options?.observedAt)) throw quotaError("subscription-invalid-observation");
+	return options.observedAt;
+}
+function reset(value, at, seconds = false) {
+	const parsed = typeof value === "string" && /^\d{4}-\d\d-\d\dT\d\d:\d\d(?::\d\d(?:\.\d{1,3})?)?(?:Z|[+-]\d\d:\d\d)$/.test(value) ? Date.parse(value) : seconds && Number.isSafeInteger(value) ? value * 1000 : null;
+	return instant(parsed) && parsed <= at + SUBSCRIPTION_QUOTA_LIMITS.resetFutureMs ? parsed : null;
+}
+function row(id, window, scope, usedPercent, resetAt, exhausted = false) {
+	return { id, window, scope, usedPercent, resetAt, state: exhausted || usedPercent !== null && usedPercent >= 100 ? "exhausted" : usedPercent === null ? "unknown" : "available" };
+}
+function strongerRow(old, next) {
+	if (old.usedPercent === null || next.usedPercent !== null && next.usedPercent > old.usedPercent) return next;
+	if (next.usedPercent !== old.usedPercent) return old;
+	return { ...old, resetAt: old.resetAt === null || next.resetAt === null ? null : Math.max(old.resetAt, next.resetAt) };
+}
+function extraOf(raw) {
+	const extra = object(raw) ? raw : {};
+	const number = value => typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= Number.MAX_SAFE_INTEGER ? value : null;
+	return { enabled: typeof extra.is_enabled === "boolean" ? extra.is_enabled : null, usedPercent: percent(extra.utilization), usedCredits: number(extra.used_credits), monthlyLimit: number(extra.monthly_limit), currency: typeof extra.currency === "string" && /^[A-Z]{3}$/.test(extra.currency) ? extra.currency : null, decimalPlaces: Number.isInteger(extra.decimal_places) && extra.decimal_places >= 0 && extra.decimal_places <= 4 ? extra.decimal_places : null };
+}
+function completeOf(windows) {
+	return windows.length > 0 && windows.every(value => value.state !== "unknown") && ["five-hour", "seven-day"].every(window => windows.some(value => value.id === window && value.state !== "unknown"));
+}
+function observation(source, at, windows, extraUsage = emptyExtra()) {
+	return { version: 1, source, observedAt: at, complete: completeOf(windows), windows, extraUsage };
+}
+
+/** Fixed fields only. Display labels from the community endpoint are not public identity or authority. */
+export function normalizeClaudeQuota(raw, options) {
+	const at = atOf(options), parsed = boundedObject(raw);
+	const base = new Map(["five-hour", "seven-day"].map(window => [window, row(window, window, "account", null, null)]));
+	const scoped = [];
+	if (!parsed || parsed.limits !== undefined && parsed.limits !== null && (!Array.isArray(parsed.limits) || parsed.limits.length > SUBSCRIPTION_QUOTA_LIMITS.limits)) return observation("claude-community", at, [...base.values()]);
+	for (const [key, window] of [["five_hour", "five-hour"], ["seven_day", "seven-day"]]) {
+		const value = parsed[key];
+		if (object(value)) base.set(window, row(window, window, "account", percent(value.utilization), reset(value.resets_at, at)));
+	}
+	for (const value of parsed.limits ?? []) {
+		if (!object(value)) continue;
+		const window = value.kind === "session" ? "five-hour" : value.group === "weekly" || typeof value.kind === "string" && value.kind.startsWith("weekly") ? "seven-day" : "other";
+		// Unknown model/surface names do not imply a physical model mapping. Their identity is opaque;
+		// without a reviewed mapping, an exhausted scoped limit conservatively blocks this application bucket.
+		const scope = object(value.scope) && (object(value.scope.model) || value.scope.surface !== undefined) || value.kind === "weekly_scoped" ? "scoped" : "account";
+		const id = scope === "account" && window !== "other" ? window : `${window}:${hash(JSON.stringify([value.kind ?? null, value.group ?? null, value.scope ?? null]))}`;
+		const next = row(id, window, scope, percent(value.percent ?? value.utilization), reset(value.resets_at, at));
+		if (scope === "account" && window !== "other") {
+			const old = base.get(window);
+			base.set(window, strongerRow(old, next));
+		} else if (!scoped.some(entry => entry.id === id)) scoped.push(next);
+	}
+	for (const [key, value] of Object.entries(parsed)) {
+		if (!(key === "iguana_necktie" || /^seven_day_[a-z0-9_]{1,64}$/.test(key)) || !object(value)) continue;
+		const id = `seven-day:${hash(key)}`;
+		if (scoped.length >= SUBSCRIPTION_QUOTA_LIMITS.windows - 2) return observation("claude-community", at, [...base.values()]);
+		scoped.push(row(id, "seven-day", "scoped", percent(value.utilization), reset(value.resets_at, at)));
+	}
+	return observation("claude-community", at, [...base.values(), ...scoped], extraOf(parsed.extra_usage));
+}
+
+/** OpenAI App Server's typed rate-limit fields, without interpreting diagnostic prose. */
+export function normalizeOpenAIQuota(raw, options) {
+	const at = atOf(options), parsed = boundedObject(raw);
+	const limits = object(parsed?.rateLimits) ? parsed.rateLimits : parsed;
+	const rows = new Map(["five-hour", "seven-day"].map(window => [window, row(window, window, "account", null, null)]));
+	for (const [key, value] of Object.entries(limits ?? {})) {
+		if (!["primary", "secondary"].includes(key) || !object(value)) continue;
+		const window = value.windowDurationMins === 300 ? "five-hour" : value.windowDurationMins === 10_080 ? "seven-day" : "other";
+		const id = window === "other" ? `other:${key}` : window;
+		const next = row(id, window, "account", percent(value.usedPercent), reset(value.resetsAt, at, true));
+		rows.set(id, rows.has(id) ? strongerRow(rows.get(id), next) : next);
+	}
+	return observation("openai", at, [...rows.values()]);
+}
+
+/** Only a verified transport's closed code/status may establish quota exhaustion. */
+export function normalizeSubscriptionQuotaError(value, options) {
+	const at = atOf(options);
+	if (!object(value) || !["anthropic", "openai", "openai-codex"].includes(value.provider) || !SUBSCRIPTION_QUOTA_CODES.includes(value.code) || value.status === 401 || value.status === 403 || value.status !== undefined && value.status !== 429) return null;
+	const window = WINDOWS.includes(value.window) ? value.window : "other";
+	const resetAt = instant(value.resetAt) && value.resetAt <= at + SUBSCRIPTION_QUOTA_LIMITS.resetFutureMs ? value.resetAt : null;
+	const result = observation("provider-error", at, [row(window === "other" ? "provider-error" : window, window, "account", null, resetAt, true)]);
+	return { ...result, complete: false, code: value.code };
+}
+
+function identityOf(value) {
+	if (!object(value) || !token(value.connectionId) || !token(value.owner) || !token(value.bucket) || typeof value.accountDigest !== "string" || !/^(?:[a-f0-9]{64}|[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12})$/.test(value.accountDigest) || !Number.isSafeInteger(value.generation) || value.generation < 1) throw quotaError("subscription-invalid-binding");
+	return { connectionId: value.connectionId, owner: value.owner, accountDigest: value.accountDigest, bucket: value.bucket, generation: value.generation };
+}
+export function subscriptionQuotaKey(value) {
+	const identity = identityOf(value);
+	return `dispatch:subscription-quota:${hash(JSON.stringify([identity.connectionId, identity.accountDigest, identity.bucket]))}`;
+}
+function cleanObservation(value) {
+	const parsed = boundedObject(value);
+	if (!parsed || parsed.version !== 1 || !SOURCES.includes(parsed.source) || !instant(parsed.observedAt) || !Array.isArray(parsed.windows) || parsed.windows.length > SUBSCRIPTION_QUOTA_LIMITS.windows || typeof parsed.complete !== "boolean") throw quotaError("subscription-invalid-observation");
+	const ids = new Set();
+	const windows = parsed.windows.map(value => {
+		if (!object(value) || !token(value.id) || ids.has(value.id) || !WINDOWS.includes(value.window) || !["account", "scoped"].includes(value.scope) || value.usedPercent !== null && percent(value.usedPercent) === null || value.resetAt !== null && (!instant(value.resetAt) || value.resetAt > parsed.observedAt + SUBSCRIPTION_QUOTA_LIMITS.resetFutureMs) || !["unknown", "available", "exhausted"].includes(value.state)) throw quotaError("subscription-invalid-observation");
+		ids.add(value.id);
+		if (value.state === "available" && (value.usedPercent === null || value.usedPercent >= 100) || value.state === "unknown" && value.usedPercent !== null || value.state === "exhausted" && value.usedPercent !== null && value.usedPercent < 100) throw quotaError("subscription-invalid-observation");
+		return row(value.id, value.window, value.scope, value.usedPercent, value.resetAt, value.state === "exhausted");
+	});
+	const extra = parsed.extraUsage;
+	if (!object(extra)) throw quotaError("subscription-invalid-observation");
+	const normalized = observation(parsed.source, parsed.observedAt, windows, extraOf({ is_enabled: extra.enabled, utilization: extra.usedPercent, used_credits: extra.usedCredits, monthly_limit: extra.monthlyLimit, currency: extra.currency, decimal_places: extra.decimalPlaces }));
+	if (parsed.complete !== normalized.complete) throw quotaError("subscription-invalid-observation");
+	return { ...normalized, ...(parsed.source === "provider-error" && SUBSCRIPTION_QUOTA_CODES.includes(parsed.code) ? { code: parsed.code } : {}) };
+}
+function emptyState(identity) { return { version: 0, identity, source: null, observedAt: null, windows: [], extraUsage: emptyExtra(), trial: null, probeRequired: false, invalidatedAt: null }; }
+function parseState(raw, identity) {
+	if (raw === null || raw === undefined) return emptyState(identity);
+	const value = boundedObject(raw);
+	if (!value || !Number.isSafeInteger(value.version) || value.version < 1 || !instant(value.observedAt) || !Array.isArray(value.windows) || value.windows.length > SUBSCRIPTION_QUOTA_LIMITS.windows || !SOURCES.includes(value.source)) throw quotaError("subscription-store-invalid");
+	try {
+		const bound = identityOf(value.identity);
+		if (subscriptionQuotaKey(bound) !== subscriptionQuotaKey(identity)) throw new Error();
+		const clean = cleanObservation({ version: 1, source: value.source, observedAt: value.observedAt, complete: completeOf(value.windows), windows: value.windows, extraUsage: value.extraUsage });
+		// Stored rows retain their individual observation times when a later partial read omits them.
+		const windows = clean.windows.map((row, index) => {
+			if (!instant(value.windows[index].observedAt) || value.windows[index].observedAt > value.observedAt) throw new Error();
+			return { ...row, observedAt: value.windows[index].observedAt };
+		});
+		if (value.trial !== null && (!object(value.trial) || !/^[a-f0-9-]{36}$/.test(value.trial.id) || value.trial.usedBy !== null && !/^[a-f0-9]{64}$/.test(value.trial.usedBy))) throw new Error();
+		if (value.probeRequired !== undefined && typeof value.probeRequired !== "boolean" || value.probeRequired === true && !instant(value.invalidatedAt)) throw new Error();
+		return { version: value.version, identity: bound, source: value.source, observedAt: value.observedAt, windows, extraUsage: clean.extraUsage, trial: value.trial === null ? null : { id: value.trial.id, usedBy: value.trial.usedBy }, probeRequired: value.probeRequired === true, invalidatedAt: value.probeRequired === true ? value.invalidatedAt : null };
+	} catch { throw quotaError("subscription-store-invalid"); }
+}
+function bindingValid(state, identity) { return identity.generation > state.identity.generation || identity.generation === state.identity.generation && identity.owner === state.identity.owner; }
+function statusOf(state, identity, at) {
+	const windows = state.windows.map(value => ({ ...value, fresh: !state.probeRequired && at - value.observedAt <= SUBSCRIPTION_QUOTA_LIMITS.freshMs && value.observedAt <= at, state: value.state === "exhausted" && (value.resetAt === null || value.resetAt > at) ? "exhausted" : !state.probeRequired && value.state === "available" && value.observedAt <= at && at - value.observedAt <= SUBSCRIPTION_QUOTA_LIMITS.freshMs && (value.resetAt === null || value.resetAt > at) ? "available" : "unknown" }));
+	const blocked = windows.filter(value => value.state === "exhausted");
+	return { connectionId: identity.connectionId, accountDigest: identity.accountDigest, bucket: identity.bucket, generation: state.identity.generation, version: state.version, observedAt: state.observedAt, source: state.source, fresh: !state.probeRequired && state.observedAt !== null && at - state.observedAt <= SUBSCRIPTION_QUOTA_LIMITS.freshMs, bindingValid: bindingValid(state, identity), state: blocked.length ? "exhausted" : windows.length && windows.every(value => value.state === "available") ? "available" : "unknown", until: blocked.length && blocked.every(value => value.resetAt !== null) ? Math.max(...blocked.map(value => value.resetAt)) : null, blockedUnknownReset: blocked.some(value => value.resetAt === null), trialAvailable: state.trial !== null && state.trial.usedBy === null, probeRequired: state.probeRequired, invalidatedAt: state.invalidatedAt, windows, extraUsage: state.probeRequired ? emptyExtra() : state.extraUsage };
+}
+const CAS = `local old = redis.call('GET', KEYS[1]); if (old or '') ~= ARGV[1] then return 0 end; redis.call('SET', KEYS[1], ARGV[2]); return 1`;
+
+/** Bounded GET/CAS only. Exhaustion without a reset has no TTL and cannot disappear through expiry. */
+export function makeSubscriptionQuotaStore({ redis, now = Date.now } = {}) {
+	if (typeof redis?.get !== "function" || typeof redis?.eval !== "function") throw quotaError("subscription-store-unavailable");
+	const readRaw = async identity => {
+		const raw = await redis.get(subscriptionQuotaKey(identity));
+		if (raw !== null && raw !== undefined && (typeof raw !== "string" || Buffer.byteLength(raw) > SUBSCRIPTION_QUOTA_LIMITS.payloadBytes)) throw quotaError("subscription-store-invalid");
+		return { raw: raw ?? "", state: parseState(raw, identity) };
+	};
+	async function mutate(value, fn, { bind = false } = {}) {
+		const identity = identityOf(value);
+		for (let attempt = 0; attempt < SUBSCRIPTION_QUOTA_LIMITS.casAttempts; attempt++) {
+			const { raw, state } = await readRaw(identity), at = now();
+			if (!instant(at)) throw quotaError("subscription-invalid-clock");
+			const status = statusOf(state, identity, at);
+			if (!status.bindingValid) return { ok: false, reason: "subscription-stale-binding", status };
+			let result = fn(state, status, at);
+			// A selected prepare publishes the newer owner/generation even when quota refuses it. Merely
+			// considering a fallback must remain read-only and cannot claim a binding or a person's trial.
+			if (bind && state.version > 0 && identity.generation > state.identity.generation && !result.next) result = { ...result, next: state };
+			if (!result.next) return result;
+			const next = { ...result.next, version: state.version + 1, identity };
+			const serialized = JSON.stringify(next);
+			if (Buffer.byteLength(serialized) > SUBSCRIPTION_QUOTA_LIMITS.payloadBytes) throw quotaError("subscription-store-capacity");
+			if (await redis.eval(CAS, 1, subscriptionQuotaKey(identity), raw, serialized) === 1) {
+				const { next: _next, ...returned } = result;
+				return { ...returned, status: statusOf(next, identity, at) };
+			}
+		}
+		throw quotaError("subscription-store-conflict");
+	}
+	return {
+		async read(value) { const identity = identityOf(value); return statusOf((await readRaw(identity)).state, identity, now()); },
+		async invalidate(value, { observedAt } = {}) {
+			if (!instant(observedAt)) throw quotaError("subscription-invalid-observation");
+			return mutate(value, (state, status, at) => {
+				if (observedAt > at || state.observedAt !== null && observedAt < state.observedAt || state.invalidatedAt !== null && observedAt < state.invalidatedAt) return { ok: false, reason: "subscription-stale-evidence", status };
+				return { ok: true, next: { ...state, source: state.source ?? "provider-error", observedAt: state.observedAt ?? observedAt, probeRequired: true, invalidatedAt: observedAt } };
+			});
+		},
+		async record(value, evidence, { expectedVersion } = {}) {
+			const incoming = cleanObservation(evidence);
+			return mutate(value, (state, status, at) => {
+				if (expectedVersion !== undefined && expectedVersion !== state.version) return { ok: false, reason: "subscription-stale-state", status };
+				const clearsProbe = state.probeRequired && incoming.source !== "provider-error" && expectedVersion === state.version && incoming.observedAt >= state.invalidatedAt;
+				if (state.probeRequired && incoming.source !== "provider-error" && !clearsProbe) return { ok: false, reason: "subscription-stale-state", status };
+				if (incoming.observedAt > at || state.observedAt !== null && incoming.observedAt < state.observedAt) return { ok: false, reason: "subscription-stale-evidence", status };
+				const tied = incoming.observedAt === state.observedAt;
+				if (tied && !clearsProbe && !incoming.windows.some(row => {
+					const old = state.windows.find(value => value.id === row.id);
+					return row.state === "exhausted" && (old?.state !== "exhausted" || old.resetAt !== null && (row.resetAt === null || row.resetAt > old.resetAt));
+				})) return { ok: false, reason: "subscription-stale-evidence", status };
+				const rows = new Map(state.windows.map(row => [row.id, row]));
+				if (incoming.complete && (!tied || clearsProbe)) rows.delete("provider-error");
+				for (const row of incoming.windows) {
+					const old = rows.get(row.id);
+					if (tied && !clearsProbe && row.state !== "exhausted") continue;
+					if (tied && !clearsProbe && old?.state === "exhausted") {
+						rows.set(row.id, { ...row, resetAt: old.resetAt === null || row.resetAt === null ? null : Math.max(old.resetAt, row.resetAt), observedAt: incoming.observedAt });
+						continue;
+					}
+					if (row.state === "unknown" && old?.state === "exhausted") continue;
+					rows.set(row.id, { ...row, observedAt: incoming.observedAt });
+				}
+				if (rows.size > SUBSCRIPTION_QUOTA_LIMITS.windows) throw quotaError("subscription-store-capacity");
+				return { ok: true, next: { ...state, source: incoming.source, observedAt: incoming.observedAt, windows: [...rows.values()], extraUsage: incoming.source === "provider-error" ? state.extraUsage : incoming.extraUsage, trial: null, ...(clearsProbe ? { probeRequired: false, invalidatedAt: null } : {}) } };
+			});
+		},
+		async admit(value, { windows = ["five-hour", "seven-day"], attemptId, consumeTrial = true, allowExtraUsage = false, maxCreditMicros = null, requireExtraUsageKnownDisabled = false } = {}) {
+			if (!Array.isArray(windows) || windows.some(value => !["five-hour", "seven-day"].includes(value)) || new Set(windows).size !== windows.length || allowExtraUsage && (!Number.isSafeInteger(maxCreditMicros) || maxCreditMicros <= 0)) throw quotaError("subscription-invalid-policy");
+			return mutate(value, (state, status) => {
+				if (state.probeRequired) {
+					if (status.state === "exhausted") return { ok: false, reason: "subscription-quota", until: status.until, status };
+					return { ok: consumeTrial === false, reason: "subscription-observation-required", requiresUsage: true, status };
+				}
+				if (requireExtraUsageKnownDisabled && status.extraUsage.enabled !== false && !allowExtraUsage) return { ok: false, reason: "subscription-extra-usage", until: null, status };
+				// Monitoring preferences do not authorize spending against any observed exhausted bucket.
+				const blocked = status.windows.filter(row => row.state === "exhausted");
+				if (blocked.length === 0) return { ok: true, reason: status.state === "unknown" ? "subscription-unknown" : "subscription-available", ...(allowExtraUsage ? { creditCapMicros: maxCreditMicros } : {}), status };
+				if (allowExtraUsage && status.extraUsage.enabled === true) return { ok: true, reason: "subscription-available", creditCapMicros: maxCreditMicros, status };
+				if (blocked.every(row => row.resetAt === null) && state.trial !== null) {
+					if (consumeTrial === false && state.trial.usedBy === null) return { ok: true, reason: "subscription-trial", status };
+					if (typeof attemptId !== "string" || attemptId.length === 0 || attemptId.length > 256) throw quotaError("subscription-invalid-trial");
+					const usedBy = hash(attemptId);
+					if (state.trial.usedBy === usedBy) return { ok: true, reason: "subscription-trial", status };
+					if (state.trial.usedBy === null) return { ok: true, reason: "subscription-trial", next: { ...state, trial: { ...state.trial, usedBy } } };
+				}
+				return { ok: false, reason: "subscription-quota", until: blocked.every(row => row.resetAt !== null) ? Math.max(...blocked.map(row => row.resetAt)) : null, status };
+			}, { bind: consumeTrial !== false });
+		},
+		async grantOneTrial(value, { expectedVersion, actorKind } = {}) {
+			if (actorKind !== "person" || !Number.isSafeInteger(expectedVersion) || expectedVersion < 0) throw quotaError("subscription-trial-person-required");
+			return mutate(value, (state, status) => {
+				if (state.version !== expectedVersion) return { ok: false, reason: "subscription-stale-state", status };
+				if (!status.blockedUnknownReset || status.windows.some(row => row.state === "exhausted" && row.resetAt !== null) || status.trialAvailable) return { ok: false, reason: "subscription-stale-state", status };
+				return { ok: true, next: { ...state, trial: { id: randomUUID(), usedBy: null } } };
+			});
+		},
+	};
+}

package/src/subscription-runtime.mjs

@@ -0,0 +1,123 @@
+import { REASONS } from "./reason-catalog.mjs";
+/** Host-only orchestration. Private snapshots never become job data, run records or telemetry. */
+import { COMMUNITY_AUTH_ADAPTERS } from "./community-auth-metadata.mjs";
+import { builtinModel } from "./model-catalog.mjs";
+import { splitModelEntry } from "./model-ref.mjs";
+import { normalizeClaudeQuota, normalizeOpenAIQuota, normalizeSubscriptionQuotaError } from "./subscription-quota.mjs";
+import { LOCAL_FOLDER_HOLDS_SUBSCRIPTION_AUTH } from "./private-store-boundary.mjs";
+
+// Lifecycle errors remain precise on the host terminal; run records use the closed operator catalog.
+function recordRefusal(value) {
+	if (!value?.reason?.startsWith("auth-") || Object.hasOwn(REASONS, value.reason)) return value;
+	const reason = value.reason.startsWith("auth-adapter-") ? "auth-adapter-unavailable" : value.reason.startsWith("auth-store-") ? "auth-store-unavailable" : value.reason.startsWith("auth-policy-") ? "auth-policy-invalid" : "auth-reauth-required";
+	return { ...value, reason };
+}
+
+export const subscriptionIdentity = (row) => ({ connectionId: row.connectionId ?? row.id, owner: row.ownerHost, accountDigest: row.accountGroup, bucket: `${row.provider}:subscription`, generation: row.generation });
+export function subscriptionRoutes(job) {
+	const refs = new Map();
+	const add = (provider, id) => { if (provider && id) refs.set(`${provider}/${id}`, { provider, id }); };
+	add(job.provider, job.model);
+	for (const entry of job.models ?? []) { const ref = splitModelEntry(entry); if (ref) add(ref.provider, ref.model); }
+	for (const role of [job.watchDecisionModel, job.questionGroupModel, job.answerDecisionModel]) add(role?.provider, role?.id);
+	return [...refs.values()];
+}
+
+export function makeSubscriptionRuntime({ auth, quota, now = Date.now, lookup = builtinModel, packageRootFor = () => null, defaultBackend = "local", isPrivateStoreExposed = () => false } = {}) {
+	async function check(job, { attemptId = null, consumeTrial = false } = {}) {
+		try {
+			if (await isPrivateStoreExposed(job)) return { ok: false, managed: true, reason: LOCAL_FOLDER_HOLDS_SUBSCRIPTION_AUTH };
+		} catch (error) {
+			return { ok: false, managed: true, reason: "auth-store-unavailable", unavailable: error?.transient !== false };
+		}
+		const managed = [];
+		let unmanaged = false;
+		for (const ref of subscriptionRoutes(job)) {
+			const model = lookup(ref.provider, ref.id);
+			const row = await auth.check(ref.provider, { model: ref.id, api: model?.api, baseUrl: model?.baseUrl });
+			if (!row.managed) { unmanaged = true; continue; }
+			if (!row.ok) return row.reason === "auth-owner-host" ? { ok: false, managed: true, wait: "subscription-owner", until: now() + 60_000 } : recordRefusal(row);
+			if (!model?.api || !model?.baseUrl) return { ok: false, managed: true, reason: "auth-model-unverified" };
+			// A finite list fences tools, child sessions and compaction as well as the root call. An unrestricted
+			// subscription job could otherwise switch to an unadmitted provider after this free gate.
+			if (!Array.isArray(job.models) || job.models.length === 0) return { ok: false, managed: true, reason: "auth-route-unbounded" };
+			if (ref.provider === "openai" && (job.watchDecisionModel?.provider === "openai" || job.questionGroupModel?.provider === "openai" || job.answerDecisionModel?.provider === "openai")) return { ok: false, managed: true, reason: "auth-capability-unsupported" };
+			if (["openshell", "openshell-bind"].includes(job.backend ?? defaultBackend) || job.canary === true) return { ok: false, managed: true, reason: "auth-venue-unsupported" };
+			if (ref.provider === "anthropic") {
+				// Excluded by name too (issue #800): the adapter is a staged package, and left out of PI_PACKAGES it would stop the job at its load, inside a started
+				// container with its budget held. `row.adapter` is the policy's key, `pi-anthropic-oauth@0.3.6`, which the loader refuses as an extension's name; a trigger
+				// names the package, as the worker omits it (run-container.mjs) and `isSubscriptionAdapter` reads it, so the key's `package` is what compares.
+				if (job.packages === false || (Array.isArray(job.excludeExtensions) && job.excludeExtensions.includes(COMMUNITY_AUTH_ADAPTERS[row.adapter]?.package))) return { ok: false, managed: true, reason: "auth-adapter-disabled" };
+				const staged = packageRootFor(row.adapter);
+				if (!staged) return { ok: false, managed: true, reason: "auth-adapter-unavailable" };
+				if (staged.refused) return { ok: false, managed: true, reason: staged.refused };
+			}
+			const paid = Number.isSafeInteger(row.extraUsageCreditMicros) && row.extraUsageCreditMicros > 0;
+			if (paid && (!Number.isSafeInteger(job.maxCostMicros) || job.maxCostMicros > row.extraUsageCreditMicros)) return { ok: false, managed: true, reason: "auth-credit-cap-required" };
+			const available = await quota.admit(subscriptionIdentity(row), { attemptId, consumeTrial, windows: row.quotaWindows ?? ["five-hour", "seven-day"], allowExtraUsage: paid, maxCreditMicros: row.extraUsageCreditMicros, requireExtraUsageKnownDisabled: ref.provider === "anthropic" });
+			const needsUsage = ref.provider === "anthropic" && (available.requiresUsage === true || available.status?.fresh === false && available.status?.state !== "exhausted");
+			if (!available.ok && !(consumeTrial === false && needsUsage && available.reason === "subscription-extra-usage" && available.status?.extraUsage?.enabled === null)) return available.reason === "subscription-quota" ? { ...available, managed: true, wait: "subscription-quota", until: available.until ?? now() + 60_000 } : { ...available, managed: true };
+			if (!managed.some((entry) => entry.provider === row.provider)) managed.push({ ...row, needsUsage });
+		}
+		if (managed.length && unmanaged) return { ok: false, managed: true, reason: "auth-mixed-billing" };
+		return { ok: true, managed };
+	}
+	async function prepare(job, { deadlineAt, signal, attemptId } = {}) {
+		const preview = await check(job);
+		if (!preview.ok) return preview;
+		for (const row of preview.managed) if (row.needsUsage) {
+			const result = await usage(row.id, { signal });
+			if (result.kind !== "observation") return { ok: false, managed: true, reason: "auth-usage-unavailable", unavailable: true };
+		}
+		const checked = await check(job, { attemptId, consumeTrial: true });
+		if (!checked.ok) return checked;
+		const snapshots = [];
+		for (const row of checked.managed) {
+			const prepared = await auth.prepareSnapshot(row.provider, { deadlineAt, signal });
+			if (!prepared.ok) return recordRefusal(prepared);
+			if (!prepared.snapshot) return { ok: false, managed: true, reason: "auth-binding-changed" };
+			snapshots.push({ ...prepared.snapshot, ownerHost: row.ownerHost, ...packageRootFor(row.adapter) });
+		}
+		return { ok: true, snapshots };
+	}
+	async function validate(snapshots) {
+		for (const snapshot of snapshots) {
+			if (!(await auth.validateSnapshot(snapshot))) return false;
+			if (snapshot.provider === "anthropic") {
+				const staged = packageRootFor(snapshot.adapter);
+				if (!staged || staged.refused || staged.root !== snapshot.root || staged.digest !== snapshot.digest) return false;
+			}
+		}
+		return true;
+	}
+	async function observe(job, result, snapshots) {
+		if (result?.exitAuth !== "verified" || result?.exitLineCode !== result?.code || result?.aborted === true) return;
+		const snapshot = snapshots.find((row) => row.provider === result.providerFailure?.subscriptionProvider);
+		if (snapshot?.provider === "anthropic" && ["quota-exhausted", "rate-limited"].includes(result.providerFailure?.kind)) {
+			await quota.invalidate(subscriptionIdentity(snapshot), { observedAt: now() });
+			const refreshed = await usage(snapshot.connectionId, { signal: AbortSignal.timeout(15_000) });
+			if (refreshed.kind !== "observation") throw new Error("subscription usage unavailable after throttling");
+			return;
+		}
+		if (!snapshot || result.providerFailure?.kind !== "quota-exhausted" || !result.providerFailure.subscriptionCode) return;
+		const observation = normalizeSubscriptionQuotaError({ provider: snapshot.provider, code: result.providerFailure.subscriptionCode, status: 429, resetAt: result.providerFailure.resetAt }, { observedAt: now() });
+		if (observation) await quota.record(subscriptionIdentity(snapshot), observation);
+	}
+	async function usage(id, options) {
+		const before = (await auth.status()).find((entry) => entry.id === id && entry.active);
+		if (!before?.accountGroup) return { kind: "unavailable", reason: "auth-binding-changed" };
+		const version = (await quota.read(subscriptionIdentity(before))).version;
+		const result = await auth.usage(id, options);
+		if (result.kind !== "observation") return result;
+		const row = (await auth.status()).find((entry) => entry.id === id && entry.active);
+		if (!row || row.provider !== result.provider || row.ownerHost !== result.ownerHost || row.accountGroup !== result.accountGroup || row.generation !== result.generation) return { kind: "unavailable", reason: "auth-binding-changed" };
+		const observation = (row.provider === "anthropic" ? normalizeClaudeQuota : normalizeOpenAIQuota)(result.payload, { observedAt: result.observedAt });
+		const written = await quota.record(subscriptionIdentity(row), observation, { expectedVersion: version });
+		return { kind: written.ok ? "observation" : "unavailable", reason: written.reason ?? null, quota: written.status };
+	}
+	async function status() {
+		const rows = await auth.status();
+		return { state: "ready", partial: false, connections: await Promise.all(rows.map(async (row) => ({ ...row, ...(row.accountGroup ? { quota: await quota.read(subscriptionIdentity(row)) } : {}) }))) };
+	}
+	return { check, prepare, validate, observe, usage, status };
+}