@zq-silk/yui 2.11.0 → 2.12.0

package/dist/controller/jobArtifactControl.js

@@ -0,0 +1,111 @@
+import { isDeepStrictEqual } from "node:util";
+import { requireKnownFields } from "../domain/validation.js";
+import { runReference } from "../job/jobBusinessResult.js";
+import { createJobDefinitionControl } from "./jobDefinitionControl.js";
+import { assertCallerAuthorized } from "./jobControl.js";
+import { artifactInputBytes, presentArtifactContent } from "../artifacts/artifactCapability.js";
+import { previewArtifactContent } from "../web/webMaterials.js";
+import { boundedJobArtifactPayload, MAX_JOB_ARTIFACT_RESPONSE_BYTES } from "../artifacts/jobArtifactTransport.js";
+import { jobArtifactOwner, openJobArtifactRepository, readJobArtifactReference, validateJobArtifactReference } from "../artifacts/jobArtifact.js";
+/** Git commits precede database publication. A failed publication retains the exact
+ * commit and returns its reference for explicit registration, never business replay.
+ * Never hold a synchronous SQLite transaction across awaited Git operations. */
+export async function controlJobArtifact(store, home, value, now) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Invalid Job artifact request.");
+    requireKnownFields(value, ["op", "scope", "caller", "id", "runId", "artifact", "reference", "offset"], "Job artifact request");
+    const input = value;
+    const current = () => createJobDefinitionControl(store, home)({
+        op: "run-get", scope: input.scope, caller: input.caller, id: input.id, runId: input.runId
+    }, now);
+    const run = current(); // Both definition and historical Assignment authorization.
+    const repo = openJobArtifactRepository(home, jobArtifactOwner(run), runReference(run));
+    if (input.op === "artifact-list") {
+        const head = await repo.head();
+        const files = head === null ? [] : await repo.list(head);
+        if (files.length > 256)
+            throw new Error("Artifact repository exceeds the bounded 256-file listing.");
+        const saved = [];
+        if (head !== null)
+            for (const file of files) {
+                // One bounded file at a time: a valid 256-file repository must not spawn
+                // hundreds of Git children or materialize all 8 MiB blobs concurrently.
+                const content = await repo.read(file.relativePath, head);
+                saved.push({ kind: "artifact", owner: jobArtifactOwner(run), sourceRun: runReference(run),
+                    version: head, relativePath: file.relativePath, digest: content.digest });
+            }
+        current();
+        return { sourceRun: runReference(run), artifacts: run.artifacts ?? [],
+            repository: { head, saved, workingChanges: await repo.workingChanges() } };
+    }
+    if (input.op === "artifact-read" || input.op === "artifact-preview") {
+        const ref = validateJobArtifactReference(input.reference, run);
+        // This grants only a deliberately selected, published object, never HEAD or
+        // all material in its Task. An arbitrary caller-supplied Task ref is not a grant.
+        if (!(run.artifacts ?? []).some(item => isDeepStrictEqual(item, ref))) {
+            throw new Error("Artifact reference is not registered for this exact Run.");
+        }
+        const content = await readJobArtifactReference(home, ref);
+        current(); // A replaced Session during I/O must not receive the material.
+        return boundedJobArtifactPayload({ reference: ref, ...(input.op === "artifact-preview"
+                ? previewArtifactContent(content, input.offset) : presentArtifactContent(content)) }, "Artifact response", MAX_JOB_ARTIFACT_RESPONSE_BYTES);
+    }
+    if (!["artifact-save", "artifact-register"].includes(input.op))
+        throw new Error("Unknown Job artifact operation.");
+    let ref;
+    if (input.op === "artifact-save") {
+        const artifact = input.artifact;
+        requireKnownFields(artifact, ["relativePath", "content", "encoding", "message", "expectedHead"], "Job artifact save");
+        boundedJobArtifactPayload(artifact, "Artifact save");
+        if (typeof artifact.relativePath !== "string" || artifact.relativePath.length > 512)
+            throw new Error("Artifact path exceeds 512 characters.");
+        if ((run.artifacts?.length ?? 0) >= 256)
+            throw new Error("Run artifacts exceed the bounded reference limit.");
+        const bytes = artifactInputBytes(artifact);
+        const saved = await repo.save({ files: [{ relativePath: artifact.relativePath, bytes }],
+            message: artifact.message ?? `Save ${artifact.relativePath}`, expectedHead: artifact.expectedHead });
+        const content = await repo.read(artifact.relativePath, saved.commit);
+        ref = { kind: "artifact", owner: jobArtifactOwner(run), sourceRun: runReference(run),
+            version: saved.commit, relativePath: content.relativePath, digest: content.digest };
+    }
+    else {
+        ref = validateJobArtifactReference(input.reference, run);
+        if (ref.owner.kind === "task") {
+            // Only a Task Leader or Operator with current access may select Task material.
+            // Assignment readers cannot manufacture a cross-entity grant.
+            if (!(input.caller.scope === "global" && input.caller.role === "operator")
+                && !(input.caller.scope === "task" && input.caller.role === "leader")) {
+                throw new Error("Selecting Task artifacts requires its authorized Leader or Operator.");
+            }
+            assertCallerAuthorized(store, input.caller, ref.owner.taskId);
+        }
+        await readJobArtifactReference(home, ref);
+    }
+    try {
+        return store.transaction(tx => {
+            const fresh = current();
+            if (ref.owner.kind === "task")
+                assertCallerAuthorized(tx, input.caller, ref.owner.taskId);
+            const previous = fresh.artifacts ?? [];
+            if (previous.some(item => isDeepStrictEqual(item, ref)))
+                return { status: "registered", reference: ref };
+            const next = { ...fresh, artifacts: [...previous, ref],
+                updatedAt: new Date(Math.max(now.getTime(), Date.parse(fresh.updatedAt))).toISOString() };
+            if ("executor" in next)
+                tx.saveAgentJobRun(next);
+            else if ("taskId" in next)
+                tx.saveDurableJob(next.taskId, next);
+            else
+                tx.saveGlobalJobRun(next);
+            return { status: "registered", reference: ref };
+        });
+    }
+    catch (cause) {
+        // An explicit partial receipt survives the RPC's bounded exception text.
+        // It is NOT a published result. Never replay the business action or silently
+        // retry the database write to conceal this boundary.
+        return { status: "saved-unregistered", reference: ref,
+            error: (cause instanceof Error ? cause.message : String(cause)).slice(0, 4096),
+            recovery: "Inspect artifact-list and register this exact reference; do not rerun business work." };
+    }
+}

package/dist/controller/jobControl.js

@@ -86,6 +86,8 @@ export function createDurableJobControl(store) {
                 validateStartParams(tx, params);
                 const previous = params.retryOf === undefined ? null : tx.getDurableJob(params.taskId, params.retryOf);
                 if (previous !== null) {
+                    if (previous.delegation)
+                        throw jobDomainError("Use Job run retry for a Task delegation, not a process specification.");
                     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.");
@@ -190,6 +192,8 @@ export function createJobCallAuthority(store) {
  * Job even when its management binding is revoked. Only a new spawn checks it.
  */
 export function authorizeJobStart(store, job) {
+    if (job.delegation)
+        throw jobDomainError("Task delegation cannot start a process.");
     const taskPrefix = `task:${job.taskId}/role:`;
     const actor = job.operation.actorId;
     const scope = actor.startsWith(taskPrefix) ? "task" : actor.startsWith("global:") ? "global" : undefined;

package/dist/controller/jobDefinitionControl.js

@@ -8,9 +8,26 @@ 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) {
+import { jobRunSnapshot, runReference } from "../job/jobBusinessResult.js";
+import { controlJobArtifact } from "./jobArtifactControl.js";
+import { ArtifactHeadConflictError, ArtifactManagedConfigViolationError, ArtifactRemoteViolationError } from "../artifacts/taskArtifactRepository.js";
+import { ArtifactCommitLockedError } from "../artifacts/artifactCommitLock.js";
+import { ManagedGitError } from "../artifacts/managedGit.js";
+import { authorizeServiceJob, requireScheduleService, serviceRunBinding } from "../job/scheduleService.js";
+import { authorizeAgentDefinition, controlAgentJob, summarizeAgentRuns } from "./agentJobControl.js";
+import { admitTaskJob, authorizeTaskJob, reconcileTaskDelegation, taskDelegationView } from "./jobTaskDelegationControl.js";
+import { requireProjectSyncTarget } from "../job/projectSync.js";
+export function authorizeScope(store, scope, caller, allowPublic = false) {
     parseDurableJobCaller(caller);
     jobScopeKey(scope);
+    // Public local ingress is not a fabricated Operator. It grants only immediate
+    // controlled global management/actions. Schedule grants are explicit and
+    // Task-shell authority is unchanged.
+    if (allowPublic && scope.kind === "global" && caller.scope === "user") {
+        if (Object.keys(caller).some(key => key !== "scope"))
+            throw new Error("Public user Job caller must not claim a managed identity.");
+        return;
+    }
     // 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.
@@ -26,7 +43,13 @@ function taskParams(job, caller, requestId) {
     return { ...job.configuration, taskId: job.scope.taskId, caller, requestId };
 }
 export function authorizeDefinition(store, job, caller, write) {
-    authorizeScope(store, job.scope, caller);
+    if (job.configuration.kind === "agent")
+        return authorizeAgentDefinition(store, job, caller, write);
+    authorizeScope(store, job.scope, caller, true);
+    if (job.configuration.kind === "task") {
+        authorizeTaskJob(store, job, caller, write);
+        return;
+    }
     if (job.scope.kind === "task") {
         const params = taskParams(job, caller, "definition-validation");
         // A definition must not reveal another Assignment's commands/environment.
@@ -41,11 +64,13 @@ export function authorizeDefinition(store, job, caller, write) {
             throw new Error("Global Jobs require builtin actions.");
         prepareBuiltinJob(job.configuration, "/");
         if (job.configuration.action === "project.refresh") {
+            if (job.builtin)
+                requireProjectSyncTarget(store, job);
             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"
+            const duplicate = !job.instantiation && store.listJobDefinitions({ kind: "global" }).find(other => !other.instantiation && !other.builtin && 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}.`);
@@ -57,7 +82,29 @@ export function listJobRuns(store, job) {
         .filter(run => run.definitionId === job.id);
 }
 /** Read-only presentation; attempts/results remain owned by exact JobRuns. */
-function presentDefinition(store, job) {
+function presentDefinition(store, definition, caller) {
+    if (definition.configuration.kind === "agent")
+        return {
+            ...definition, results: summarizeAgentRuns(store.listAgentJobRuns(definition.scope, definition.id))
+        };
+    const history = listJobRuns(store, definition).filter(run => {
+        try {
+            authorizeRunRead(store, run, caller);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }).sort((a, b) => b.createdAt.localeCompare(a.createdAt) || b.id.localeCompare(a.id));
+    const result = (run) => run ? {
+        runId: run.id, sourceRun: runReference(run), status: run.status,
+        outcome: run.businessResult?.outcome ?? null,
+        summary: run.businessResult?.summary.slice(0, 512) ?? null,
+        artifactCount: run.artifacts?.length ?? 0, delegation: taskDelegationView(store, run)
+    } : null;
+    const job = { ...definition, results: {
+            latest: result(history[0]), latestSuccessful: result(history.find(run => run.businessResult?.outcome === "succeeded"))
+        } };
     if (job.configuration.kind !== "builtin" || job.configuration.action !== "project.refresh")
         return job;
     const projectId = job.configuration.projectId;
@@ -69,14 +116,21 @@ function presentDefinition(store, job) {
         .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
+        status: run.status, attemptedAt: run.createdAt, finishedAt: run.terminalAt ?? null,
+        summary: run.businessResult?.summary.slice(0, 512) ?? null
     };
     return { ...job, refresh: {
             projectId, lastAttempt: summarize(runs[0]),
             lastSuccessfulRefresh: summarize(runs.find(run => run.status === "succeeded"))
         } };
 }
-function authorizeRunRead(store, run, caller) {
+export function authorizeRunRead(store, run, caller) {
+    if (run.delegation) {
+        authorizeScope(store, runReference(run).scope, caller, true);
+        if (caller.scope === "task" && caller.role !== "leader")
+            throw new Error("Task delegation is not an Assignment grant.");
+        return;
+    }
     // A revised definition's Assignment does not grant access to earlier Runs.
     if ("taskId" in run)
         createDurableJobControl(store).getJob(run.taskId, run.id, caller);
@@ -86,12 +140,21 @@ function authorizeRunRead(store, run, caller) {
  * 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) {
+export function admitJobRun(store, home, scope, definitionId, caller, trigger, now, retryOf, service) {
     return store.transaction(tx => {
         const job = tx.getJobDefinition(scope, definitionId);
         if (job === null)
             throw new Error("Job definition not found.");
+        if (job.configuration.kind === "agent")
+            throw new Error("Agent Jobs use their explicit Role message admission; Schedule service does not grant Agent execution.");
         authorizeDefinition(tx, job, caller, false);
+        const serviceSchedule = service === undefined ? undefined : authorizeServiceJob(tx, job, service, trigger.key);
+        if (service && (scope.kind !== "global" || trigger.source !== "schedule" || retryOf !== undefined)) {
+            throw new Error("Invalid Schedule service admission.");
+        }
+        if (!service && caller.scope === "user" && !["manual", "retry"].includes(trigger.source)) {
+            throw new Error("Public Job admission only authorizes an immediate manual execution or explicit retry.");
+        }
         if (!trigger.key.trim() || !["manual", "retry", "schedule", "integration"].includes(trigger.source)) {
             throw new Error("Invalid JobRun trigger.");
         }
@@ -116,6 +179,11 @@ export function admitJobRun(store, home, scope, definitionId, caller, trigger, n
             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 (job.configuration.kind === "task") {
+            if (service)
+                throw new Error("Schedule service does not authorize Task delegation.");
+            return { run: admitTaskJob(tx, { ...job, configuration: job.configuration }, caller, trigger, requestId, now, retryOf), created: true };
+        }
         if (scope.kind === "task") {
             const result = createDurableJobControl(tx).startJob({
                 ...taskParams(job, caller, requestId), definitionId, trigger, retryOf
@@ -127,30 +195,85 @@ export function admitJobRun(store, home, scope, definitionId, caller, trigger, n
         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({
+        const actorId = service ? "service:schedule" : caller.scope === "user" ? "user" : `global:${caller.role}`;
+        let run = {
             schemaVersion: 1, scope: "global", id, definitionId: job.id, definitionRevision: job.revision,
             trigger: structuredClone(trigger), action: job.configuration.action,
+            ...(service === undefined ? {} : { serviceAuthorization: structuredClone(service) }),
             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, ""),
+                requestId, actorId, authorityRef: service || caller.scope === "user" ? "pending" : 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()
-        });
+        };
+        if (serviceSchedule)
+            run = { ...run, operation: { ...run.operation, authorityRef: serviceRunBinding(tx, run, serviceSchedule) } };
+        else if (caller.scope === "user")
+            run = { ...run, operation: { ...run.operation, authorityRef: publicJobBinding(tx, run) } };
+        validateDurableJob(run);
         tx.saveGlobalJobRun(run);
         return { run, created: true };
     });
 }
+/** Job owns instantiation; Schedule supplies only the exact version and occurrence. */
+export function instantiateJobRun(store, home, scope, definitionId, revision, caller, trigger, now, service) {
+    return store.transaction(tx => {
+        const source = tx.getJobDefinition(scope, definitionId);
+        if (!source || source.revision !== revision)
+            throw new Error("Source Job revision changed; explicitly select an available version.");
+        authorizeDefinition(tx, source, caller, true);
+        const id = `instance-${createHash("sha256").update(JSON.stringify([source.scope, source.id, trigger])).digest("hex")}`;
+        const instantiation = { sourceId: source.id, sourceRevision: revision, key: trigger.key };
+        let job = tx.getJobDefinition(source.scope, id);
+        if (job) {
+            if (JSON.stringify(job.instantiation) !== JSON.stringify(instantiation)
+                || JSON.stringify(job.configuration) !== JSON.stringify(source.configuration)) {
+                throw new Error("Job instance identity conflicts with its original source.");
+            }
+        }
+        else {
+            job = validateJobDefinition({ ...createJobDefinition({ id, scope: source.scope,
+                    title: source.title, configuration: source.configuration }, now), instantiation });
+            tx.saveJobDefinition(job);
+        }
+        return admitJobRun(tx, home, source.scope, job.id, caller, trigger, now, undefined, service);
+    });
+}
+function publicJobBinding(store, run) {
+    return createHash("sha256").update(JSON.stringify([
+        "public-immediate-job/v1", store.getHomeIdentity().homeId, run.id, run.definitionId, run.definitionRevision,
+        run.action, run.projectId, run.actionInput, run.trigger, run.operation.requestId
+    ])).digest("hex");
+}
 export function authorizeGlobalJobStart(store, run) {
-    if (run.operation.actorId !== "global:operator"
-        || jobAuthorityBinding(store, "global", "operator", "") !== run.operation.authorityRef) {
+    if (run.delegation)
+        throw new Error("Task delegation cannot start a builtin process.");
+    let serviceAdmission = false;
+    if (run.operation.actorId === "service:schedule" && run.serviceAuthorization && run.trigger.source === "schedule") {
+        try {
+            const schedule = requireScheduleService(store, run.serviceAuthorization);
+            const job = store.getJobDefinition({ kind: "global" }, run.definitionId);
+            if (!job || job.revision !== run.definitionRevision)
+                throw new Error("Schedule Run Job revision changed.");
+            authorizeServiceJob(store, job, run.serviceAuthorization, run.trigger.key);
+            serviceAdmission = serviceRunBinding(store, run, schedule) === run.operation.authorityRef;
+        }
+        catch (error) {
+            throw Object.assign(new Error(error instanceof Error ? error.message : String(error), { cause: error }), { name: "CoreJobError" });
+        }
+    }
+    const publicAdmission = run.operation.actorId === "user"
+        && ["manual", "retry"].includes(run.trigger.source)
+        && publicJobBinding(store, run) === run.operation.authorityRef;
+    if (!serviceAdmission && !publicAdmission && (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.
@@ -162,6 +285,9 @@ export function authorizeGlobalJobStart(store, run) {
             ...(run.projectId === undefined ? {} : { projectId: run.projectId })
         }, run.workspace, { home, runId: run.id });
         if (run.action === "project.refresh") {
+            const definition = store.getJobDefinition({ kind: "global" }, run.definitionId);
+            if (definition?.builtin)
+                requireProjectSyncTarget(store, definition);
             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
@@ -185,11 +311,28 @@ 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 op = value.op;
+        if (typeof op === "string" && op.startsWith("artifact-")) {
+            return controlJobArtifact(store, home, value, now).catch(error => {
+                // Preserve bounded domain diagnostics through RPC; authentication errors
+                // retain their existing CoreApplicationError identity and code.
+                if (error instanceof ArtifactHeadConflictError || error instanceof ArtifactManagedConfigViolationError
+                    || error instanceof ArtifactRemoteViolationError || error instanceof ArtifactCommitLockedError
+                    || error instanceof ManagedGitError)
+                    error.name = "CoreJobError";
+                throw error;
+            });
+        }
+        requireKnownFields(value, ["op", "scope", "caller", "id", "title", "configuration", "expectedRevision", "trigger", "retryOf", "runId", "result", "expectedSessionId", "expectedAttemptId"], "Job request");
         const input = value;
-        authorizeScope(store, input.scope, input.caller);
+        // A Job execution reader is authorized against its exact definition below,
+        // not promoted to Operator or to a Task manager.
+        if (!(input.caller.scope === "global" && input.caller.role !== "operator")
+            && !(input.caller.scope === "task" && input.scope.kind === "global"))
+            authorizeScope(store, input.scope, input.caller, true);
         return store.transaction(tx => {
             if (input.op === "list") {
+                authorizeScope(tx, input.scope, input.caller, true);
                 return tx.listJobDefinitions(input.scope).filter(job => {
                     try {
                         authorizeDefinition(tx, job, input.caller, false);
@@ -198,12 +341,15 @@ export function createJobDefinitionControl(store, home) {
                     catch {
                         return false;
                     }
-                }).map(job => presentDefinition(tx, job));
+                }).map(job => presentDefinition(tx, job, input.caller));
             }
             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") {
+                if (existing?.builtin || (!existing && input.scope.kind === "global" && input.id.startsWith("project-sync-"))) {
+                    throw new Error("Builtin Project sync definitions are installer-owned; edit their Schedule.");
+                }
                 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.
@@ -238,9 +384,11 @@ export function createJobDefinitionControl(store, home) {
             if (existing === null)
                 throw new Error("Job definition not found.");
             validateJobDefinition(existing);
+            if (existing.configuration.kind === "agent")
+                return controlAgentJob(tx, home, existing, input, now);
             authorizeDefinition(tx, existing, input.caller, false);
             if (input.op === "show")
-                return presentDefinition(tx, existing);
+                return presentDefinition(tx, existing, input.caller);
             if (input.op === "runs")
                 return listJobRuns(tx, existing).filter(run => {
                     try {
@@ -263,8 +411,24 @@ export function createJobDefinitionControl(store, home) {
             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 === "run-delegation")
+                return taskDelegationView(tx, run);
+            if (input.op === "run-get" || input.op === "run-confirm")
+                return input.op === "run-confirm" && run.delegation
+                    ? reconcileTaskDelegation(tx, run, now) : run;
+            if (input.op === "run-result")
+                return {
+                    snapshot: jobRunSnapshot(run),
+                    acceptedAt: run.createdAt, startedAt: run.startedAt ?? null,
+                    confirmedAt: run.businessResult === undefined ? null : run.terminalAt ?? null,
+                    status: run.status, result: run.businessResult ?? null, artifacts: run.artifacts ?? []
+                };
+            if (input.op === "run-evidence")
+                return {
+                    sourceRun: jobRunSnapshot(run), operation: run.operation,
+                    process: run.process ?? null, checkpoint: run.checkpoint ?? null,
+                    processResult: run.result ?? null, artifactsLocator: run.artifactsLocator
+                };
             if (input.op === "logs") {
                 const steps = run.result?.steps ?? createFileArtifactPort(home)
                     .readCheckpoint(executionNamespace(run), run.id)?.completedSteps ?? run.checkpoint?.completedSteps ?? [];
@@ -288,6 +452,14 @@ export function createJobDefinitionControl(store, home) {
                 });
             }
             if (input.op === "run-cancel" || input.op === "run-acknowledge") {
+                if (run.delegation) {
+                    const next = input.op === "run-cancel" ? requestDurableJobCancel(run, now) : acknowledgeUnknownDurableJob(run, now);
+                    if ("taskId" in next)
+                        tx.saveDurableJob(next.taskId, next);
+                    else
+                        tx.saveGlobalJobRun(next);
+                    return next;
+                }
                 if ("taskId" in run) {
                     const control = createDurableJobControl(tx);
                     return input.op === "run-cancel"

package/dist/controller/jobSupervisor.js

@@ -20,6 +20,7 @@ import { recordOperationEvidence } from "../kernel/operationFacts.js";
 import { wakeReason } from "../scheduler/wakeReason.js";
 import { writeTextFileAtomically } from "../storage/durableFile.js";
 import { readProcessStartIdentity } from "../core/fileLockOwner.js";
+import { processBusinessResult, resultDigest, runReference, validateBusinessResult } from "../job/jobBusinessResult.js";
 const DEFAULT_STEP_TIMEOUT_MS = 30 * 60_000;
 const HEARTBEAT_STALE_MS = 2 * 60_000;
 const SIGKILL_GRACE_MS = 30_000;
@@ -31,6 +32,7 @@ export class DurableJobSupervisor {
     #wake;
     #onError;
     #authorizeStart;
+    #reconcileDelegation;
     // f5: Composite key (taskId/jobId) because job IDs are Task-local — every
     // Task has a job-1, so a Task-local key would cross-kill healthy runners.
     #sigkillAt = new Map();
@@ -42,6 +44,7 @@ export class DurableJobSupervisor {
         this.#wake = options.wake ?? (() => undefined);
         this.#onError = options.onError ?? (() => undefined);
         this.#authorizeStart = options.authorizeStart;
+        this.#reconcileDelegation = options.reconcileDelegation;
     }
     reconcile(now) {
         const jobs = this.#store.listActiveDurableJobs();
@@ -67,7 +70,38 @@ export class DurableJobSupervisor {
             }
         }
     }
+    /** Explicit collection only. Never admits, spawns, cancels or retries work. */
+    confirmResult(namespace, runId, now) {
+        const run = this.#store.listActiveDurableJobs()
+            .find(run => executionNamespace(run) === namespace && run.id === runId);
+        if (!run)
+            return;
+        if (run.delegation) {
+            this.#reconcileDelegation?.(run, now);
+            return;
+        }
+        if (run.status === "queued") {
+            const spawned = this.#spawnedProcessFromEvidence(run, this.#artifacts.readStartMarker(namespace, runId));
+            if (spawned)
+                this.#adoptAndContinue(run, spawned, now);
+        }
+        else {
+            const exit = this.#artifacts.readExitJson(namespace, runId);
+            if (exit)
+                this.#harvestExit(run, exit, now);
+            else if (run.process) {
+                const identity = this.#process.processStartIdentity(run.process.pid);
+                if (identity === undefined || identity !== run.process.startIdentity
+                    || !this.#process.isProcessAlive(run.process.pid))
+                    this.#handleDeadProcess(run, now);
+            }
+        }
+    }
     #reconcileJob(job, now) {
+        if (job.delegation) {
+            this.#reconcileDelegation?.(job, now);
+            return;
+        }
         if (job.status === "queued") {
             this.#reconcileQueued(job, now);
             return;
@@ -155,6 +189,8 @@ export class DurableJobSupervisor {
         }
     }
     #startJob(job, now) {
+        if (job.delegation)
+            throw new Error("Task delegation cannot start a process.");
         try {
             this.#authorizeStart(job);
         }
@@ -298,6 +334,7 @@ export class DurableJobSupervisor {
             evidenceSource: "exit-artifact",
             steps: exit.steps
         };
+        const business = this.#businessResult(job, result);
         // rr4/finding-7: The terminal transition and the Leader wakeup must be
         // atomic. Compose complete + wakeupNotified and pass the wakeup param so
         // the adapter enqueues the Leader mailbox entry in the same transaction.
@@ -306,11 +343,11 @@ export class DurableJobSupervisor {
         const terminal = this.#store.transitionDurableJob(executionNamespace(job), job.id, (current) => {
             let completed;
             try {
-                completed = completeDurableJob(current, result, now);
+                completed = completeDurableJob(current, result, now, business);
             }
             catch {
                 completed = completeDurableJob(current, {
-                    outcome: "failed", exitCode: null, signal: null,
+                    outcome: "unknown-needs-attention", exitCode: null, signal: null,
                     unknownReason: "runner output is invalid; original receipt is retained",
                     steps: []
                 }, now);
@@ -329,7 +366,7 @@ export class DurableJobSupervisor {
             // The runner died without exit.json, but its step checkpoint covered
             // every planned step: the outcome is still provable from durable
             // evidence. No false pass — the checkpoint is the runner's own record.
-            const terminal = this.#store.transitionDurableJob(executionNamespace(job), job.id, (current) => markDurableJobWakeupNotified(completeDurableJob(current, { ...proven, evidenceSource: "checkpoint" }, now), now), now, { reason: wakeReason("job-finished"), refs: wakeupRefs(job) });
+            const terminal = this.#store.transitionDurableJob(executionNamespace(job), job.id, (current) => markDurableJobWakeupNotified(completeDurableJob(current, { ...proven, evidenceSource: "checkpoint" }, now, this.#businessResult(current, { ...proven, evidenceSource: "checkpoint" })), now), now, { reason: wakeReason("job-finished"), refs: wakeupRefs(job) });
             this.#deliverTerminalEvent(terminal);
         }
         else {
@@ -339,6 +376,34 @@ export class DurableJobSupervisor {
         }
         this.#sigkillAt.delete(this.#sigkillKey(job));
     }
+    #businessResult(job, result) {
+        const fallback = processBusinessResult(job, result);
+        if ("taskId" in job)
+            return fallback;
+        // The runner records this only when its cancel fence is seen before the
+        // first step. No domain action ran, so no business receipt is expected.
+        if (result.outcome === "cancelled" && result.steps.length === 0)
+            return fallback;
+        if (job.action === "system.noop")
+            return { ...fallback, data: { action: "system.noop" } };
+        const raw = this.#artifacts.readBusinessResult?.(executionNamespace(job), job.id);
+        if (raw !== null && raw !== undefined) {
+            try {
+                const business = validateBusinessResult(JSON.parse(raw), runReference(job));
+                const sourceRun = runReference(job);
+                return { ...business, evidence: [...business.evidence, {
+                            kind: "execution-evidence", owner: sourceRun, sourceRun,
+                            version: resultDigest(raw), locator: `${job.artifactsLocator}/business-result.json`
+                        }, ...fallback.evidence] };
+            }
+            catch {
+                return { ...fallback, outcome: "unknown-needs-attention",
+                    summary: "Invalid business result receipt; inspect retained execution evidence. Do not replay the action." };
+            }
+        }
+        return { ...fallback, outcome: "unknown-needs-attention",
+            summary: "Business result receipt is missing; process completion does not prove the business outcome. Do not replay the action." };
+    }
     /**
      * f7/rr5: Deliver a terminal notice to the runtime inbox channel when a
      * Job reaches a terminal state. The notice is best-effort: the terminal
@@ -375,6 +440,8 @@ function wakeupRefs(job) {
  * checkpoint covers every planned step exactly, by name.
  */
 function proveOutcomeFromCheckpoint(job, checkpoint) {
+    if (job.delegation)
+        return null;
     const byName = new Map(checkpoint.completedSteps.map((step) => [step.name, step]));
     if (byName.size !== checkpoint.completedSteps.length)
         return null;
@@ -501,6 +568,19 @@ export function createFileArtifactPort(home) {
         },
         readReadyFile(taskId, jobId) {
             return readJsonFile(join(home, "artifacts", "jobs", taskId, jobId, "ready.json"));
+        },
+        readBusinessResult(taskId, jobId) {
+            const path = join(home, "artifacts", "jobs", taskId, jobId, "business-result.json");
+            try {
+                if (statSync(path).size > 256 * 1024)
+                    return "oversized business result";
+                return readFileSync(path, "utf8");
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    return null;
+                throw error; // A transient collection failure is not absence or permission to rerun.
+            }
         }
     };
 }