@zq-silk/yui 2.8.0 → 2.9.0

package/dist/controller/jobControl.js

@@ -9,7 +9,7 @@
  * preserves its admitted Job across authorized Session replacement.
  */
 import { execSync } from "node:child_process";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { resolve, sep } from "node:path";
 import { activeLiveRoleAgentSession } from "../executor/agentExecutor.js";
 import { acknowledgeUnknownDurableJob, createDurableJob, durableJobIdempotencyKey, isDurableJobTerminal, requestDurableJobCancel, retryDurableJobIdempotencyKey } from "../job/durableJob.js";
@@ -21,6 +21,7 @@ import { assertJobAssignmentScope, JobAssignmentScopeError } from "../job/jobAss
 import { assertContextRecordReadable } from "../context/taskContext.js";
 import { assertTaskProjectWriteAuthority } from "../task/taskAuthority.js";
 import { validateHttpPreview } from "../job/httpPreview.js";
+import { definitionFromTaskRun } from "../job/jobDefinition.js";
 export function createDurableJobControl(store) {
     const authority = createJobCallAuthority(store);
     return {
@@ -34,7 +35,7 @@ export function createDurableJobControl(store) {
                 requireJobAssignment(tx, params, params.caller);
                 assertNonSecretJobInput(params);
                 validateHttpPreview(params.env, params.steps);
-                const baseKey = durableJobIdempotencyKey({
+                const specificationKey = durableJobIdempotencyKey({
                     owner: params.owner,
                     projectId: params.projectId,
                     head: params.head,
@@ -42,6 +43,12 @@ export function createDurableJobControl(store) {
                     workspace: params.workspace,
                     env: params.env
                 });
+                const definition = params.definitionId === undefined ? null
+                    : tx.getJobDefinition({ kind: "task", taskId: params.taskId }, params.definitionId);
+                if (params.definitionId !== undefined && definition === null)
+                    throw jobDomainError("Job definition not found.");
+                const baseKey = definition === null ? specificationKey : createHash("sha256")
+                    .update(JSON.stringify([specificationKey, definition.id, definition.revision, params.trigger])).digest("hex");
                 const inputDigest = params.retryOf === undefined
                     ? baseKey
                     : retryDurableJobIdempotencyKey(baseKey, params.retryOf);
@@ -77,9 +84,29 @@ export function createDurableJobControl(store) {
                 }
                 authority.authorize(context, params.taskId);
                 validateStartParams(tx, params);
+                const previous = params.retryOf === undefined ? null : tx.getDurableJob(params.taskId, params.retryOf);
+                if (previous !== null) {
+                    requireJobAssignment(tx, previous, params.caller);
+                    if (definition === null && durableJobIdempotencyKey(previous) !== specificationKey) {
+                        throw jobDomainError("Legacy retry must preserve the original Run specification; update its Job definition for a changed configuration.");
+                    }
+                }
+                const definitionId = definition?.id ?? previous?.definitionId;
+                if (definitionId !== undefined) {
+                    const active = tx.listDurableJobs(params.taskId).find(run => run.definitionId === definitionId
+                        && (run.status === "queued" || run.status === "running" || run.status === "unknown-needs-attention"));
+                    if (active !== undefined)
+                        throw jobDomainError(`Job is already occupied by Run ${active.id} (${active.status}); no new Run was admitted.`);
+                }
                 const id = tx.nextDurableJobId(params.taskId);
                 const job = createDurableJob({
                     id,
+                    definitionId: definitionId ?? `definition-${randomUUID()}`,
+                    definitionRevision: definition?.revision ?? previous?.definitionRevision,
+                    trigger: params.trigger ?? {
+                        source: params.retryOf !== undefined ? "retry" : params.owner.kind === "integration-attempt" ? "integration" : "manual",
+                        key: requestId
+                    },
                     taskId: params.taskId,
                     owner: params.owner,
                     projectId: params.projectId,
@@ -94,6 +121,9 @@ export function createDurableJobControl(store) {
                     artifactsLocator: `artifacts/jobs/${params.taskId}/${id}`,
                     ...(params.retryOf === undefined ? {} : { retryOf: params.retryOf })
                 }, now);
+                if (tx.getJobDefinition({ kind: "task", taskId: params.taskId }, job.definitionId) === null) {
+                    tx.saveJobDefinition(definitionFromTaskRun(job));
+                }
                 tx.saveDurableJob(params.taskId, job);
                 return { job, created: true };
             });
@@ -191,7 +221,7 @@ function assertLeaderJobWriteScope(store, target, caller) {
         throw jobControlError("UNAUTHORIZED", error instanceof Error ? error.message : String(error));
     }
 }
-function requireJobAssignment(store, target, caller) {
+export function requireJobAssignment(store, target, caller) {
     try {
         assertJobAssignmentScope(store, target, caller);
     }
@@ -201,7 +231,7 @@ function requireJobAssignment(store, target, caller) {
         throw error;
     }
 }
-function jobAuthorityBinding(store, scope, roleName, taskId) {
+export function jobAuthorityBinding(store, scope, roleName, taskId) {
     // A Host detach/reattach preserves the native Session and its queued work.
     // Authenticate the live launch at ingress, but bind accepted Jobs to the
     // caller's durable Session identity, not its disposable Host generation.
@@ -232,7 +262,7 @@ function jobAuthorityBinding(store, scope, roleName, taskId) {
         role.activeAgentId, session.agentId, session.nativeSessionId
     ])).digest("hex");
 }
-function assertNonSecretJobInput(params) {
+export function assertNonSecretJobInput(params) {
     // Existing Jobs persist commands and environments. This boundary accepts
     // non-secret executable specifications only; credential resolution is not a
     // Job feature. Never hash a known secret then call the digest sanitized.
@@ -263,7 +293,7 @@ function assertNonSecretJobInput(params) {
  * workspace was not the stable checkout. Now it binds the job to the exact
  * managed workspace, verifies write access, and requires an active Task.
  */
-function validateStartParams(store, params) {
+export function validateStartParams(store, params) {
     validateJobTarget(store, params);
     assertCallerAuthorized(store, params.caller, params.taskId);
     assertLeaderJobWriteScope(store, params, params.caller);
@@ -384,7 +414,7 @@ function validateJobTarget(store, params) {
  * identity contract does not defend against another process with the same
  * user's filesystem access. Bare user calls cannot start or cancel Jobs.
  */
-function assertCallerAuthorized(store, caller, taskId) {
+export function assertCallerAuthorized(store, caller, taskId) {
     if (caller.scope === "user") {
         // rr13: A user-scope caller has no per-Session channel binding. Every
         // durable-state claim it could carry is replayable
@@ -508,7 +538,7 @@ export function parseDurableJobStartParams(value) {
     const retryOf = record.retryOf === undefined
         ? undefined
         : requiredId(record.retryOf, "job.start retryOf");
-    const caller = parseCaller(record.caller);
+    const caller = parseDurableJobCaller(record.caller);
     return {
         taskId,
         owner,
@@ -531,7 +561,7 @@ export function parseDurableJobRefParams(value) {
     return {
         taskId: requiredId(record.taskId, "DurableJob taskId"),
         jobId: requiredId(record.jobId, "DurableJob jobId"),
-        caller: parseCaller(record.caller)
+        caller: parseDurableJobCaller(record.caller)
     };
 }
 /**
@@ -548,7 +578,7 @@ export function parseDurableJobCancelParams(value) {
     return {
         taskId: requiredId(record.taskId, "DurableJob taskId"),
         jobId: requiredId(record.jobId, "DurableJob jobId"),
-        caller: parseCaller(record.caller)
+        caller: parseDurableJobCaller(record.caller)
     };
 }
 /**
@@ -564,7 +594,7 @@ export function parseDurableJobAcknowledgeParams(value) {
     return {
         taskId: requiredId(record.taskId, "DurableJob taskId"),
         jobId: requiredId(record.jobId, "DurableJob jobId"),
-        caller: parseCaller(record.caller)
+        caller: parseDurableJobCaller(record.caller)
     };
 }
 function parseJobOwner(value) {
@@ -645,7 +675,7 @@ function parseSteps(value) {
  * optional managed Session identity fields. The identity is verified against
  * durable state by `assertCallerAuthorized`; parsing only validates the JSON shape.
  */
-function parseCaller(value) {
+export function parseDurableJobCaller(value) {
     if (value === undefined) {
         throw jobControlError("INVALID_PARAMS", "job caller is required.");
     }

package/dist/controller/jobDefinitionControl.js

@@ -0,0 +1,304 @@
+import { createHash, randomUUID } from "node:crypto";
+import { openSync, closeSync, fstatSync, readSync, realpathSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { requireKnownFields } from "../domain/validation.js";
+import { createJobDefinition, reviseJobDefinition, jobScopeKey, validateJobDefinition } from "../job/jobDefinition.js";
+import { acknowledgeUnknownDurableJob, requestDurableJobCancel, validateDurableJob, JOB_RUNNER_IMPLEMENTATION, executionNamespace } from "../job/durableJob.js";
+import { prepareBuiltinJob, projectRefreshDigest } from "../job/builtinJob.js";
+import { projectRefreshTargetDigest, requireRefreshProject } from "../repository/projectRefresh.js";
+import { assertCallerAuthorized, assertNonSecretJobInput, createDurableJobControl, jobAuthorityBinding, validateStartParams, requireJobAssignment, parseDurableJobCaller } from "./jobControl.js";
+import { createFileArtifactPort } from "./jobSupervisor.js";
+export function authorizeScope(store, scope, caller) {
+    parseDurableJobCaller(caller);
+    jobScopeKey(scope);
+    // Match Task Context's Operator-only boundary for global callers as well
+    // as excluding Task callers from global Jobs. Session identity alone is not
+    // permission for a custom GlobalRole to read or manage Task definitions.
+    if ((scope.kind === "global" && caller.scope !== "global")
+        || (caller.scope === "global" && caller.role !== "operator")) {
+        throw Object.assign(new Error("Only the current Operator Session may access Jobs across global scope."), { name: "CoreApplicationError", code: "UNAUTHORIZED" });
+    }
+    assertCallerAuthorized(store, caller, scope.kind === "task" ? scope.taskId : "");
+}
+function taskParams(job, caller, requestId) {
+    if (job.scope.kind !== "task" || job.configuration.kind !== "shell")
+        throw new Error("Not a Task Job.");
+    return { ...job.configuration, taskId: job.scope.taskId, caller, requestId };
+}
+export function authorizeDefinition(store, job, caller, write) {
+    authorizeScope(store, job.scope, caller);
+    if (job.scope.kind === "task") {
+        const params = taskParams(job, caller, "definition-validation");
+        // A definition must not reveal another Assignment's commands/environment.
+        requireJobAssignment(store, params, caller);
+        if (write)
+            validateStartParams(store, params);
+        if (write)
+            assertNonSecretJobInput(params);
+    }
+    else if (write) {
+        if (job.configuration.kind !== "builtin")
+            throw new Error("Global Jobs require builtin actions.");
+        prepareBuiltinJob(job.configuration, "/");
+        if (job.configuration.action === "project.refresh") {
+            const project = requireRefreshProject(store, job.configuration.projectId, true);
+            if (projectRefreshDigest(job.configuration) !== projectRefreshTargetDigest(project)) {
+                throw new Error("Project refresh target changed; inspect the Project and explicitly update the Job.");
+            }
+            const duplicate = store.listJobDefinitions({ kind: "global" }).find(other => other.id !== job.id && other.configuration.kind === "builtin"
+                && other.configuration.action === "project.refresh" && other.configuration.projectId === project.id);
+            if (duplicate)
+                throw new Error(`Project refresh Job already exists: ${duplicate.id}.`);
+        }
+    }
+}
+export function listJobRuns(store, job) {
+    return (job.scope.kind === "task" ? store.listDurableJobs(job.scope.taskId) : store.listGlobalJobRuns())
+        .filter(run => run.definitionId === job.id);
+}
+/** Read-only presentation; attempts/results remain owned by exact JobRuns. */
+function presentDefinition(store, job) {
+    if (job.configuration.kind !== "builtin" || job.configuration.action !== "project.refresh")
+        return job;
+    const projectId = job.configuration.projectId;
+    const targetDigest = projectRefreshDigest(job.configuration);
+    const runs = listJobRuns(store, job).filter(run => !("taskId" in run)
+        && run.action === "project.refresh" && run.projectId === projectId
+        && projectRefreshDigest({ kind: "builtin", action: run.action,
+            projectId: run.projectId, input: run.actionInput }) === targetDigest)
+        .sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+    const summarize = (run) => run === undefined ? null : {
+        runId: run.id, definitionRevision: run.definitionRevision, trigger: run.trigger,
+        status: run.status, attemptedAt: run.createdAt, finishedAt: run.terminalAt ?? null
+    };
+    return { ...job, refresh: {
+            projectId, lastAttempt: summarize(runs[0]),
+            lastSuccessfulRefresh: summarize(runs.find(run => run.status === "succeeded"))
+        } };
+}
+function authorizeRunRead(store, run, caller) {
+    // A revised definition's Assignment does not grant access to earlier Runs.
+    if ("taskId" in run)
+        createDurableJobControl(store).getJob(run.taskId, run.id, caller);
+}
+/**
+ * The narrow Schedule seam: call inside the SAME TaskStore transaction as
+ * schedule advancement. No external effects occur here; rollback removes the
+ * admission as well. The caller must be freshly authenticated on every call.
+ */
+export function admitJobRun(store, home, scope, definitionId, caller, trigger, now, retryOf) {
+    return store.transaction(tx => {
+        const job = tx.getJobDefinition(scope, definitionId);
+        if (job === null)
+            throw new Error("Job definition not found.");
+        authorizeDefinition(tx, job, caller, false);
+        if (!trigger.key.trim() || !["manual", "retry", "schedule", "integration"].includes(trigger.source)) {
+            throw new Error("Invalid JobRun trigger.");
+        }
+        const runs = listJobRuns(tx, job);
+        const same = runs.find(run => run.trigger.key === trigger.key && run.trigger.source === trigger.source);
+        if (same !== undefined) {
+            authorizeRunRead(tx, same, caller);
+            if (same.definitionRevision !== job.revision || same.retryOf !== retryOf) {
+                throw new Error(`JobRun trigger conflicts with its original snapshot: ${same.id}.`);
+            }
+            return { run: same, created: false };
+        }
+        authorizeDefinition(tx, job, caller, true);
+        const occupied = runs.find(run => run.status === "queued" || run.status === "running"
+            || run.status === "unknown-needs-attention");
+        if (occupied !== undefined) {
+            authorizeRunRead(tx, occupied, caller);
+            return { run: occupied, created: false, reason: "overlap" };
+        }
+        if (retryOf !== undefined && !runs.some(run => run.id === retryOf
+            && ["failed", "cancelled", "timed-out"].includes(run.status))) {
+            throw new Error("Retry requires an exact failed/cancelled/timed-out Run of this Job.");
+        }
+        const requestId = `job:${job.id}:${trigger.source}:${trigger.key}`;
+        if (scope.kind === "task") {
+            const result = createDurableJobControl(tx).startJob({
+                ...taskParams(job, caller, requestId), definitionId, trigger, retryOf
+            }, now);
+            return { run: result.job, created: result.created };
+        }
+        if (job.configuration.kind !== "builtin")
+            throw new Error("Global Jobs require builtin actions.");
+        const id = `job-${randomUUID()}`;
+        const locator = `artifacts/jobs/global/${id}`;
+        const spec = prepareBuiltinJob(job.configuration, join(home, locator), { home, runId: id });
+        const actorId = `global:${caller.role}`;
+        const run = validateDurableJob({
+            schemaVersion: 1, scope: "global", id, definitionId: job.id, definitionRevision: job.revision,
+            trigger: structuredClone(trigger), action: job.configuration.action,
+            actionInput: structuredClone(job.configuration.input),
+            ...(job.configuration.projectId === undefined ? {} : { projectId: job.configuration.projectId }),
+            ...spec, status: "queued", artifactsLocator: locator,
+            idempotencyKey: createHash("sha256").update(JSON.stringify([actorId, requestId])).digest("hex"),
+            operation: {
+                requestId, actorId, authorityRef: jobAuthorityBinding(tx, "global", caller.role, ""),
+                targetId: job.id, capability: "job.run", implementation: JOB_RUNNER_IMPLEMENTATION,
+                inputDigest: createHash("sha256").update(JSON.stringify([job, trigger, retryOf])).digest("hex"),
+                effect: "none", receiptRefs: [], partialResultRefs: []
+            },
+            ...(retryOf === undefined ? {} : { retryOf }),
+            createdAt: now.toISOString(), updatedAt: now.toISOString()
+        });
+        tx.saveGlobalJobRun(run);
+        return { run, created: true };
+    });
+}
+export function authorizeGlobalJobStart(store, run) {
+    if (run.operation.actorId !== "global:operator"
+        || jobAuthorityBinding(store, "global", "operator", "") !== run.operation.authorityRef) {
+        throw Object.assign(new Error("Global JobRun caller binding was revoked; no execution was started."), { name: "CoreJobError" });
+    }
+    // Storage failures are not domain refusals or proof of no execution.
+    const projects = run.action === "project.refresh" ? store.listProjects() : [];
+    const home = store.rootDirectory();
+    try {
+        const compiled = prepareBuiltinJob({
+            kind: "builtin", action: run.action, input: run.actionInput,
+            ...(run.projectId === undefined ? {} : { projectId: run.projectId })
+        }, run.workspace, { home, runId: run.id });
+        if (run.action === "project.refresh") {
+            const project = requireRefreshProject({ listProjects: () => projects, rootDirectory: () => home }, run.projectId, true);
+            if (projectRefreshTargetDigest(project) !== projectRefreshDigest({
+                kind: "builtin", action: run.action, projectId: run.projectId, input: run.actionInput
+            }))
+                throw new Error("Project refresh target changed before execution.");
+            if (run.workspace !== join(home, "artifacts/jobs/global", run.id)) {
+                throw new Error("Project refresh Run workspace does not match its artifact directory.");
+            }
+        }
+        if (JSON.stringify(compiled.steps) !== JSON.stringify(run.steps)
+            || JSON.stringify(compiled.env) !== JSON.stringify(run.env) || compiled.head !== run.head) {
+            throw new Error("Global JobRun does not match its controlled action.");
+        }
+    }
+    catch (error) {
+        throw Object.assign(new Error(error instanceof Error ? error.message : String(error), { cause: error }), { name: "CoreJobError" });
+    }
+}
+/** One bounded RPC surface; legacy job.start/get/cancel remain exact-run APIs. */
+export function createJobDefinitionControl(store, home) {
+    return (value, now) => {
+        if (value === null || typeof value !== "object" || Array.isArray(value))
+            throw new Error("Invalid Job request.");
+        requireKnownFields(value, ["op", "scope", "caller", "id", "title", "configuration", "expectedRevision", "trigger", "retryOf", "runId"], "Job request");
+        const input = value;
+        authorizeScope(store, input.scope, input.caller);
+        return store.transaction(tx => {
+            if (input.op === "list") {
+                return tx.listJobDefinitions(input.scope).filter(job => {
+                    try {
+                        authorizeDefinition(tx, job, input.caller, false);
+                        return true;
+                    }
+                    catch {
+                        return false;
+                    }
+                }).map(job => presentDefinition(tx, job));
+            }
+            if (typeof input.id !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/u.test(input.id))
+                throw new Error("An explicit safe Job id is required.");
+            const existing = tx.getJobDefinition(input.scope, input.id);
+            if (input.op === "define" || input.op === "update") {
+                let configuration = input.configuration;
+                // Empty input is an explicit request to bind the current catalog target.
+                // A saved digest is never silently refreshed on run/retry.
+                if (input.scope.kind === "global" && configuration?.kind === "builtin"
+                    && configuration.action === "project.refresh" && JSON.stringify(configuration.input) === "{}") {
+                    const project = requireRefreshProject(tx, configuration.projectId, true);
+                    configuration = { ...configuration, input: { targetDigest: projectRefreshTargetDigest(project) } };
+                }
+                const fields = { title: input.title, configuration };
+                if (input.op === "define") {
+                    const next = createJobDefinition({ id: input.id, scope: input.scope, ...fields }, now);
+                    authorizeDefinition(tx, next, input.caller, true);
+                    if (existing !== null) {
+                        if (JSON.stringify(existing.configuration) !== JSON.stringify(next.configuration) || existing.title !== next.title) {
+                            throw new Error("Job id already exists with different configuration; use update with its revision.");
+                        }
+                        return existing;
+                    }
+                    tx.saveJobDefinition(next);
+                    return next;
+                }
+                if (existing === null || existing.revision !== input.expectedRevision)
+                    throw new Error("Job revision changed or Job missing.");
+                // The old snapshot may no longer be runnable (for example HEAD moved).
+                // Check its ownership before validating the replacement for execution.
+                authorizeDefinition(tx, existing, input.caller, false);
+                const next = reviseJobDefinition(existing, fields, now);
+                authorizeDefinition(tx, next, input.caller, true);
+                tx.saveJobDefinition(next);
+                return next;
+            }
+            if (existing === null)
+                throw new Error("Job definition not found.");
+            validateJobDefinition(existing);
+            authorizeDefinition(tx, existing, input.caller, false);
+            if (input.op === "show")
+                return presentDefinition(tx, existing);
+            if (input.op === "runs")
+                return listJobRuns(tx, existing).filter(run => {
+                    try {
+                        authorizeRunRead(tx, run, input.caller);
+                        return true;
+                    }
+                    catch {
+                        return false;
+                    }
+                });
+            if (input.op === "run") {
+                if (input.trigger === undefined)
+                    throw new Error("A trigger identity is required.");
+                // Schedule is an internal transactional caller, not a manual RPC claim.
+                if (!["manual", "retry"].includes(input.trigger.source))
+                    throw new Error("RPC triggers must be manual or retry.");
+                return admitJobRun(tx, home, input.scope, input.id, input.caller, input.trigger, now, input.retryOf);
+            }
+            const run = listJobRuns(tx, existing).find(candidate => candidate.id === input.runId);
+            if (run === undefined)
+                throw new Error("Exact JobRun not found.");
+            authorizeRunRead(tx, run, input.caller);
+            if (input.op === "run-get")
+                return run;
+            if (input.op === "logs") {
+                const steps = run.result?.steps ?? createFileArtifactPort(home)
+                    .readCheckpoint(executionNamespace(run), run.id)?.completedSteps ?? run.checkpoint?.completedSteps ?? [];
+                if (steps.length === 0)
+                    return [];
+                const root = realpathSync(resolve(home, run.artifactsLocator, "logs"));
+                return steps.map(step => {
+                    const path = realpathSync(resolve(root, step.logPath));
+                    if (!path.startsWith(root + sep))
+                        throw new Error("JobRun log escaped its artifact directory.");
+                    const fd = openSync(path, "r");
+                    try {
+                        const size = fstatSync(fd).size;
+                        const bytes = Buffer.alloc(Math.min(size, 65536));
+                        const count = readSync(fd, bytes, 0, bytes.length, Math.max(0, size - bytes.length));
+                        return { step: step.name, path, text: bytes.subarray(0, count).toString("utf8"), truncated: size > bytes.length };
+                    }
+                    finally {
+                        closeSync(fd);
+                    }
+                });
+            }
+            if (input.op === "run-cancel" || input.op === "run-acknowledge") {
+                if ("taskId" in run) {
+                    const control = createDurableJobControl(tx);
+                    return input.op === "run-cancel"
+                        ? control.cancelJob(run.taskId, run.id, now, input.caller)
+                        : control.acknowledgeJob(run.taskId, run.id, now, input.caller);
+                }
+                const next = input.op === "run-cancel" ? requestDurableJobCancel(run, now) : acknowledgeUnknownDurableJob(run, now);
+                tx.saveGlobalJobRun(next);
+                return next;
+            }
+            throw new Error(`Unknown Job operation: ${input.op}.`);
+        });
+    };
+}