Implement workspace evolution, migrations, and runtime continuity
Enable evolution by default for source-backed workspaces. Add stable conformance ownership, semantic-major review, candidate typechecking, and durable fenced cutover with explicit migrations and forward recovery. Independently supervise package runtimes so unchanged resource owners keep their processes and connections across cutover. Add scoped invocation authority, resource sessions, and typed callback rebinding. Wire opaque object references through generated bindings and RPCs. Add canonical relationship sets, keyed maps, and ordered lists with scoped transactional mutations, revision checks, and inverse consistency. Support planned cascade deletion, protection, tombstones, and lifecycle foundations. Add journaled structural edits, package/function/migration scaffolding, managed repository creation, and resumable bottom-up dependency pin publication. Document lifetime boundaries, revision pinning, prototype compatibility policy, commands, and deferred work. Validate with 210 tests, user-systemd process/connection continuity, generated-package TypeScript checks, and Nix host/protocol checks. TTL handoff, physical reclamation, general multi-step migrations, and root-systemd migration isolation acceptance remain deferred.
This commit is contained in:
Timothy J. Aveni
@@ -0,0 +1,135 @@
|
||||
import { CharStream, CommonTokenStream } from "antlr4ng";
|
||||
import { QuixosLockLexer } from "../resource-lock/generated/QuixosLockLexer.js";
|
||||
import { QuixosLockParser } from "../resource-lock/generated/QuixosLockParser.js";
|
||||
import { parseQuixosLockDocument } from "../resource-lock/parser.js";
|
||||
import { parseQx, walkSyntax, applySourceEdits, type SyntaxNode } from "./source.js";
|
||||
|
||||
export type StructuralSelector = { kind: string; id?: string; name?: string; names?: string[] };
|
||||
export type StructuralEdit =
|
||||
| { operation: "append"; parent: StructuralSelector; source: string }
|
||||
| { operation: "replace"; target: StructuralSelector; source: string }
|
||||
| { operation: "remove"; target: StructuralSelector }
|
||||
| { operation: "import"; kind: "interface" | "package"; name: string }
|
||||
| { operation: "semantic-major"; target: StructuralSelector; major: number }
|
||||
| { operation: "conformance-id"; target: StructuralSelector; id: string }
|
||||
| { operation: "quixos-pin"; source: {repository: string; commit: string} }
|
||||
| { operation: "dependency"; kind: "interface" | "package"; name: string; source: {repository: string; commit: string} | null };
|
||||
|
||||
// Deliberately exclude valueType/identifier/stringLiteral: callers operate on
|
||||
// declaration structure, not arbitrary token offsets or lockfile text patches.
|
||||
const selectable = new Set(["workspaceDecl", "fragmentDecl", "interfaceResourceDecl", "packageResourceDecl", "atomDecl",
|
||||
"valueMember", "relationshipMember", "operationMember", "packageOperationExport", "packageFunctionExport", "packageConstructorExport",
|
||||
"conformanceDecl", "stateDecl", "edgeDecl", "constructorBindingDecl", "resourceImportDecl", "sourceImportDecl", "operationBindingDecl"]);
|
||||
|
||||
const select = (source: string, selector: StructuralSelector): {node: SyntaxNode; syntax: ReturnType<typeof parseQx>} => {
|
||||
if (!selectable.has(selector.kind)) throw new Error(`Unsupported structural selector ${selector.kind}`);
|
||||
const syntax = parseQx(source);
|
||||
if (syntax.diagnostics.length) throw new Error("Cannot scaffold syntactically invalid QX");
|
||||
const matches = [...walkSyntax(syntax.root)].filter((node) => {
|
||||
if (node.kind !== selector.kind) return false;
|
||||
if (selector.name && !node.children.some((child) => child.kind === "identifier" && source.slice(child.start, child.end) === selector.name)) return false;
|
||||
if (selector.names && JSON.stringify(node.children.filter((child) => child.kind === "identifier").map((child) => source.slice(child.start, child.end))) !== JSON.stringify(selector.names)) return false;
|
||||
if (selector.id) {
|
||||
// Only an explicit ID field counts, not a coincidentally equal revision,
|
||||
// default value, nested declaration, or comment.
|
||||
const tokens = syntax.tokens.filter((token) => !token.trivia && token.start >= node.start && token.end <= node.end);
|
||||
const literal = node.children.find((child) => child.kind === "stringLiteral" && tokens.some((token, index) => token.start === child.start && tokens[index - 1]?.kind === "ID"));
|
||||
if (!literal || JSON.parse(source.slice(literal.start, literal.end)) !== selector.id) return false;
|
||||
}
|
||||
return true;
|
||||
});
|
||||
if (matches.length !== 1) throw new Error(`Structural selector must resolve exactly once (found ${matches.length})`);
|
||||
return {node: matches[0], syntax};
|
||||
};
|
||||
|
||||
/** Comment-preserving structural edits; every result is parsed before returning. */
|
||||
export const editStructure = (source: string, edit: StructuralEdit): string => {
|
||||
if (edit.operation === "quixos-pin") {
|
||||
const parsed = parseQuixosLockDocument(source);
|
||||
if (!parsed.ok || parsed.document.kind !== "root") throw new Error("Quixos pins belong in a valid root lockfile");
|
||||
const parser = new QuixosLockParser(new CommonTokenStream(new QuixosLockLexer(CharStream.fromString(source))));
|
||||
const entries = parser.document().quixosEntry();
|
||||
if (entries.length !== 1) throw new Error("Expected one Quixos source declaration");
|
||||
const literals = entries[0].quixosSourceBlock().stringLiteral();
|
||||
const offsets = [0];
|
||||
for (const character of source) offsets.push(offsets[offsets.length - 1] + character.length);
|
||||
const result = applySourceEdits(source, [
|
||||
{start: offsets[literals[0].start!.start], end: offsets[literals[0].stop!.stop + 1], text: JSON.stringify(edit.source.repository)},
|
||||
{start: offsets[literals[literals.length - 1].start!.start], end: offsets[literals[literals.length - 1].stop!.stop + 1], text: JSON.stringify(edit.source.commit)},
|
||||
]);
|
||||
const checked = parseQuixosLockDocument(result);
|
||||
if (!checked.ok) throw new Error(`Invalid Quixos pin: ${checked.diagnostics.map((entry) => entry.message).join("; ")}`);
|
||||
return result;
|
||||
}
|
||||
if (edit.operation === "import") {
|
||||
if (!["interface", "package"].includes(edit.kind) || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(edit.name)) throw new Error("Invalid resource import");
|
||||
const syntax = parseQx(source);
|
||||
if (syntax.diagnostics.length) throw new Error("Cannot scaffold invalid QX");
|
||||
const text = `import ${edit.kind} ${edit.name};`;
|
||||
if ([...walkSyntax(syntax.root)].some((entry) => entry.kind === "resourceImportDecl" && source.slice(entry.start, entry.end).replace(/\s+/g, " ") === text)) return source;
|
||||
const root = syntax.root.children[0];
|
||||
const position = ["workspaceDecl", "fragmentDecl"].includes(root.kind) ? syntax.tokens.find((token) => token.kind === "LBRACE")!.end : root.start;
|
||||
const result = applySourceEdits(source, [{start: position, end: position, text: `\n${text}\n`}]);
|
||||
if (parseQx(result).diagnostics.length) throw new Error("Invalid resource import position");
|
||||
return result;
|
||||
}
|
||||
if (edit.operation === "dependency") {
|
||||
const parsed = parseQuixosLockDocument(source);
|
||||
if (!parsed.ok) throw new Error("Cannot scaffold an invalid lockfile");
|
||||
if (!["interface", "package"].includes(edit.kind) || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(edit.name)) throw new Error("Invalid dependency selector");
|
||||
const parser = new QuixosLockParser(new CommonTokenStream(new QuixosLockLexer(CharStream.fromString(source))));
|
||||
const tree = parser.document();
|
||||
const offsets = [0];
|
||||
for (const character of source) offsets.push(offsets[offsets.length - 1] + character.length);
|
||||
const entries = tree.resourceEntry().filter((entry) => entry.resourceKind().getText() === edit.kind && entry.identifier().getText() === edit.name);
|
||||
if (entries.length > 1) throw new Error("Ambiguous dependency selector");
|
||||
const entry = entries[0];
|
||||
const replacement = edit.source ? `${edit.kind} ${edit.name} source {\n repository ${JSON.stringify(edit.source.repository)};\n commit ${JSON.stringify(edit.source.commit)};\n}` : "";
|
||||
if (!entry && !edit.source) throw new Error("Cannot remove an absent dependency");
|
||||
const start = entry ? offsets[entry.start!.start] : offsets[tree.RBRACE().symbol.start];
|
||||
const end = entry ? offsets[entry.stop!.stop + 1] : start;
|
||||
const result = applySourceEdits(source, [{start, end, text: entry ? replacement : `${replacement}\n`}]);
|
||||
const checked = parseQuixosLockDocument(result);
|
||||
if (!checked.ok) throw new Error(`Invalid dependency change: ${checked.diagnostics.map((entry) => entry.message).join("; ")}`);
|
||||
return result;
|
||||
}
|
||||
const {node, syntax} = select(source, edit.operation === "append" ? edit.parent : edit.target);
|
||||
let result: string;
|
||||
if (edit.operation === "semantic-major") {
|
||||
if (!["conformanceDecl", "packageResourceDecl"].includes(node.kind) || !Number.isSafeInteger(edit.major) || edit.major < 1) throw new Error("Semantic major requires a package/conformance and positive integer");
|
||||
const tokens = syntax.tokens.filter((token) => !token.trivia && token.start >= node.start && token.end <= node.end);
|
||||
const marker = tokens.findIndex((token) => token.kind === "SEMANTIC_MAJOR");
|
||||
const value = marker < 0 ? undefined : tokens[marker + 1];
|
||||
const brace = tokens.find((token) => token.kind === "LBRACE")!;
|
||||
result = applySourceEdits(source, [{start: value?.start ?? brace.start, end: value?.end ?? brace.start, text: value ? String(edit.major) : `semantic-major ${edit.major} `}]);
|
||||
} else if (edit.operation === "conformance-id") {
|
||||
if (node.kind !== "conformanceDecl" || !edit.id) throw new Error("Identity enrollment requires a conformance and stable ID");
|
||||
const existing = node.children.find((entry) => entry.kind === "stringLiteral");
|
||||
if (existing) {
|
||||
if (JSON.parse(source.slice(existing.start, existing.end)) !== edit.id) throw new Error("Cannot change an enrolled conformance identity; create a new conformance explicitly");
|
||||
return source;
|
||||
}
|
||||
const identifiers = node.children.filter((entry) => entry.kind === "identifier");
|
||||
const position = identifiers[identifiers.length - 1].end;
|
||||
result = applySourceEdits(source, [{start: position, end: position, text: ` id ${JSON.stringify(edit.id)}`}]);
|
||||
} else if (edit.operation === "append") {
|
||||
const closing = syntax.tokens.find((token) => token.kind === "RBRACE" && token.end === node.end);
|
||||
if (!closing) throw new Error("Append requires a declaration with a body");
|
||||
result = applySourceEdits(source, [{start: closing.start, end: closing.start, text: `\n${edit.source}\n`}]);
|
||||
} else {
|
||||
const wrapper = edit.operation === "remove" && ["stateDecl", "edgeDecl"].includes(node.kind)
|
||||
? [...walkSyntax(syntax.root)].filter((entry) => ["conformanceItem", "sharedAttachmentDecl"].includes(entry.kind) && entry.start <= node.start && entry.end >= node.end).sort((a, b) => (a.end - a.start) - (b.end - b.start))[0]
|
||||
: undefined;
|
||||
result = applySourceEdits(source, [{start: wrapper?.start ?? node.start, end: wrapper?.end ?? node.end, text: edit.operation === "replace" ? edit.source : ""}]);
|
||||
}
|
||||
const checked = parseQx(result);
|
||||
if (checked.diagnostics.length) throw new Error(`Invalid structural change: ${checked.diagnostics.map((entry) => entry.message).join("; ")}`);
|
||||
return result;
|
||||
};
|
||||
|
||||
export const scaffoldResourceSource = (kind: "interface" | "package", name: string, id: string, revision: string) => {
|
||||
if (!/^[A-Z][A-Za-z0-9]*$/.test(name) || !id || !revision) throw new Error("Resource scaffold requires a PascalCase name and explicit identities");
|
||||
const source = `${kind} ${name} id ${JSON.stringify(id)} revision ${JSON.stringify(revision)} {\n}\n`;
|
||||
if (parseQx(source).diagnostics.length) throw new Error("Invalid resource scaffold");
|
||||
return source;
|
||||
};
|
||||
Reference in New Issue
Block a user