quixos/quixos-protocol
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Unify workspace authoring, verification and scaffolding workflows

Browse Source 
Use exact jj snapshots and one candidate-bound Nix builder for incremental checks, template validation and activation. Keep provenance internal and separate recovery checkpoint failures from local command success.

Provision workspace-scoped managed package/interface repositories with recoverable Central effects. Add TypeScript/React presets, function and dependency commands, and scaffold enrollment for all TODO packages. Install authoring guides and controlled Codex sandbox rules.

Invalidate module resolutions across cutover, including in-flight races, and content-address host platform entries. Strengthen domain-model and verification instructions.

Validated real jj/Nix authoring, React/Slate dependency installation, bottom-up local Git publication, packaged CLI tests, PostgreSQL recovery/auth tests, Web Studio tests and host configuration. Public protocol/helpers and the validated 19-resource TODO template are published. Retained the approved exact private baseline and updated the installation's default template pin to 68d54f0d52be433ebf60bdc1faf7646c57f90307. Master and live deployments remain unchanged. See docs/WORKSPACE_AUTHORING_PROGRESS.md.
This commit is contained in:
Timothy J. Aveni
2026-09-13 22:07:18 -07:00
parent 16b28f1bc4
commit fae4e48f72
11 changed files with 288 additions and 116 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/capability-language/candidate-check.ts
+58 -86
View File
@@ -7,7 +7,8 @@ import { createHash } from "node:crypto";
import { compileWorkspaceRepository, compileCapabilityResourceRepository } from "./assembly.js";
import { createGitCapabilityResolver } from "./git-resolver.js";
import { contentDigest, planEvolution, type EvolutionReview, type WorkspaceRevision } from "../capability-model/index.js";
import { bindingSchema, generateTypeScriptBindings, type BindingSchema, type TypeScriptBindingOptions } from "../bindings/index.js";
import { bindingSchema } from "../bindings/index.js";
import {snapshotCommit, checkoutCommit, buildCheckedPackage} from "./checked-build.js";
const execFile = promisify(execFileCallback);
const bytesDigest = (value: Uint8Array) => `sha256:${createHash("sha256").update(value).digest("hex")}`;
@@ -64,116 +65,87 @@ export const snapshotRepository = async (source: string, destination: string) =>
return { source: root, directory: destination, treeDigest: contentDigest(contents), files: contents };
};
// Local mirrors accelerate resolution, but only their committed locked trees
// may stand in for published dependencies. Never relabel dirty files as a pin.
async function committedResolver(root: string, temporary: string, filename?: string, publishedOnly = false) {
const map = publishedOnly ? {resources: []} : await localResourceSnapshots(root, filename);
const resources = [];
for (const [index, entry] of map.resources.entries()) {
const directory = path.join(temporary, `dependency-${index}`);
await checkoutCommit(entry.directory, entry.commit, directory);
resources.push({...entry, directory});
}
const snapshotMap = path.join(temporary, "snapshots.json");
await fs.writeFile(snapshotMap, JSON.stringify({resources}));
return createGitCapabilityResolver({checkoutRoot: path.join(temporary, "resolved"), snapshotMap});
}
export const checkResourceCandidate = async (options: {root: string; output: string; kind: "package" | "interface"; source: {repository: string; commit: string}; snapshotMap?: string; publishedOnly?: boolean}) => {
await fs.mkdir(options.output, {mode: 0o700});
const temporary = await fs.mkdtemp(path.join(os.tmpdir(), "qx-resource-check-"));
const blockers: string[] = [];
let diagnostics = "";
let treeDigest: string | undefined;
let treeDigest: string | undefined, commit: string | undefined, artifactPath: string | undefined;
try {
const root = await snapshotRepository(options.root, path.join(temporary, "root"));
treeDigest = root.treeDigest;
const map = options.publishedOnly ? {resources: []} : await localResourceSnapshots(options.root, options.snapshotMap);
const resources = [];
for (const [index, entry] of map.resources.entries()) {
const snapshot = await snapshotRepository(entry.directory, path.join(temporary, `dependency-${index}`));
resources.push({...entry, directory: snapshot.directory});
}
const snapshotMap = path.join(temporary, "snapshots.json");
await fs.writeFile(snapshotMap, JSON.stringify({resources}));
const resolveResource = await createGitCapabilityResolver({checkoutRoot: path.join(temporary, "resolved"), snapshotMap});
const compiled = await compileCapabilityResourceRepository({rootDirectory: root.directory, kind: options.kind, source: {resolver: "git", ...options.source}, resolveResource});
commit = await snapshotCommit(options.root);
treeDigest = (await snapshotRepository(options.root, path.join(temporary, "observed"))).treeDigest;
const root = path.join(temporary, "source");
await checkoutCommit(options.root, commit, root);
const resolveResource = await committedResolver(options.root, temporary, options.snapshotMap, options.publishedOnly);
const compiled = await compileCapabilityResourceRepository({rootDirectory: root, kind: options.kind, source: {resolver: "git", repository: options.source.repository, commit}, resolveResource});
if (compiled.resource.kind === "package") {
const configuration = JSON.parse(await fs.readFile(path.join(root.directory, "quixos.check.json"), "utf8"));
const output = configuration.bindingOutput as string;
if (configuration.backend !== "typescript" || !/^(?:[A-Za-z0-9_-][A-Za-z0-9_.-]*\/)*[A-Za-z0-9_-][A-Za-z0-9_.-]*\.ts$/.test(output)) throw new Error("Unsupported candidate checker configuration");
const modules = path.join(root.source, "node_modules");
await fs.access(path.join(modules, ".bin/tsc"));
await fs.symlink(modules, path.join(root.directory, "node_modules"), "dir");
const destination = path.join(root.directory, output);
await fs.mkdir(path.dirname(destination), {recursive: true});
await fs.writeFile(destination, generateTypeScriptBindings(bindingSchema(compiled), compiled.resource.revision.revisionId, configuration.options));
diagnostics = (await execFile(path.join(modules, ".bin/tsc"), ["--noEmit", "--pretty", "false"], {cwd: root.directory, maxBuffer: 16 * 1024 * 1024})).stdout;
const schema = path.join(temporary, "bindings.json");
await fs.writeFile(schema, JSON.stringify(bindingSchema(compiled)));
artifactPath = await buildCheckedPackage(root, schema, compiled.resource.revision.revisionId);
}
if (await snapshotCommit(options.root) !== commit) throw new Error("Source changed during verification; run the check again");
await fs.writeFile(path.join(options.output, "candidate.json"), JSON.stringify(compiled.resource, null, 2));
} catch (error) {
blockers.push(error instanceof Error ? error.message : String(error));
diagnostics += (error as {stdout?: string; stderr?: string}).stdout ?? "";
diagnostics += (error as {stderr?: string}).stderr ?? "";
} finally {await fs.rm(temporary, {recursive: true, force: true});}
const result = {candidateOnly: true, activationEvidence: false, treeDigest, blockers, diagnostics};
const result = {candidateOnly: true, activationEvidence: false, commit, treeDigest, artifactPath, blockers,
note: "Checked immutable candidate; cutover independently checks current migration/review requirements. No publication or activation performed."};
await fs.writeFile(path.join(options.output, "report.json"), JSON.stringify(result, null, 2));
return result;
};
export const checkWorkspaceCandidate = async (options: { root: string; output: string; snapshotMap?: string; baseline?: string; reviews?: string }) => {
// A new output directory is the whole artifact boundary; never overwrite a prior check.
await fs.mkdir(options.output, { mode: 0o700 });
const temporary = await fs.mkdtemp(path.join(os.tmpdir(), "quixos-candidate-"));
const blockers: string[] = [];
const checks: unknown[] = [];
const snapshots = [];
export const checkWorkspaceCandidate = async (options: {root: string; output: string; snapshotMap?: string; baseline?: string; reviews?: string}) => {
await fs.mkdir(options.output, {mode: 0o700});
const temporary = await fs.mkdtemp(path.join(os.tmpdir(), "qx-workspace-check-"));
const blockers: string[] = [], checks: {packageRevisionId: string; artifactPath: string}[] = [];
let commit: string | undefined;
try {
const root = await snapshotRepository(options.root, path.join(temporary, "root"));
snapshots.push(root);
const map = await localResourceSnapshots(options.root, options.snapshotMap);
const resources = [];
for (const [index, entry] of map.resources.entries()) {
const source = entry.directory;
const snapshot = await snapshotRepository(source, path.join(temporary, `resource-${index}`));
snapshots.push(snapshot);
resources.push({ ...entry, directory: snapshot.directory });
commit = await snapshotCommit(options.root);
for (const entry of (await localResourceSnapshots(options.root, options.snapshotMap)).resources) {
const current = await snapshotCommit(entry.directory);
const tree = async (revision: string) => (await execFile("git", ["rev-parse", `${revision}^{tree}`], {cwd: entry.directory})).stdout.trim();
if (await tree(current) !== await tree(entry.commit)) throw new Error(`Edited resource is not in the root's locked candidate: ${entry.directory}. Check that resource, then run qx-workspace resource upgrade --publish to propagate its revision.`);
}
const mapFile = path.join(temporary, "snapshots.json");
await fs.writeFile(mapFile, JSON.stringify({ resources }));
const resolveResource = await createGitCapabilityResolver({ checkoutRoot: path.join(temporary, "resolved"), snapshotMap: mapFile });
const compiled = await compileWorkspaceRepository({ rootDirectory: root.directory, resolveResource });
const root = path.join(temporary, "source");
await checkoutCommit(options.root, commit, root);
const resolveResource = await committedResolver(options.root, temporary, options.snapshotMap);
const compiled = await compileWorkspaceRepository({rootDirectory: root, sourceRootCommit: commit, resolveResource});
const baseline = options.baseline ? JSON.parse(await fs.readFile(options.baseline, "utf8")) as WorkspaceRevision : null;
const reviews = options.reviews ? JSON.parse(await fs.readFile(options.reviews, "utf8")) as EvolutionReview[] : [];
const evolution = planEvolution(baseline, compiled.workspace, { reviews });
const evolution = planEvolution(baseline, compiled.workspace, {reviews});
blockers.push(...evolution.blockers);
const schema: BindingSchema = { format: "quixos-bindings", version: 1, interfaces: compiled.workspace.interfaceImports, packages: compiled.workspace.packageImports };
for (const resource of compiled.resources.filter((entry) => entry.kind === "package")) {
if (resource.resource.kind !== "package") continue;
const revision = resource.resource.revision;
let config: { backend: string; bindingOutput: string; options?: TypeScriptBindingOptions };
try { config = JSON.parse(await fs.readFile(path.join(resource.directory, "quixos.check.json"), "utf8")); }
catch { blockers.push(`No candidate checker configured for ${revision.revisionId} (quixos.check.json)`); continue; }
if (config.backend !== "typescript" || !/^(?:[A-Za-z0-9_-][A-Za-z0-9_.-]*\/)*[A-Za-z0-9_-][A-Za-z0-9_.-]*\.ts$/.test(config.bindingOutput)
|| config.bindingOutput.split("/").includes("..")) { blockers.push(`Unsupported checker or binding path for ${revision.revisionId}`); continue; }
const sourceSnapshot = snapshots.find((entry) => entry.directory === resource.directory);
const dependencyRoot = sourceSnapshot?.source ?? resource.directory;
const modules = path.join(dependencyRoot, "node_modules");
try { await fs.access(path.join(modules, ".bin", "tsc")); }
catch { blockers.push(`Missing installed TypeScript checker/dependencies for ${revision.revisionId}; install its locked development dependencies first`); continue; }
if (sourceSnapshot) await fs.symlink(modules, path.join(resource.directory, "node_modules"), "dir");
const generated = generateTypeScriptBindings(schema, revision.revisionId, config.options);
const destination = path.join(resource.directory, config.bindingOutput);
await fs.mkdir(path.dirname(destination), { recursive: true });
await fs.writeFile(destination, generated);
let success = false, diagnostics = "";
try { diagnostics = (await execFile(path.join(modules, ".bin", "tsc"), ["--noEmit", "--pretty", "false", "--listFiles"], { cwd: resource.directory, maxBuffer: 16 * 1024 * 1024 })).stdout; success = true; }
catch (error) { const result = error as Error & {stdout?: string; stderr?: string}; diagnostics = `${result.stdout ?? ""}\n${result.stderr ?? result.message}`; }
const typeInputs = [];
for (const line of diagnostics.split(/\r?\n/)) if (path.isAbsolute(line) && /\.[cm]?tsx?$/.test(line)) {
try { typeInputs.push({file: line, digest: bytesDigest(await fs.readFile(line))}); } catch { success = false; }
}
const checker = await fs.realpath(path.join(modules, ".bin", "tsc"));
const check = { packageRevisionId: revision.revisionId, success, bindingSchemaDigest: contentDigest(schema), generatedDigest: contentDigest(generated),
checkerDigest: contentDigest({ executable: bytesDigest(await fs.readFile(checker)), typeInputs }), diagnostics };
checks.push(check);
if (!success) blockers.push(`Typecheck failed for ${revision.revisionId}`);
for (const resource of compiled.resources.filter(entry => entry.kind === "package")) {
// Per-package recursive schema, identical to host activation, not unrelated
// workspace declarations that would unnecessarily invalidate build caches.
const candidate = await compileCapabilityResourceRepository({rootDirectory: resource.directory, kind: "package", source: resource.source, resolveResource});
const schema = path.join(temporary, "bindings.json");
await fs.writeFile(schema, JSON.stringify(bindingSchema(candidate)));
const artifactPath = await buildCheckedPackage(resource.directory, schema, candidate.resource.revision.revisionId);
checks.push({packageRevisionId: candidate.resource.revision.revisionId, artifactPath});
}
const result = { schemaVersion: 1, candidateOnly: true, activationEvidence: false,
sourceDigest: contentDigest(snapshots.map(({source, treeDigest}) => ({source, treeDigest}))),
snapshots: snapshots.map(({source, treeDigest}) => ({source, treeDigest})), evolution, checks, blockers,
note: "Local source-tree checks do not certify old Git revisions. Publication must repin the DAG and recheck final immutable artifacts." };
if (await snapshotCommit(options.root) !== commit) throw new Error("Source changed during verification; run the check again");
const result = {schemaVersion: 1, candidateOnly: true, activationEvidence: false, commit, evolution, checks, blockers,
note: "Checks the committed root and its exact locked dependencies. Resource edits must be verified and repinned before they enter this candidate. No publication or activation performed."};
await fs.writeFile(path.join(options.output, "candidate.json"), JSON.stringify(compiled.workspace, null, 2));
await fs.writeFile(path.join(options.output, "report.json"), JSON.stringify(result, null, 2));
return result;
} catch (error) {
const result = { schemaVersion: 1, candidateOnly: true, activationEvidence: false, checks, blockers: [...blockers, error instanceof Error ? error.message : String(error)] };
const result = {schemaVersion: 1, candidateOnly: true, activationEvidence: false, commit, checks, blockers: [...blockers, error instanceof Error ? error.message : String(error)]};
await fs.writeFile(path.join(options.output, "report.json"), JSON.stringify(result, null, 2));
return result;
} finally { await fs.rm(temporary, { recursive: true, force: true }); }
} finally {await fs.rm(temporary, {recursive: true, force: true});}
};