@tiphys/kernel 0.0.0 → 0.1.0

package/dist/src/gates/adapters/http-json.js

@@ -0,0 +1,283 @@
+import { realpathSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { readRegularFileIfPresent, refuseOpenForWrite } from "../../task.js";
+const ADAPTER_NAME = "http-json";
+/** RFC 6901 JSON pointer resolution. Absent is distinguished from null. */
+export function resolvePointer(document, pointer) {
+    if (pointer === "") {
+        return { found: true, value: document };
+    }
+    if (!pointer.startsWith("/")) {
+        return { found: false };
+    }
+    let current = document;
+    for (const rawToken of pointer.slice(1).split("/")) {
+        const token = rawToken.split("~1").join("/").split("~0").join("~");
+        if (Array.isArray(current)) {
+            const index = Number(token);
+            if (!Number.isInteger(index) || index < 0 || index >= current.length) {
+                return { found: false };
+            }
+            current = current[index];
+            continue;
+        }
+        if (typeof current === "object" && current !== null) {
+            if (!Object.hasOwn(current, token)) {
+                return { found: false };
+            }
+            current = current[token];
+            continue;
+        }
+        return { found: false };
+    }
+    return { found: true, value: current };
+}
+/** Strict equality for JSON primitives; deep for anything else via JSON. */
+function jsonEqual(a, b) {
+    if (a === b) {
+        return true;
+    }
+    if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) {
+        return false;
+    }
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+function display(value) {
+    return value === undefined ? "(no value)" : JSON.stringify(value);
+}
+function writeResponse(request, fields) {
+    const refusal = refuseOpenForWrite(request.recordPath);
+    if (refusal !== undefined) {
+        process.stderr.write(`${ADAPTER_NAME}: ${refusal}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const response = {
+        contractVersion: "1",
+        adapter: ADAPTER_NAME,
+        subject: request.subject,
+        outcome: fields.outcome,
+        ...(fields.resolved === undefined ? {} : { resolved: fields.resolved }),
+        observedAt: new Date().toISOString(),
+        ...(fields.observation === undefined ? {} : { observation: fields.observation }),
+        ...(fields.reason === undefined ? {} : { reason: fields.reason }),
+        ...(fields.units === undefined ? {} : { units: fields.units }),
+        ...(fields.transport === undefined ? {} : { transport: fields.transport }),
+    };
+    writeFileSync(request.recordPath, `${JSON.stringify(response, null, 2)}\n`);
+}
+function configError(request, field, message) {
+    writeResponse(request, {
+        outcome: "error",
+        reason: `misconfiguration at config.${field}: ${message}`,
+    });
+}
+async function observeOnce(request) {
+    const config = request.config;
+    if (typeof config?.url !== "string" || config.url === "") {
+        configError(request, "url", "a request URL is required");
+        return;
+    }
+    if (typeof config.observe?.statusPointer !== "string") {
+        configError(request, "observe.statusPointer", "a status pointer is required");
+        return;
+    }
+    if (!("satisfiedValue" in config.observe)) {
+        configError(request, "observe.satisfiedValue", "one satisfying value is required");
+        return;
+    }
+    const hasTerminalPointer = typeof config.observe.terminalPointer === "string";
+    const hasTerminalValue = "terminalValue" in config.observe;
+    if (hasTerminalPointer !== hasTerminalValue) {
+        configError(request, "observe.terminalPointer", "terminalPointer and terminalValue are declared together or not at all");
+        return;
+    }
+    let body;
+    let httpStatus;
+    try {
+        const response = await fetch(config.url, {
+            method: config.method ?? "GET",
+        });
+        httpStatus = response.status;
+        body = await response.text();
+    }
+    catch (error) {
+        writeResponse(request, {
+            outcome: "error",
+            reason: `request to ${config.url} could not be completed: ${String(error.message)}`,
+        });
+        return;
+    }
+    if (httpStatus < 200 || httpStatus > 299) {
+        // Unreachable-in-substance: unauthenticated (401), forbidden, missing,
+        // server error. No verdict was reached; never pending (M2-C-3).
+        writeResponse(request, {
+            outcome: "error",
+            reason: `HTTP ${String(httpStatus)} from ${config.url}; no verdict can be read from a non-success transport status`,
+            transport: { httpStatus },
+        });
+        return;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch (error) {
+        writeResponse(request, {
+            outcome: "error",
+            reason: `response body from ${config.url} does not parse as JSON: ${error.message}`,
+            transport: { httpStatus },
+        });
+        return;
+    }
+    // Locate, when configured: find the subject's own release object.
+    let target = parsed;
+    let resolved = { kind: "endpoint", id: config.url };
+    if (config.locate !== undefined) {
+        const locate = config.locate;
+        if (typeof locate.listPointer !== "string" || typeof locate.idPointer !== "string" || !Array.isArray(locate.match) || locate.match.length === 0) {
+            configError(request, "locate", "listPointer, idPointer and a non-empty match list are required");
+            return;
+        }
+        const list = resolvePointer(parsed, locate.listPointer);
+        if (!list.found || !Array.isArray(list.value)) {
+            writeResponse(request, {
+                outcome: "error",
+                reason: `no array at locate.listPointer ${JSON.stringify(locate.listPointer)} in the response from ${config.url}`,
+                transport: { httpStatus },
+            });
+            return;
+        }
+        const matches = list.value.filter((item) => locate.match.every((rule) => {
+            const value = resolvePointer(item, rule.pointer);
+            if (!value.found) {
+                return false;
+            }
+            if (rule.subjectField !== undefined) {
+                return jsonEqual(value.value, request.subject[rule.subjectField]);
+            }
+            return jsonEqual(value.value, rule.equals);
+        }));
+        if (matches.length === 0) {
+            writeResponse(request, {
+                outcome: "absent",
+                reason: `no release object matches the subject in the listing from ${config.url} ` +
+                    `(${String(list.value.length)} object(s) examined against ${String(locate.match.length)} match rule(s))`,
+                observation: {
+                    raw: { objectsExamined: list.value.length },
+                    detail: "no release object for subject",
+                },
+                transport: { httpStatus },
+            });
+            return;
+        }
+        target = matches[0];
+        const id = resolvePointer(target, locate.idPointer);
+        if (!id.found || typeof id.value !== "string") {
+            writeResponse(request, {
+                outcome: "error",
+                reason: `located object has no string value at locate.idPointer ${JSON.stringify(locate.idPointer)}`,
+                transport: { httpStatus },
+            });
+            return;
+        }
+        resolved = { kind: locate.kind ?? "release-object", id: id.value };
+        if (locate.createdAtPointer !== undefined) {
+            const created = resolvePointer(target, locate.createdAtPointer);
+            if (created.found) {
+                resolved["createdAt"] = created.value;
+            }
+        }
+        if (matches.length > 1) {
+            resolved["matchCount"] = matches.length;
+        }
+    }
+    // Observe. One satisfying value; verbatim recording of everything else.
+    const status = resolvePointer(target, config.observe.statusPointer);
+    const observedRaw = {};
+    observedRaw[config.observe.statusPointer] = status.found
+        ? status.value
+        : "(no value)";
+    let terminal = false;
+    if (hasTerminalPointer) {
+        const terminalObserved = resolvePointer(target, config.observe.terminalPointer);
+        observedRaw[config.observe.terminalPointer] = terminalObserved.found
+            ? terminalObserved.value
+            : "(no value)";
+        terminal =
+            terminalObserved.found &&
+                jsonEqual(terminalObserved.value, config.observe.terminalValue);
+    }
+    const satisfied = status.found && jsonEqual(status.value, config.observe.satisfiedValue);
+    const detail = `${config.observe.statusPointer} = ${display(status.found ? status.value : undefined)}` +
+        (hasTerminalPointer
+            ? `, ${config.observe.terminalPointer} = ${display(observedRaw[config.observe.terminalPointer])}`
+            : "");
+    if (satisfied) {
+        writeResponse(request, {
+            outcome: "satisfied",
+            resolved,
+            observation: { raw: observedRaw, detail },
+            transport: { httpStatus },
+        });
+        return;
+    }
+    if (hasTerminalPointer && terminal) {
+        // The platform's state machine is finished and the satisfying value is
+        // not there: a terminal non-success, named verbatim, never enumerated.
+        writeResponse(request, {
+            outcome: "failed",
+            resolved,
+            reason: `terminal state reached with a non-satisfying value: ${detail} ` +
+                `(satisfying value is ${display(config.observe.satisfiedValue)})`,
+            observation: { raw: observedRaw, detail },
+            transport: { httpStatus },
+        });
+        return;
+    }
+    writeResponse(request, {
+        outcome: "pending",
+        resolved,
+        observation: { raw: observedRaw, detail },
+        transport: { httpStatus },
+    });
+}
+async function main() {
+    const requestPath = process.argv[2];
+    if (requestPath === undefined) {
+        process.stderr.write(`usage: node src/gates/adapters/http-json.ts <request-file>\n`);
+        process.exitCode = 64;
+        return;
+    }
+    const read = readRegularFileIfPresent(requestPath);
+    if (read.kind !== "read") {
+        process.stderr.write(`${ADAPTER_NAME}: request file ${requestPath} ${read.kind === "absent" ? "does not exist" : `refused: ${read.reason}`}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    let request;
+    try {
+        request = JSON.parse(read.body);
+    }
+    catch (error) {
+        process.stderr.write(`${ADAPTER_NAME}: request file does not parse as JSON: ${error.message}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    await observeOnce(request);
+}
+function isMain() {
+    const argv1 = process.argv[1];
+    if (argv1 === undefined) {
+        return false;
+    }
+    try {
+        return realpathSync(argv1) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+if (isMain()) {
+    await main();
+}

package/dist/src/gates/adapters/migrations-command.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/gates/adapters/migrations-command.js

@@ -0,0 +1,373 @@
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { readdirSync, realpathSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { classifyEntry, readRegularFileIfPresent, refuseOpenForWrite, singleLine, } from "../../task.js";
+const ADAPTER_NAME = "migrations-command";
+/** RFC 6901 JSON pointer resolution, local to this adapter's configuration. */
+function resolvePointer(document, pointer) {
+    if (pointer === "") {
+        return { found: true, value: document };
+    }
+    if (!pointer.startsWith("/")) {
+        return { found: false };
+    }
+    let current = document;
+    for (const rawToken of pointer.slice(1).split("/")) {
+        const token = rawToken.split("~1").join("/").split("~0").join("~");
+        if (Array.isArray(current)) {
+            const index = Number(token);
+            if (!Number.isInteger(index) || index < 0 || index >= current.length) {
+                return { found: false };
+            }
+            current = current[index];
+            continue;
+        }
+        if (typeof current === "object" && current !== null) {
+            if (!Object.hasOwn(current, token)) {
+                return { found: false };
+            }
+            current = current[token];
+            continue;
+        }
+        return { found: false };
+    }
+    return { found: true, value: current };
+}
+function writeResponse(request, fields) {
+    const refusal = refuseOpenForWrite(request.recordPath);
+    if (refusal !== undefined) {
+        process.stderr.write(`${ADAPTER_NAME}: ${refusal}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const response = {
+        contractVersion: "1",
+        adapter: ADAPTER_NAME,
+        subject: request.subject,
+        outcome: fields.outcome,
+        ...(fields.resolved === undefined ? {} : { resolved: fields.resolved }),
+        observedAt: new Date().toISOString(),
+        ...(fields.observation === undefined ? {} : { observation: fields.observation }),
+        ...(fields.reason === undefined ? {} : { reason: fields.reason }),
+        ...(fields.units === undefined ? {} : { units: fields.units }),
+        ...(fields.precondition === undefined ? {} : { precondition: fields.precondition }),
+    };
+    writeFileSync(request.recordPath, `${JSON.stringify(response, null, 2)}\n`);
+}
+function configError(request, field, message) {
+    writeResponse(request, {
+        outcome: "error",
+        reason: `misconfiguration at config.${field}: ${message}`,
+    });
+}
+function observeOnce(request) {
+    const config = request.config;
+    if (typeof config?.migrationsDir !== "string" || config.migrationsDir === "") {
+        configError(request, "migrationsDir", "a repository migrations directory is required");
+        return;
+    }
+    if (typeof config.pattern !== "string" || config.pattern === "") {
+        configError(request, "pattern", "a filename pattern is required");
+        return;
+    }
+    if (!Array.isArray(config.appliedCommand) || config.appliedCommand.length === 0) {
+        configError(request, "appliedCommand", "an applied-inventory command argv is required");
+        return;
+    }
+    if (typeof config.appliedPointer !== "string") {
+        configError(request, "appliedPointer", "a JSON pointer to the applied list is required");
+        return;
+    }
+    if (typeof config.idPointer !== "string") {
+        configError(request, "idPointer", "a JSON pointer to each entry's id is required");
+        return;
+    }
+    let pattern;
+    try {
+        pattern = new RegExp(config.pattern);
+    }
+    catch (error) {
+        configError(request, "pattern", `not a valid expression: ${error.message}`);
+        return;
+    }
+    // REPOSITORY inventory. The directory and its files are paths this
+    // adapter did not create: M2-C-6, type established before any open, a
+    // non-regular entry is error naming the path and the type, never a block.
+    const dirEntry = classifyEntry(config.migrationsDir);
+    if (dirEntry.kind === "absent" || dirEntry.kind === "dangling") {
+        writeResponse(request, {
+            outcome: "not-applicable",
+            reason: `repository migrations directory ${config.migrationsDir} does not exist`,
+            precondition: {
+                id: "repository-migrations-present",
+                evidence: [`${config.migrationsDir}: absent`],
+            },
+        });
+        return;
+    }
+    if (dirEntry.kind === "unexaminable") {
+        writeResponse(request, { outcome: "error", reason: dirEntry.reason });
+        return;
+    }
+    if (dirEntry.kind === "regular") {
+        writeResponse(request, {
+            outcome: "error",
+            reason: `${config.migrationsDir} is a regular file, not a directory`,
+        });
+        return;
+    }
+    let names;
+    try {
+        names = readdirSync(config.migrationsDir);
+    }
+    catch (error) {
+        writeResponse(request, {
+            outcome: "error",
+            reason: `${config.migrationsDir} could not be listed: ${singleLine(String(error))}`,
+        });
+        return;
+    }
+    const matching = names.filter((name) => pattern.test(name)).sort();
+    if (matching.length === 0) {
+        writeResponse(request, {
+            outcome: "not-applicable",
+            reason: `repository migrations directory ${config.migrationsDir} contains zero ` +
+                `migrations matching ${config.pattern}`,
+            precondition: {
+                id: "repository-migrations-present",
+                evidence: [
+                    `${config.migrationsDir}: ${String(names.length)} entr(ies), 0 matching ${config.pattern}`,
+                ],
+            },
+        });
+        return;
+    }
+    const repository = new Map();
+    for (const name of matching) {
+        const path = join(config.migrationsDir, name);
+        const read = readRegularFileIfPresent(path);
+        if (read.kind === "refused") {
+            // M2-C-6: a FIFO or other non-regular entry in the migrations
+            // directory is error naming the path and the observed type.
+            writeResponse(request, { outcome: "error", reason: read.reason });
+            return;
+        }
+        if (read.kind === "absent") {
+            writeResponse(request, {
+                outcome: "error",
+                reason: `${path} vanished between listing and reading`,
+            });
+            return;
+        }
+        const match = pattern.exec(name);
+        const id = match !== null && match[1] !== undefined ? match[1] : name;
+        repository.set(id, {
+            file: name,
+            sha256: createHash("sha256").update(read.body).digest("hex"),
+        });
+    }
+    // APPLIED inventory: another program's output, parsed only at the
+    // project-declared pointers, never pattern-matched as text.
+    const child = spawnSync(config.appliedCommand[0], config.appliedCommand.slice(1), { encoding: "utf8" });
+    if (child.error !== undefined) {
+        writeResponse(request, {
+            outcome: "error",
+            reason: `applied-inventory command could not be run: ${singleLine(String(child.error))}`,
+        });
+        return;
+    }
+    if (child.status !== 0) {
+        writeResponse(request, {
+            outcome: "error",
+            reason: `applied-inventory command exited ${String(child.status)}: ` +
+                `${singleLine(child.stderr ?? "")}`,
+        });
+        return;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(child.stdout ?? "");
+    }
+    catch (error) {
+        writeResponse(request, {
+            outcome: "error",
+            reason: `applied-inventory output does not parse as JSON: ${error.message}`,
+        });
+        return;
+    }
+    const list = resolvePointer(parsed, config.appliedPointer);
+    if (!list.found || !Array.isArray(list.value)) {
+        writeResponse(request, {
+            outcome: "error",
+            reason: `no array at appliedPointer ${JSON.stringify(config.appliedPointer)} in the applied-inventory output`,
+        });
+        return;
+    }
+    const applied = new Map();
+    for (let index = 0; index < list.value.length; index += 1) {
+        const entry = list.value[index];
+        const id = resolvePointer(entry, config.idPointer);
+        if (!id.found || (typeof id.value !== "string" && typeof id.value !== "number")) {
+            writeResponse(request, {
+                outcome: "error",
+                reason: `applied entry ${String(index)} has no string or number value at ` +
+                    `idPointer ${JSON.stringify(config.idPointer)}`,
+            });
+            return;
+        }
+        const record = {};
+        if (config.checksumPointer !== undefined) {
+            // Content verification was requested. A usable checksum is a non-empty
+            // string; null, absent, empty or non-string is NOT a usable checksum,
+            // and (CR-P7H-2) must not silently reduce this row to an id-only pass.
+            const checksum = resolvePointer(entry, config.checksumPointer);
+            if (checksum.found && typeof checksum.value === "string" && checksum.value !== "") {
+                record.checksum = checksum.value;
+            }
+            else {
+                record.checksumAbsent = true;
+            }
+        }
+        applied.set(String(id.value), record);
+    }
+    const repositoryIds = [...repository.keys()];
+    const appliedIds = [...applied.keys()];
+    const raw = { repository: repositoryIds, applied: appliedIds };
+    // Drift: applied migrations the repository does not have. Terminal.
+    const drift = appliedIds.filter((id) => !repository.has(id)).sort();
+    if (drift.length > 0) {
+        writeResponse(request, {
+            outcome: "failed",
+            resolved: { kind: "applied-migrations", id: appliedIds.join(",") },
+            reason: `applied inventory contains ${String(drift.length)} migration(s) the ` +
+                `repository does not: ${drift.join(", ")} (drift)`,
+            observation: { raw, detail: `drift: ${drift.join(", ")}` },
+        });
+        return;
+    }
+    // Content drift where both sides expose a checksum. Terminal.
+    for (const [id, entry] of repository) {
+        const appliedEntry = applied.get(id);
+        if (appliedEntry?.checksum !== undefined && appliedEntry.checksum !== entry.sha256) {
+            writeResponse(request, {
+                outcome: "failed",
+                resolved: { kind: "applied-migrations", id: appliedIds.join(",") },
+                reason: `migration ${id} (${entry.file}) is applied with checksum ` +
+                    `${appliedEntry.checksum}, repository content sha256 is ${entry.sha256} ` +
+                    `(content drift)`,
+                observation: { raw, detail: `content drift: ${id}` },
+            });
+            return;
+        }
+    }
+    // CR-P7H-2: content verification was requested (checksumPointer configured)
+    // but a MATCHED row (present in both inventories) exposes no usable applied
+    // checksum, so the comparison the config asked for could not be made. This
+    // is NOT a silent pass on id-match: an unchecked assumption never becomes a
+    // green (M2-C-3). It is surfaced as error naming the ids, and observation.raw
+    // discloses which rows were checksum-compared versus which could not be.
+    // Terminal, and ahead of the missing/pending check, because waiting cannot
+    // add a checksum the applied inventory does not expose. Two structurally
+    // different members reach this: an applied checksum of null, and an absent
+    // checksum key (both set checksumAbsent above).
+    if (config.checksumPointer !== undefined) {
+        const checksumCompared = repositoryIds
+            .filter((id) => applied.get(id)?.checksum !== undefined)
+            .sort();
+        const checksumAbsent = repositoryIds
+            .filter((id) => applied.get(id)?.checksumAbsent === true)
+            .sort();
+        if (checksumAbsent.length > 0) {
+            writeResponse(request, {
+                outcome: "error",
+                resolved: { kind: "applied-migrations", id: appliedIds.join(",") },
+                reason: `checksumPointer ${JSON.stringify(config.checksumPointer)} is configured, but ` +
+                    `${String(checksumAbsent.length)} matched migration(s) expose no applied checksum, ` +
+                    `so the requested content comparison could not be made: ${checksumAbsent.join(", ")}; ` +
+                    `an unverifiable row is not a silent pass on id-match (M2-C-3)`,
+                observation: {
+                    raw: { ...raw, checksumCompared, checksumAbsent },
+                    detail: `checksum requested but absent for: ${checksumAbsent.join(", ")}`,
+                },
+            });
+            return;
+        }
+    }
+    // Missing: repository migrations the applied inventory does not show.
+    // Pending, never a terminal red here: the apply job may be queued, and
+    // the kernel's deadline is what turns a wait into a red.
+    const missing = repositoryIds.filter((id) => !applied.has(id)).sort();
+    if (missing.length > 0) {
+        writeResponse(request, {
+            outcome: "pending",
+            resolved: {
+                kind: "applied-migrations",
+                id: appliedIds.length === 0 ? "(empty applied inventory)" : appliedIds.join(","),
+            },
+            observation: {
+                raw,
+                detail: `migrations not applied: ${missing.join(", ")}`,
+            },
+        });
+        return;
+    }
+    // Every matched row was id-matched, and (when checksumPointer is configured)
+    // every matched row also exposed a usable checksum that agreed: an absent
+    // one would have been surfaced as error above, so a green here is auditable.
+    const satisfiedRaw = config.checksumPointer === undefined
+        ? raw
+        : { ...raw, checksumCompared: repositoryIds };
+    writeResponse(request, {
+        outcome: "satisfied",
+        resolved: { kind: "applied-migrations", id: repositoryIds.join(",") },
+        observation: {
+            raw: satisfiedRaw,
+            detail: `${String(repositoryIds.length)} migration(s) applied and matching` +
+                (config.checksumPointer === undefined
+                    ? ""
+                    : ` (all ${String(repositoryIds.length)} checksum(s) compared and matched)`),
+        },
+        units: repositoryIds.length,
+    });
+}
+function main() {
+    const requestPath = process.argv[2];
+    if (requestPath === undefined) {
+        process.stderr.write(`usage: node src/gates/adapters/migrations-command.ts <request-file>\n`);
+        process.exitCode = 64;
+        return;
+    }
+    const read = readRegularFileIfPresent(requestPath);
+    if (read.kind !== "read") {
+        process.stderr.write(`${ADAPTER_NAME}: request file ${requestPath} ${read.kind === "absent" ? "does not exist" : `refused: ${read.reason}`}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    let request;
+    try {
+        request = JSON.parse(read.body);
+    }
+    catch (error) {
+        process.stderr.write(`${ADAPTER_NAME}: request file does not parse as JSON: ${error.message}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    observeOnce(request);
+}
+function isMain() {
+    const argv1 = process.argv[1];
+    if (argv1 === undefined) {
+        return false;
+    }
+    try {
+        return realpathSync(argv1) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+if (isMain()) {
+    main();
+}