@cosmicdrift/kumiko-framework 0.322.0 → 0.324.0

package/src/engine/entity-handlers.ts

@@ -13,6 +13,7 @@ import { acknowledgeConventionCrossTenant, type TenantDb } from "../db/tenant-db
 import { isSystemIdentity } from "../pipeline/system-identity-switch";
 import { assertUnreachable } from "../utils";
 import { PAGED_QUERY_HANDLER_BRAND } from "./define-handler";
+import { instructionFieldNames } from "./instruction-fields";
 import { buildInsertSchema, buildUpdateSchema } from "./schema-builder";
 import type {
   AccessRule,
@@ -214,19 +215,45 @@ function isInTotalsMatchPair(entity: EntityDefinition, fieldName: string): boole
   );
 }
 
-// delete on an entity without softDelete hard-purges the row — the agent
-// risk gate only protects it if this handler resolves to "high".
+// A create/update handler can write a field flagged readAsInstruction: true if:
+// update — the field isn't in excludeFields; create — the field isn't excluded,
+// or is excluded but has a default (applyDefaults writes it regardless, so the
+// define-time floor must match what the executor gate will see at runtime).
+function writableInstructionFields(
+  verb: "create" | "update",
+  entity: EntityDefinition,
+  excludedFields: readonly string[],
+): readonly string[] {
+  return instructionFieldNames(entity).filter((fieldName) => {
+    if (!excludedFields.includes(fieldName)) return true;
+    if (verb !== "create") return false;
+    const field = entity.fields[fieldName];
+    return field !== undefined && "default" in field && field.default !== undefined;
+  });
+}
+
+// delete on an entity without softDelete hard-purges the row, and create/update
+// handlers writing a readAsInstruction field are irreversible in effect (a
+// revert doesn't undo a run that already read the value) — the agent risk gate
+// only protects either case if this handler resolves to "high".
 function resolveEntityWriteAgentHints(
   name: string,
   verb: (typeof WRITE_VERBS)[number],
   entity: EntityDefinition,
   agent: AgentHandlerHints | undefined,
+  excludedFields: readonly string[],
 ): AgentHandlerHints | undefined {
-  if (verb !== "delete" || entity.softDelete) return agent;
+  const isIrreversibleDelete = verb === "delete" && !entity.softDelete;
+  const instructionFields =
+    verb === "create" || verb === "update"
+      ? writableInstructionFields(verb, entity, excludedFields)
+      : [];
+  if (!isIrreversibleDelete && instructionFields.length === 0) return agent;
   if (agent?.risk !== undefined && agent.risk !== "high") {
-    throw new Error(
-      `"${name}": delete on an entity without softDelete is irreversible — agent.risk must be "high" (got "${agent.risk}").`,
-    );
+    const reason = isIrreversibleDelete
+      ? "delete on an entity without softDelete is irreversible"
+      : `it writes field(s) ${instructionFields.join(", ")} flagged readAsInstruction: true`;
+    throw new Error(`"${name}": ${reason} — agent.risk must be "high" (got "${agent.risk}").`);
   }
   return { ...agent, risk: "high" };
 }
@@ -271,9 +298,15 @@ export function defineEntityWriteHandler(
       `"${name}": restore is only valid for entities declared with softDelete: true.`,
     );
   }
-  const agentHints = resolveEntityWriteAgentHints(name, verb, entity, options.agent);
   const excludedFields = options.excludeFields ?? [];
   assertExcludableFields(name, verb, entity, excludedFields);
+  const agentHints = resolveEntityWriteAgentHints(
+    name,
+    verb,
+    entity,
+    options.agent,
+    excludedFields,
+  );
 
   const table = buildEntityTable(entityName, entity);
   const executor = createEventStoreExecutor(table, entity, { entityName });

package/src/engine/factories.ts

@@ -88,6 +88,77 @@ function expandPersonalAnnotations<T extends PersonalOverridesInput>(
   } as Omit<T, "personal" | "find" | "reason"> & ResolvedPiiFlags;
 }
 
+type TextFieldStanceFactory = "createTextField" | "createLongTextField";
+
+// `find` is mandatory once a subject is named (types require it — see
+// PersonalAnnotations / PersonalAnnotationsLongText), but the valid values
+// differ per factory: longText has no lookup/search machinery.
+const TEXT_FIELD_STANCE_FIND_VALUES: Record<TextFieldStanceFactory, readonly Findability[]> = {
+  createTextField: ["exact", "fuzzy", "none", "secret"],
+  createLongTextField: ["none", "secret"],
+};
+
+function textFieldStanceHint(factoryName: TextFieldStanceFactory): string {
+  const find = TEXT_FIELD_STANCE_FIND_VALUES[factoryName].map((f) => `"${f}"`).join(" | ");
+  return (
+    `{ personal: "self", find: ${find} }, ` +
+    `{ personal: "tenant", find: ${find} }, ` +
+    `{ personal: { of: "<ownerField>" }, find: ${find} }, ` +
+    `{ personal: "ref" }, or ` +
+    `{ personal: false, reason: "<why this is not personal data>" }`
+  );
+}
+
+function missingTextFieldStanceError(factoryName: TextFieldStanceFactory): Error {
+  return new Error(
+    `${factoryName}(...) must declare an explicit personal-data stance — a text field must state whose data it holds and (unless it isn't personal data) how findable it needs to stay (kumiko-framework#2921). Pass one of: ${textFieldStanceHint(factoryName)}. Run \`kumiko-guards guards --guard="Text-Field Personal-Stance Guard"\` to find remaining call sites.`,
+  );
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+// Fail-closed stance gate (kumiko-framework#2921) for the two text-shaped
+// factories — runs before expandPersonalAnnotations so an untyped JS caller
+// (no compiler to stop it) can't slip an unannotated text field past the
+// type layer either. `overrides` is `unknown` here on purpose: the typed
+// signature above already rejects a missing/malformed shape at compile
+// time, this re-checks the same shape at the runtime boundary.
+function assertTextFieldStance(factoryName: TextFieldStanceFactory, overrides: unknown): void {
+  if (overrides === null || typeof overrides !== "object") {
+    throw missingTextFieldStanceError(factoryName);
+  }
+  // @cast-boundary runtime-guard — re-validated field by field below before
+  // any value is trusted.
+  const { personal, find, reason } = overrides as PersonalOverridesInput;
+  if (personal === undefined || personal === null) {
+    throw missingTextFieldStanceError(factoryName);
+  }
+  if (personal === "ref") {
+    // skip: a user reference carries no content of its own, so no `find` applies
+    return;
+  }
+  if (personal === false) {
+    if (!isNonEmptyString(reason)) {
+      throw missingTextFieldStanceError(factoryName);
+    }
+    // skip: plaintext by declaration, `find` only applies to a named subject
+    return;
+  }
+  const hasValidSubject =
+    personal === "self" ||
+    personal === "tenant" ||
+    (typeof personal === "object" && isNonEmptyString(personal.of));
+  if (!hasValidSubject) {
+    throw missingTextFieldStanceError(factoryName);
+  }
+  const validFinds = TEXT_FIELD_STANCE_FIND_VALUES[factoryName];
+  if (typeof find !== "string" || !(validFinds as readonly string[]).includes(find)) {
+    throw missingTextFieldStanceError(factoryName);
+  }
+}
+
 // Generic über `R extends true | false` (statt `boolean`) damit
 // `createTextField({ required: true })` literal `required: true` im
 // Return-Type behält. `boolean` würde widenen — EntityTable<E>'s
@@ -96,9 +167,10 @@ function expandPersonalAnnotations<T extends PersonalOverridesInput>(
 // degradieren. Default `R = false` matcht den runtime-default. Pattern
 // in jeder required-bearing factory unten.
 export function createTextField<R extends true | false = false>(
-  overrides?: Partial<Omit<TextFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> &
+  overrides: Partial<Omit<TextFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> &
     PersonalAnnotations & { required?: R },
 ): TextFieldDef & { required: R } {
+  assertTextFieldStance("createTextField", overrides);
   return {
     type: "text",
     maxLength: 200,
@@ -131,9 +203,10 @@ export function createDerivedField(spec: DerivedFieldDef): DerivedFieldDef {
 }
 
 export function createLongTextField<R extends true | false = false>(
-  overrides?: Partial<Omit<LongTextFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> &
+  overrides: Partial<Omit<LongTextFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> &
     PersonalAnnotationsLongText & { required?: R },
 ): LongTextFieldDef & { required: R } {
+  assertTextFieldStance("createLongTextField", overrides);
   return {
     type: "longText",
     required: false,

package/src/engine/instruction-fields.ts

@@ -0,0 +1,11 @@
+import type { EntityDefinition } from "./types";
+
+// Shared between the executor gate (payload-presence check on create/update)
+// and the define-time floor (resolveEntityWriteAgentHints) so both read the
+// exact same field set — a divergence here would let one enforce a flag the
+// other doesn't know about.
+export function instructionFieldNames(entity: EntityDefinition): readonly string[] {
+  return Object.entries(entity.fields)
+    .filter(([, field]) => "readAsInstruction" in field && field.readAsInstruction === true)
+    .map(([name]) => name);
+}

package/src/errors/i18n/de.yaml

@@ -173,6 +173,20 @@ irreversible_operation_requires_high_risk:
 
     `agent: { risk: "high" }` am genannten Handler deklarieren.
 
+instruction_field_write_requires_high_risk:
+  endUser: |
+    Diese Aktion ist nicht erlaubt.
+    Wende dich an einen Administrator wenn du glaubst, dass das ein Fehler ist.
+  developer: |
+    `AccessDeniedError`: der direkt aufgerufene Einstiegs-Handler schreibt ein
+    Feld mit `readAsInstruction: true` (`details.fields`), aber sein
+    aufgelöstes Agent-Risiko (`details.resolvedRisk`) liegt unter `"high"`.
+    `details.handler` nennt den Einstiegs-Handler — eine Delegation über
+    `ctx.write`/`writeAs` aus einem Handler mit niedrigerem Risiko erbt das
+    deklarierte Risiko des inneren Handlers nicht.
+
+    `agent: { risk: "high" }` am genannten Handler deklarieren.
+
 agent.tool_not_allowed:
   endUser: |
     Dieses Tool ist im aktuellen Modus nicht verfügbar.

package/src/errors/i18n/en.yaml

@@ -166,6 +166,20 @@ irreversible_operation_requires_high_risk:
 
     Declare `agent: { risk: "high" }` on the named handler.
 
+instruction_field_write_requires_high_risk:
+  endUser: |
+    This action isn't allowed.
+    Please contact an administrator if you believe this is a mistake.
+  developer: |
+    `AccessDeniedError`: the directly-dispatched entry handler writes a field
+    flagged `readAsInstruction: true` (`details.fields`) but its resolved
+    agent risk (`details.resolvedRisk`) is below `"high"`. `details.handler`
+    names the entry handler — delegating the call via `ctx.write`/`writeAs`
+    from a lower-risk handler does not inherit an inner handler's declared
+    risk.
+
+    Declare `agent: { risk: "high" }` on the named handler.
+
 agent.tool_not_allowed:
   endUser: |
     This tool is not available in the current mode.

package/src/errors/reasons.ts

@@ -68,6 +68,12 @@ export const FrameworkReasons = {
   // delete/forget but its agent.risk resolves below "high" — delegation via
   // ctx.write/writeAs from a lower-risk handler does not inherit the gate.
   irreversibleOperationRequiresHighRisk: "irreversible_operation_requires_high_risk",
+
+  // AccessDeniedError: the directly-dispatched entry handler writes a field
+  // flagged readAsInstruction: true but its agent.risk resolves below "high" —
+  // delegation via ctx.write/writeAs from a lower-risk handler does not
+  // inherit the gate.
+  instructionFieldWriteRequiresHighRisk: "instruction_field_write_requires_high_risk",
 } as const;
 
 export type FrameworkReason = (typeof FrameworkReasons)[keyof typeof FrameworkReasons];

package/src/jobs/__tests__/job-backoff.integration.test.ts

@@ -7,13 +7,12 @@
 //
 // Only lower bounds are asserted (never upper) — BullMQ schedules the next
 // attempt at failureTime + delay using the same wall clock this test reads,
-// so a >= assertion is flake-free without inflating waitFor's budget.
+// so a >= assertion is flake-free without inflating the wait budget.
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import * as z from "zod";
 import { defineFeature } from "../../engine";
 import { setupTestStack, type TestStack, TestUsers } from "../../stack";
-import { waitFor } from "../../testing";
 
 const exponentialDefaultStarts: number[] = [];
 const exponentialCustomStarts: number[] = [];
@@ -113,9 +112,8 @@ describe("job backoff waits between retries (fw#3167)", () => {
       TestUsers.admin,
     );
 
-    await waitFor(() => {
-      expect(exponentialDefaultStarts).toHaveLength(2);
-    });
+    await stack.drainJobs();
+    expect(exponentialDefaultStarts).toHaveLength(2);
 
     const [gap = 0] = gapsBetween(exponentialDefaultStarts);
     expect(gap).toBeGreaterThanOrEqual(1000);
@@ -128,9 +126,8 @@ describe("job backoff waits between retries (fw#3167)", () => {
       TestUsers.admin,
     );
 
-    await waitFor(() => {
-      expect(exponentialCustomStarts).toHaveLength(4);
-    });
+    await stack.drainJobs();
+    expect(exponentialCustomStarts).toHaveLength(4);
 
     const [gap1 = 0, gap2 = 0, gap3 = 0] = gapsBetween(exponentialCustomStarts);
     expect(gap1).toBeGreaterThanOrEqual(50);
@@ -141,9 +138,8 @@ describe("job backoff waits between retries (fw#3167)", () => {
   test('backoff: { type: "fixed", delayMs } waits the configured constant delay', async () => {
     await stack.http.writeOk("backofffixture:write:trigger-fixed-custom", {}, TestUsers.admin);
 
-    await waitFor(() => {
-      expect(fixedCustomStarts).toHaveLength(2);
-    });
+    await stack.drainJobs();
+    expect(fixedCustomStarts).toHaveLength(2);
 
     const [gap = 0] = gapsBetween(fixedCustomStarts);
     expect(gap).toBeGreaterThanOrEqual(300);

package/src/jobs/job-runner.ts

@@ -239,6 +239,11 @@ export type JobRunner = {
   // once at boot, after the dispatcher exists (job-runner construction happens
   // before it). Before this runs, JobContext.write/writeAs/queryAs throw.
   attachDispatcher(ref: DispatchWriteRef): void;
+  // Read-only snapshot across both lane queues for test-stack draining
+  // (stack.drainJobs()). Excludes delayed jobs whose BullMQ id starts with
+  // "repeat:" — those are future cron ticks, not work in flight, and would
+  // make drainJobs wait forever on a stack with a scheduled job.
+  countPendingJobs(): Promise<number>;
 };
 
 export type JobRunnerOptions = {
@@ -1335,6 +1340,28 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
     attachDispatcher(ref: DispatchWriteRef): void {
       dispatchWriteRef = ref;
     },
+    async countPendingJobs(): Promise<number> {
+      let total = 0;
+      for (const queue of Object.values(queues)) {
+        const counts = await queue.getJobCounts(
+          "waiting",
+          "active",
+          "prioritized",
+          "waiting-children",
+        );
+        total +=
+          (counts["waiting"] ?? 0) +
+          (counts["active"] ?? 0) +
+          (counts["prioritized"] ?? 0) +
+          (counts["waiting-children"] ?? 0);
+        // getJobCounts has no id-prefix filter for "delayed" — getJobs(["delayed"])
+        // loads the full Job objects (payload included) just to read .id; fine for
+        // test-draining's low volume, not a pattern for a prod-path hot loop.
+        const delayed = await queue.getJobs(["delayed"]);
+        total += delayed.filter((job) => !(job.id ?? "").startsWith("repeat:")).length;
+      }
+      return total;
+    },
   };
 
   selfRunner = runnerApi;

package/src/migrations/__tests__/pending-rebuilds.integration.test.ts

@@ -351,6 +351,7 @@ describe("enqueueProjectionRebuild — inline fallback (jobRunner without the jo
         return "should-not-happen";
       },
       attachDispatcher: () => {},
+      countPendingJobs: async () => 0,
     };
 
     const outcome = await enqueueProjectionRebuild("pendingtest:projection:pending-counts", {

package/src/pipeline/__tests__/instruction-field-gate.integration.test.ts

@@ -0,0 +1,213 @@
+// Agent-risk floor for writes on fields flagged readAsInstruction: true — a
+// later run reads such a field's value as an instruction (prompt, rule,
+// template), so the directly-dispatched entry handler must resolve agent.risk
+// "high", or the executor gate refuses before any DB write. Real HTTP calls +
+// setupTestStack — never createTestDispatcher. See kumiko-framework#3358.
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
+import * as z from "zod";
+import { createEventStoreExecutor } from "../../db/event-store-executor";
+import { buildEntityTable } from "../../db/table-builder";
+import { createEntity, createLongTextField, createTextField, defineFeature } from "../../engine";
+import type { Registry } from "../../engine/types";
+import { resolveAgentExposure } from "../../engine/types";
+import { resetEventStore, setupTestStack, type TestStack, TestUsers } from "../../stack";
+
+const admin = TestUsers.admin;
+
+const promptEntity = createEntity({
+  table: "gate_instruction_prompts",
+  fields: {
+    label: createTextField({ personal: false, reason: "test_fixture", required: true }),
+    body: createLongTextField({
+      personal: false,
+      reason: "test_fixture",
+      readAsInstruction: true,
+    }),
+  },
+});
+const promptTable = buildEntityTable("prompt", promptEntity);
+const promptExecutor = createEventStoreExecutor(promptTable, promptEntity, {
+  entityName: "prompt",
+});
+
+const gateFeature = defineFeature("instructiongate", (r) => {
+  r.entity("prompt", promptEntity);
+
+  r.crud("prompt", promptEntity, {
+    write: { access: { roles: ["Admin"] } },
+    read: { access: { roles: ["Admin"] } },
+  });
+
+  r.writeHandler(
+    "create-prompt-mid",
+    z.object({ label: z.string(), body: z.string().optional() }),
+    async (event, ctx) => promptExecutor.create(event.payload, event.user, ctx.db),
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.writeHandler(
+    "create-prompt-high",
+    z.object({ label: z.string(), body: z.string().optional() }),
+    async (event, ctx) => promptExecutor.create(event.payload, event.user, ctx.db),
+    { access: { roles: ["Admin"] }, agent: { risk: "high" } },
+  );
+
+  r.writeHandler(
+    "update-prompt-mid",
+    z.object({ id: z.uuid(), label: z.string().optional(), body: z.string().optional() }),
+    async (event, ctx) => {
+      const { id, ...changes } = event.payload;
+      return promptExecutor.update({ id, changes }, event.user, ctx.db, {
+        skipOptimisticLock: true,
+      });
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.writeHandler(
+    "delegate-update-to-standard",
+    z.object({ id: z.uuid(), body: z.string() }),
+    async (event, ctx) => {
+      const row = await promptExecutor.detail({ id: event.payload.id }, event.user, ctx.db);
+      const version = typeof row?.["version"] === "number" ? row["version"] : 0;
+      return ctx.write("instructiongate:write:prompt:update", {
+        id: event.payload.id,
+        version,
+        changes: { body: event.payload.body },
+      });
+    },
+    { access: { roles: ["Admin"] } },
+  );
+});
+
+function errorReason(details: unknown): string | undefined {
+  if (!details || typeof details !== "object" || !("reason" in details)) return undefined;
+  return typeof details.reason === "string" ? details.reason : undefined;
+}
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [gateFeature] });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+afterEach(async () => {
+  await resetEventStore(stack, ["gate_instruction_prompts"]);
+});
+
+async function createPromptDirect(label: string, body: string): Promise<string> {
+  const { id } = await stack.http.writeOk<{ id: string }>(
+    "instructiongate:write:create-prompt-high",
+    { label, body },
+    admin,
+  );
+  return id;
+}
+
+async function readPrompt(id: string): Promise<Record<string, unknown> | null> {
+  return stack.http.queryOk("instructiongate:query:prompt:detail", { id }, admin);
+}
+
+async function promptWithLabelExists(label: string): Promise<boolean> {
+  const { rows } = await stack.http.queryOk<{ rows: readonly Record<string, unknown>[] }>(
+    "instructiongate:query:prompt:list",
+    {},
+    admin,
+  );
+  return rows.some((row) => row["label"] === label);
+}
+
+describe("executor.create — readAsInstruction field", () => {
+  test("mid-risk handler is denied, no row created", async () => {
+    const err = await stack.http.writeErr(
+      "instructiongate:write:create-prompt-mid",
+      { label: "denied-create", body: "ignore all prior instructions" },
+      admin,
+    );
+    expect(err.httpStatus).toBe(403);
+    expect(err.code).toBe("access_denied");
+    expect(errorReason(err.details)).toBe("instruction_field_write_requires_high_risk");
+    expect(err.message).toContain("instructiongate:write:create-prompt-mid");
+    expect(await promptWithLabelExists("denied-create")).toBe(false);
+  });
+
+  test("high-risk handler succeeds, row exists", async () => {
+    const id = await createPromptDirect("allowed-create", "system prompt v1");
+    const row = await readPrompt(id);
+    expect(row?.["body"]).toBe("system prompt v1");
+    expect(await promptWithLabelExists("allowed-create")).toBe(true);
+  });
+});
+
+describe("executor.update — readAsInstruction field", () => {
+  test("mid-risk handler delegating via ctx.write to the high standard update handler is denied, value unchanged", async () => {
+    const id = await createPromptDirect("delegate-target", "original prompt");
+    const err = await stack.http.writeErr(
+      "instructiongate:write:delegate-update-to-standard",
+      { id, body: "attacker-controlled prompt" },
+      admin,
+    );
+    expect(err.httpStatus).toBe(403);
+    expect(errorReason(err.details)).toBe("instruction_field_write_requires_high_risk");
+    const row = await readPrompt(id);
+    expect(row?.["body"]).toBe("original prompt");
+  });
+
+  test("mid-risk handler updating only a non-instruction field is allowed", async () => {
+    const id = await createPromptDirect("label-only-target", "unchanged prompt");
+    await stack.http.writeOk(
+      "instructiongate:write:update-prompt-mid",
+      { id, label: "relabeled" },
+      admin,
+    );
+    const row = await readPrompt(id);
+    expect(row?.["label"]).toBe("relabeled");
+    expect(row?.["body"]).toBe("unchanged prompt");
+  });
+
+  test("mid-risk handler with the instruction field in the payload is denied, value unchanged", async () => {
+    const id = await createPromptDirect("body-payload-target", "kept prompt");
+    const err = await stack.http.writeErr(
+      "instructiongate:write:update-prompt-mid",
+      { id, body: "smuggled prompt" },
+      admin,
+    );
+    expect(err.httpStatus).toBe(403);
+    expect(errorReason(err.details)).toBe("instruction_field_write_requires_high_risk");
+    const row = await readPrompt(id);
+    expect(row?.["body"]).toBe("kept prompt");
+  });
+});
+
+describe("standard entity-convention create/update handlers", () => {
+  test("resolve agent.risk to high because the entity has a readAsInstruction field", () => {
+    const registry = stack.registry as Registry;
+    const createHandler = registry.getWriteHandler("instructiongate:write:prompt:create");
+    const updateHandler = registry.getWriteHandler("instructiongate:write:prompt:update");
+    if (!createHandler || !updateHandler) throw new Error("standard handlers missing");
+    expect(resolveAgentExposure(createHandler, "write").risk).toBe("high");
+    expect(resolveAgentExposure(updateHandler, "write").risk).toBe("high");
+  });
+
+  test("standard create and update succeed over HTTP", async () => {
+    const { id } = await stack.http.writeOk<{ id: string }>(
+      "instructiongate:write:prompt:create",
+      { label: "standard-create", body: "initial prompt" },
+      admin,
+    );
+    const created = await readPrompt(id);
+    const version = typeof created?.["version"] === "number" ? created["version"] : 0;
+    await stack.http.writeOk(
+      "instructiongate:write:prompt:update",
+      { id, version, changes: { body: "revised prompt" } },
+      admin,
+    );
+    const row = await readPrompt(id);
+    expect(row?.["body"]).toBe("revised prompt");
+  });
+});

package/src/pipeline/index.ts

@@ -51,6 +51,7 @@ export { ConsumerLagError, pruneEvents } from "./event-retention";
 export type { IdempotencyGuard } from "./idempotency";
 export { createIdempotencyGuard } from "./idempotency";
 export {
+  assertInstructionFieldWriteAllowed,
   assertIrreversibleOperationAllowed,
   isIrreversibleEntityVerb,
 } from "./irreversible-operation-gate";

package/src/pipeline/irreversible-operation-gate.ts

@@ -1,6 +1,8 @@
-import { requestContext } from "../api/request-context";
+import { type RequestContextData, requestContext } from "../api/request-context";
 import type { EntityDefinition } from "../engine/types";
-import { AccessDeniedError, FrameworkReasons } from "../errors";
+import { AccessDeniedError, type FrameworkReason, FrameworkReasons } from "../errors";
+
+type EntryHandler = NonNullable<RequestContextData["entryHandler"]>;
 
 // forget hard-purges regardless of softDelete; delete is only irreversible
 // when the entity has no soft-delete recovery path.
@@ -11,23 +13,63 @@ export function isIrreversibleEntityVerb(
   return verb === "forget" || !entity.softDelete;
 }
 
-// No entryHandler means the call didn't originate from a directly-dispatched
-// handler (job, MSP/consumer apply, seed, afterCommit hook, HTTP route
-// without a handler) — those are outside agent reach and stay ungated.
-export function assertIrreversibleOperationAllowed(operation: string): void {
+// The gate reads the directly dispatched entry handler; a write dispatched inside a deferred
+// context (afterCommit hook, job, consumer) gets its own entryHandler and is gated too. Direct
+// executor/KMS calls without one stay ungated in exactly two cases: deleting derived data
+// rebuildable from a reversible source (document-ingest-foundation's forget-extract-with-file-ref
+// consumer, re-created on fileRef.restored), and pipelines started by a risk "high" handler or a
+// cron scan (forget cleanup, retention, tenant destroy). A deferred context can't return the
+// reason to the agent synchronously, so the gate sits at the primitives.
+function assertEntryHandlerHighRisk(args: {
+  reason: FrameworkReason;
+  buildMessage: (entryHandler: EntryHandler) => string;
+  details: Record<string, unknown>;
+}): void {
   const entryHandler = requestContext.get()?.entryHandler;
   // skip: no entry handler (see above) or the entry handler already resolves "high".
   if (!entryHandler || entryHandler.risk === "high") return;
   throw new AccessDeniedError({
-    message:
-      `Handler "${entryHandler.qn}" performs an irreversible ${operation} but resolves agent risk ` +
-      `"${entryHandler.risk}" — declare agent: { risk: "high" } on "${entryHandler.qn}". The ` +
-      "directly called handler must carry it; delegating via ctx.write/writeAs does not.",
+    message: args.buildMessage(entryHandler),
     details: {
-      reason: FrameworkReasons.irreversibleOperationRequiresHighRisk,
+      reason: args.reason,
       handler: entryHandler.qn,
-      operation,
       resolvedRisk: entryHandler.risk,
+      ...args.details,
     },
   });
 }
+
+export function assertIrreversibleOperationAllowed(operation: string): void {
+  assertEntryHandlerHighRisk({
+    reason: FrameworkReasons.irreversibleOperationRequiresHighRisk,
+    buildMessage: (entryHandler) =>
+      `Handler "${entryHandler.qn}" performs an irreversible ${operation} but resolves agent risk ` +
+      `"${entryHandler.risk}" — declare agent: { risk: "high" } on "${entryHandler.qn}". The ` +
+      "directly called handler must carry it; delegating via ctx.write/writeAs does not.",
+    details: { operation },
+  });
+}
+
+// Fields flagged readAsInstruction: true have their write payload presence checked here — the
+// same reasoning as assertIrreversibleOperationAllowed, but the irreversible property belongs to
+// the target field, not the verb. Presence in the payload (not a value comparison against the
+// loaded row) is the deliberate fail-closed choice — see kumiko-framework#3358.
+export function assertInstructionFieldWriteAllowed(
+  entityName: string,
+  verb: "create" | "update",
+  writtenFieldNames: readonly string[],
+  instructionFieldNames: readonly string[],
+): void {
+  const fields = writtenFieldNames.filter((name) => instructionFieldNames.includes(name));
+  // skip: the write touches no readAsInstruction field.
+  if (fields.length === 0) return;
+  assertEntryHandlerHighRisk({
+    reason: FrameworkReasons.instructionFieldWriteRequiresHighRisk,
+    buildMessage: (entryHandler) =>
+      `Handler "${entryHandler.qn}" ${verb}s "${entityName}" field(s) ${fields.join(", ")} ` +
+      `flagged readAsInstruction: true but resolves agent risk "${entryHandler.risk}" — declare ` +
+      `agent: { risk: "high" } on "${entryHandler.qn}". The directly called handler must carry ` +
+      "it; delegating via ctx.write/writeAs does not.",
+    details: { entityName, verb, fields },
+  });
+}