Compare commits

...

6 Commits

Author SHA1 Message Date
Quixos Subtree Publisher b406738249 Publish quixos-protocol from 11d2ad06170609a09118cbabd4245b5828a148d1 2026-10-08 18:19:19 +00:00
Timothy J. Aveni 165510341d Repair packed agent startup and bound activation metadata retention 2026-10-08 11:19:19 -07:00
Quixos Subtree Publisher e78b7adf28 Publish quixos-protocol from c4319441699b7b8c5af7e70dade6e4ad8cccddea 2026-10-08 14:59:49 +00:00
Timothy J. Aveni ffd728b061 Keep pin-upgraded workbench paths relative for relocation 2026-10-08 07:59:49 -07:00
Quixos Subtree Publisher e162dc3013 Publish quixos-protocol from e4075003e669be0e307ec8c0585cccb1bd08276a 2026-10-08 14:43:32 +00:00
Timothy J. Aveni a935273913 Use execution workspace review semantics during bottom-up pin upgrades 2026-10-08 07:43:32 -07:00
6 changed files with 236 additions and 30 deletions
+1 -1
View File
@@ -1,7 +1,7 @@
{ {
"version": 1, "version": 1,
"sourceRepo": "https://gitea-external.egads.tutti.syntaxblitz.net/quixos/quixos", "sourceRepo": "https://gitea-external.egads.tutti.syntaxblitz.net/quixos/quixos",
"sourceCommit": "932fe7714761fb8b5db4bd6401357cdff762a428", "sourceCommit": "11d2ad06170609a09118cbabd4245b5828a148d1",
"sourcePath": "quixos-protocol", "sourcePath": "quixos-protocol",
"exportName": "quixos-protocol", "exportName": "quixos-protocol",
"mirrorRemote": "https://gitea-external.egads.tutti.syntaxblitz.net/quixos/quixos-protocol.git" "mirrorRemote": "https://gitea-external.egads.tutti.syntaxblitz.net/quixos/quixos-protocol.git"
+45 -7
View File
@@ -15,7 +15,12 @@ import {
} from "./assembly.js"; } from "./assembly.js";
import { createGitCapabilityResolver } from "./git-resolver.js"; import { createGitCapabilityResolver } from "./git-resolver.js";
import { snapshotCommit, buildImmutableCandidate } from "./checked-build.js"; import { snapshotCommit, buildImmutableCandidate } from "./checked-build.js";
import { planEvolution, type WorkspaceRevision, type EvolutionReview } from "../capability-model/index.js"; import {
planEvolution,
reviewSemanticMajors,
type WorkspaceRevision,
type EvolutionReview,
} from "../capability-model/index.js";
import { withFileLock } from "./file-lock.js"; import { withFileLock } from "./file-lock.js";
const execFile = promisify(callback); const execFile = promisify(callback);
type Source = { repository: string; commit: string }; type Source = { repository: string; commit: string };
@@ -187,6 +192,34 @@ export type UpgradeEffects = {
snapshot(root: string): Promise<string>; snapshot(root: string): Promise<string>;
publish(root: string, commit: string): Promise<void>; publish(root: string, commit: string): Promise<void>;
}; };
/** Review a successfully built immutable candidate using the same boundary as
* ordinary authoring checks. Execution storage compatibility is checked against
* the current graph at activation; the legacy evolution model is not its schema.
*/
export async function reviewUpgradeCandidate({
artifact,
baseline,
candidate,
reviews = [],
}: {
artifact: string;
baseline: WorkspaceRevision | null;
candidate: WorkspaceRevision;
reviews?: EvolutionReview[];
}) {
let execution = false;
try {
await fs.access(path.join(artifact, "execution-plan.json"));
execution = true;
} catch (error) {
if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
}
return execution
? { filename: "semantic-review.json", review: reviewSemanticMajors(baseline, candidate, reviews) }
: { filename: "evolution.json", review: planEvolution(baseline, candidate, { reviews }) };
}
const effects: UpgradeEffects = { const effects: UpgradeEffects = {
async check(node, root, output, spec) { async check(node, root, output, spec) {
if (node.kind === "workspace" && !spec.baseline && !spec.bootstrap) if (node.kind === "workspace" && !spec.baseline && !spec.bootstrap)
@@ -206,10 +239,15 @@ const effects: UpgradeEffects = {
? (JSON.parse(await fs.readFile(spec.baseline, "utf8")) as WorkspaceRevision) ? (JSON.parse(await fs.readFile(spec.baseline, "utf8")) as WorkspaceRevision)
: null; : null;
const reviews = spec.reviews ? (JSON.parse(await fs.readFile(spec.reviews, "utf8")) as EvolutionReview[]) : []; const reviews = spec.reviews ? (JSON.parse(await fs.readFile(spec.reviews, "utf8")) as EvolutionReview[]) : [];
const evolution = planEvolution(baseline, JSON.parse(candidate), { reviews }); const { filename, review } = await reviewUpgradeCandidate({
await fs.writeFile(path.join(output, "evolution.json"), JSON.stringify(evolution, null, 2)); artifact,
if (evolution.blockers.length) baseline,
throw new Error(`Refactor required in ${node.directory}: ${evolution.blockers.join("; ")}`); candidate: JSON.parse(candidate),
reviews,
});
await fs.writeFile(path.join(output, filename), JSON.stringify(review, null, 2));
if (review.blockers.length)
throw new Error(`Refactor required in ${node.directory}: ${review.blockers.join("; ")}`);
} }
}, },
async snapshot(root) { async snapshot(root) {
@@ -443,13 +481,13 @@ export const applyPinUpgrades = async (
quixos: compiled.lock.quixos, quixos: compiled.lock.quixos,
directResources: [...compiled.directResources.entries()].map(([bindingKey, node]) => { directResources: [...compiled.directResources.entries()].map(([bindingKey, node]) => {
const [kind, binding] = bindingKey.split("\0"); const [kind, binding] = bindingKey.split("\0");
return { kind, binding, resourceKey: node.key, directory: node.directory }; return { kind, binding, resourceKey: node.key, directory: path.relative(plan.workbench, node.directory) };
}), }),
resources: [...resources.values()].map((node) => ({ resources: [...resources.values()].map((node) => ({
key: node.key, key: node.key,
kind: node.kind, kind: node.kind,
source: node.source, source: node.source,
directory: node.directory, directory: path.relative(plan.workbench, node.directory),
...(node.resource.kind === "build" ...(node.resource.kind === "build"
? {} ? {}
: { : {
+27 -15
View File
@@ -36,33 +36,37 @@ export async function loadCheckedInstallationCandidate(
if (!rootPattern.test(root) || !(await lstat(root)).isDirectory()) if (!rootPattern.test(root) || !(await lstat(root)).isDirectory())
throw Error("Candidate must be an immutable Nix output directory"); throw Error("Candidate must be an immutable Nix output directory");
const scope = (resources.budget ?? candidateMetadataBudget).acquire(resources.owner ?? root); const scope = (resources.budget ?? candidateMetadataBudget).acquire(resources.owner ?? root);
let releaseValidation = () => {};
try { try {
// Validate the duplicated source contract by digest, then discard its tree
// before allocating the substantially larger checked execution plan.
const workspaceDigest = await (async () => {
const input = await readJson(root, "candidate.json", scope);
try {
const { executionContracts: _legacyContracts, ...workspace } = input.value;
return hexDigest(workspace);
} finally {
input.releaseTree();
}
})();
// Sequential reads avoid partially rejected Promise.all() work allocating // Sequential reads avoid partially rejected Promise.all() work allocating
// after the failed candidate's reservation has been released. // after the failed candidate's reservation has been released.
const values = []; const values = [];
for (const file of [ for (const file of [
"candidate.json",
"execution-plan.json", "execution-plan.json",
"execution-artifacts.json", "execution-artifacts.json",
"source.json", "source.json",
"entry.json", "entry.json",
"kernel.json", "kernel.json",
"queries.json", "queries.json",
"graph-execution.json",
]) { ]) {
const parsed = await readJson(root, file, scope); const parsed = await readJson(root, file, scope);
values.push(parsed.value); values.push(parsed.value);
// candidate.json duplicates the checked plan for validation. Nothing in
// the installed candidate retains this input tree after validation.
if (file === "candidate.json") releaseValidation = parsed.releaseTree;
} }
const [candidate, plan, artifacts, source, entryRequest, kernel, queries, graph] = values; const [plan, artifacts, source, entryRequest, kernel, queries] = values;
const { executionContracts: _legacyContracts, ...workspace } = candidate;
if ( if (
plan?.definition?.codec !== "camino-execution-plan-v1" || plan?.definition?.codec !== "camino-execution-plan-v1" ||
hexDigest(plan.definition) !== plan.digest || hexDigest(plan.definition) !== plan.digest ||
hexDigest(workspace) !== hexDigest(plan.definition.workspace) workspaceDigest !== hexDigest(plan.definition.workspace)
) )
throw new ExecutionPlanError( throw new ExecutionPlanError(
"CANDIDATE_PLAN_MISMATCH", "CANDIDATE_PLAN_MISMATCH",
@@ -113,14 +117,24 @@ export async function loadCheckedInstallationCandidate(
"Stored interpreter input must match the checked build and plan", "Stored interpreter input must match the checked build and plan",
); );
const expectedGraph = graphExecutionRepresentation(plan, installation, kernel, queries); const expectedGraph = graphExecutionRepresentation(plan, installation, kernel, queries);
if (hexDigest(graph) !== hexDigest(expectedGraph) || artifacts.execution !== hexDigest(graph)) // The stored graph embeds the same kernel/query programs. Validate it in a
// short-lived scope and retain the representation that shares those trees.
await (async () => {
const input = await readJson(root, "graph-execution.json", scope);
try {
const digest = hexDigest(input.value);
if (digest !== hexDigest(expectedGraph) || artifacts.execution !== digest)
throw new ExecutionPlanError( throw new ExecutionPlanError(
"CANDIDATE_EXECUTION_MISMATCH", "CANDIDATE_EXECUTION_MISMATCH",
root, root,
"Stored graph execution differs from checked inputs", "Stored graph execution differs from checked inputs",
); );
} finally {
input.releaseTree();
}
})();
const provenance = { const provenance = {
workspaceRevision: workspace.id as string, workspaceRevision: plan.definition.workspace.id as string,
source: { repository: source.repository as string, commit: source.commit as string }, source: { repository: source.repository as string, commit: source.commit as string },
generator: artifacts.generator as string, generator: artifacts.generator as string,
packages: (plan as ExecutionPlan).definition.packages.map((pkg) => ({ packages: (plan as ExecutionPlan).definition.packages.map((pkg) => ({
@@ -142,9 +156,9 @@ export async function loadCheckedInstallationCandidate(
return { return {
reference, reference,
workspace: plan.definition.workspace.workspaceId, workspace: plan.definition.workspace.workspaceId,
world: hexDigest(graph), world: hexDigest(expectedGraph),
plan: kernel.plan as string, plan: kernel.plan as string,
graphExecution: graph, graphExecution: expectedGraph,
provenance, provenance,
entry, entry,
kernel, kernel,
@@ -161,8 +175,6 @@ export async function loadCheckedInstallationCandidate(
} catch (error) { } catch (error) {
scope.release(); scope.release();
throw error; throw error;
} finally {
releaseValidation();
} }
} }
+5 -1
View File
@@ -9,7 +9,11 @@ export class CandidateMetadataBudget {
private bytes = 0; private bytes = 0;
private scopes = 0; private scopes = 0;
private readonly owners = new Map<string, number>(); private readonly owners = new Map<string, number>();
constructor(limits = { bytes: 512 * 1024 * 1024, ownerBytes: 256 * 1024 * 1024, candidates: 128 }) { // A cutover holds both the serving and proposed installation plus transient
// parsing space. The 57-repository reader retains ~133 MiB per installation;
// a 256 MiB owner ceiling cannot admit its ordinary atomic replacement.
// Keep the aggregate ceiling independent and leave room for parsing overlap.
constructor(limits = { bytes: 512 * 1024 * 1024, ownerBytes: 384 * 1024 * 1024, candidates: 128 }) {
for (const value of Object.values(limits)) for (const value of Object.values(limits))
if (!Number.isSafeInteger(value) || value < 1) throw Error("INVALID_CANDIDATE_METADATA_BUDGET"); if (!Number.isSafeInteger(value) || value < 1) throw Error("INVALID_CANDIDATE_METADATA_BUDGET");
if (limits.ownerBytes > limits.bytes) throw Error("INVALID_CANDIDATE_METADATA_BUDGET"); if (limits.ownerBytes > limits.bytes) throw Error("INVALID_CANDIDATE_METADATA_BUDGET");
+56
View File
@@ -4,6 +4,62 @@ import { mkdtemp, writeFile, symlink, rm } from "node:fs/promises";
import { join } from "node:path"; import { join } from "node:path";
import { tmpdir } from "node:os"; import { tmpdir } from "node:os";
import { CandidateMetadataBudget, readCandidateMetadata } from "../src/execution-world/metadata.js"; import { CandidateMetadataBudget, readCandidateMetadata } from "../src/execution-world/metadata.js";
import { loadCheckedInstallationCandidate } from "../src/execution-world/candidate.js";
test(
"a real checked application can stage its replacement within the default metadata budget",
{
skip: !process.env.QX_CHECKED_CANDIDATE,
},
async () => {
const root = process.env.QX_CHECKED_CANDIDATE!;
const budget = new CandidateMetadataBudget();
const first = await loadCheckedInstallationCandidate(root, {}, { budget, owner: "reader" });
try {
const retained = budget.snapshot().bytes;
const second = await loadCheckedInstallationCandidate(root, {}, { budget, owner: "reader" });
try {
assert.equal(budget.snapshot().bytes, retained * 2);
assert.deepEqual(second.reference, first.reference, "Compaction preserves exact checked identity");
assert.equal(second.graphExecution.kernel, second.kernel, "Graph representation shares the validated program");
assert.equal(second.graphExecution.queries, second.queries);
// A deliberately tighter pool admits the serving installation but must
// reject replacement parsing without leaking a candidate or tree lease.
const tight = new CandidateMetadataBudget({
bytes: retained + 1,
ownerBytes: retained + 1,
candidates: 2,
});
const blocker = tight.acquire("reader");
blocker.charge(retained);
try {
await assert.rejects(
loadCheckedInstallationCandidate(root, {}, { budget: tight, owner: "reader" }),
/CANDIDATE_METADATA_LIMIT/,
);
assert.equal(tight.snapshot().bytes, retained);
assert.equal(tight.snapshot().candidates, 1);
} finally {
blocker.release();
}
const other = budget.acquire("other");
try {
assert.throws(() => other.charge(budget.limits.bytes), /CANDIDATE_METADATA_LIMIT/);
assert.equal(budget.snapshot().bytes, retained * 2, "Rejected admission must not leak charges");
} finally {
other.release();
}
} finally {
second.metadata.release();
}
assert.equal(budget.snapshot().bytes, retained, "The serving candidate survives failed or completed staging");
} finally {
first.metadata.release();
}
assert.equal(budget.snapshot().bytes, 0);
assert.equal(budget.snapshot().candidates, 0);
},
);
test("concurrent candidate reservations enforce aggregate and owner limits and release exactly once", () => { test("concurrent candidate reservations enforce aggregate and owner limits and release exactly once", () => {
const budget = new CandidateMetadataBudget({ bytes: 1000, ownerBytes: 600, candidates: 3 }); const budget = new CandidateMetadataBudget({ bytes: 1000, ownerBytes: 600, candidates: 3 });
+97 -1
View File
@@ -5,9 +5,90 @@ import os from "node:os";
import path from "node:path"; import path from "node:path";
import { promisify } from "node:util"; import { promisify } from "node:util";
import { execFile as callback } from "node:child_process"; import { execFile as callback } from "node:child_process";
import { planPinUpgrades, applyPinUpgrades, type UpgradeEffects } from "../src/capability-language/pin-upgrades.js"; import {
planPinUpgrades,
applyPinUpgrades,
discoverUpgradeSpec,
reviewUpgradeCandidate,
type UpgradeEffects,
} from "../src/capability-language/pin-upgrades.js";
import { capabilityId } from "../src/capability-model/index.js";
import { makeValidCapabilityWorkspace } from "./fixtures/capability-model.js";
const execFile = promisify(callback); const execFile = promisify(callback);
test("execution pin upgrades accept unchanged shared attachments without legacy migration planning", async (context) => {
const artifact = await fs.mkdtemp(path.join(os.tmpdir(), "qx-upgrade-execution-review-"));
context.after(() => fs.rm(artifact, { recursive: true, force: true }));
await fs.writeFile(path.join(artifact, "execution-plan.json"), "{}");
const baseline = makeValidCapabilityWorkspace();
assert.ok(baseline.sharedAttachments.length);
const candidate = structuredClone(baseline);
candidate.sourceRootCommit = "f".repeat(40);
const { filename, review } = await reviewUpgradeCandidate({ artifact, baseline, candidate });
assert.equal(filename, "semantic-review.json");
assert.equal(review.checkerVersion, "quixos-semantic-review-v1");
assert.deepEqual(review.blockers, []);
assert.equal("migrationRequired" in review, false);
assert.equal("runtimeActions" in review, false);
});
test("execution pin upgrades require exact semantic-major receipts and reject foreign workspaces", async (context) => {
const artifact = await fs.mkdtemp(path.join(os.tmpdir(), "qx-upgrade-semantic-review-"));
context.after(() => fs.rm(artifact, { recursive: true, force: true }));
await fs.writeFile(path.join(artifact, "execution-plan.json"), "{}");
const baseline = makeValidCapabilityWorkspace();
baseline.conformances[0]!.id = capabilityId.conformance("conformance:project:named");
const candidate = structuredClone(baseline);
candidate.conformances[0]!.semanticMajor = 2;
const { review } = await reviewUpgradeCandidate({ artifact, baseline, candidate });
assert.equal(review.reviews.length, 1);
assert.equal(review.reviews[0]!.accepted, false);
assert.match(review.blockers[0]!, /Semantic-major review required/);
const receipt = {
requirementDigest: review.reviews[0]!.requirementDigest,
decision: "accepted-unchanged" as const,
rationale: "Reviewed the consumer against the provider's unchanged label behavior",
agentId: "upgrade-fixture-agent",
};
assert.deepEqual(
(await reviewUpgradeCandidate({ artifact, baseline, candidate, reviews: [receipt] })).review.blockers,
[],
);
candidate.packageImports[0]!.source.commit = "f".repeat(40);
assert.equal(
(await reviewUpgradeCandidate({ artifact, baseline, candidate, reviews: [receipt] })).review.reviews[0]!.accepted,
false,
);
candidate.workspaceId = capabilityId.workspace("workspace:foreign");
await assert.rejects(() => reviewUpgradeCandidate({ artifact, baseline, candidate }), /different workspace/);
});
test("nonexecution pin upgrades retain their evolution checks", async (context) => {
const artifact = await fs.mkdtemp(path.join(os.tmpdir(), "qx-upgrade-evolution-review-"));
context.after(() => fs.rm(artifact, { recursive: true, force: true }));
const baseline = makeValidCapabilityWorkspace();
const { filename, review } = await reviewUpgradeCandidate({
artifact,
baseline,
candidate: structuredClone(baseline),
});
assert.equal(filename, "evolution.json");
assert.equal(review.checkerVersion, "quixos-evolution-v1");
assert.ok(review.blockers.some((message) => message.includes("legacy workspace-shared attachments")));
assert.equal("migrationRequired" in review, true);
});
test("unexpected artifact access failures do not select nonexecution checks", async (context) => {
const directory = await fs.mkdtemp(path.join(os.tmpdir(), "qx-upgrade-review-failure-"));
context.after(() => fs.rm(directory, { recursive: true, force: true }));
const artifact = path.join(directory, "not-a-directory");
await fs.writeFile(artifact, "not an artifact");
const candidate = makeValidCapabilityWorkspace();
await assert.rejects(() => reviewUpgradeCandidate({ artifact, baseline: candidate, candidate }), {
code: "ENOTDIR",
});
});
test( test(
"real jj snapshots and immutable Git publication propagate a changed interface into the root", "real jj snapshots and immutable Git publication propagate a changed interface into the root",
{ skip: !process.env.QX_CHECK_GENERATOR }, { skip: !process.env.QX_CHECK_GENERATOR },
@@ -73,6 +154,21 @@ test(
await run(workbench, "git", ["--git-dir", path.join(workbench, "remotes/named.git"), "show-ref"]), await run(workbench, "git", ["--git-dir", path.join(workbench, "remotes/named.git"), "show-ref"]),
new RegExp(commit), new RegExp(commit),
); );
assert.equal(graph.resources[0].directory, "resources/Named");
assert.equal(graph.directResources[0].directory, "resources/Named");
// A retained workbench can move without keeping its original absolute path
// alive. Recovery journals remain bound to their original writer/root.
const relocated = `${workbench}-relocated`;
context.after(() => fs.rm(relocated, { recursive: true, force: true }));
await fs.cp(workbench, relocated, { recursive: true });
const discovered = await discoverUpgradeSpec(relocated);
assert.equal(discovered.nodes[1]!.directory, "resources/Named");
const relocatedPlan = await planPinUpgrades(relocated, { ...discovered, bootstrap: true });
assert.equal(relocatedPlan.workbench, relocated);
assert.deepEqual(
relocatedPlan.nodes.map((node) => node.directory),
["resources/Named", "root"],
);
}, },
); );