@cspeach/cli 1.1.40 → 1.1.41

package/dist/tools/sap-write.js

@@ -22,155 +22,79 @@
  * auditLog aliased from safety/audit-log.ts#log via sap-client/src/index.ts.
  */
 import crypto from 'node:crypto';
-import { readFileSync } from 'node:fs';
 import { registerTool } from './index.js';
 import { byObjectType } from '../sap/profile-gate.js';
 import { verifyAndSpendApprovalId } from '../approvals/jwt.js';
-import { grantClaimMismatch, grantActivateMismatch, grantOwningTransportMismatch, grantOwningTransportDetail } from '../approvals/grant-claims.js';
-import { autoSnapshot, autoSnapshotClassInclude, autoSnapshotMessageClass } from './snapshot.js';
-import { includeSnapshotType } from './include-snapshot.js';
-import { buildWriteChainLine } from '../renderer/verify-chain.js';
-import { buildChangeCard } from '../renderer/change-card.js';
+import { grantActivateMismatch } from '../approvals/grant-claims.js';
 import { getLook } from '../renderer/look.js';
-import { getEffectiveBodyWidth } from '../renderer/tty.js';
-import { verifySyntax, verifyActive } from './verify.js';
+import { verifyActive } from './verify.js';
 import { hasRecordedSyntaxErrorsByName, clearSyntaxErrorsAfterActivation } from './syntax-state.js';
 import { teamFixOffers, cspeachWritesThisSession } from '../register/offer.js';
-import { isJourneyActive } from '../journey/flow.js';
 import { appendPending, finalizeToolCall } from '../session/pending.js';
 import { checkTransportFit, reusedRequestRefusal } from './transport-fit-check.js';
 import { auditLog } from '@cspeach/sap-client';
 import { ERR } from '../errors/codes.js';
 import { interceptUpdateMethod, CancelledByUserError, } from './update-method-intercept.js';
-import { resolveWriteTransport } from './transport-resolution.js';
 // F-L2-1: statusline-only wire — records the transport a write ACTUALLY
 // stamped so the `tr` segment stops reading `none` for plan-supplied
 // transports. Never touches the session transport pointer.
 import { noteWriteTransport, setCurrentTransport } from '../repl/current-transport.js';
 import { markTransportCreatedThisSession } from './transport.js';
-import { presentSafetyConfirmation } from '../repl/safety-confirm.js';
-import { isSafetyConfirmEnabled } from '../repl/safety-mode-state.js';
 import { hasManualLocks, noteManualLock, noteManualUnlock } from '../sap/session-end.js';
-// ── Transcript visibility helpers (D16-display + tour slide-7, 2026-06-12) ──
-//
-// Rule 7 auto-snapshots always fired but the transcript never said so
-// (battery D16-display). And the tour shows writes as
-// "① snapshot ✓ ② written ✓ ③ syntax ✓ ④ activated ✓" while real
-// transcripts showed an opaque tool row. Both lines below are HUMAN-stream
-// only (ctx.chunkEmitter) — tool RESULT payloads the model sees are
-// unchanged, and subagent ctxs (no chunkEmitter) stay silent.
-/** Dim one-liner when the Rule 7 auto-snapshot actually captured source. */
-function emitSnapshotNotice(ctx, snap, type, name) {
-    if (snap?.taken && snap.entry) {
-        ctx.chunkEmitter?.emit('info', `snapshot ✓ ${type} ${name} ${snap.entry.timestamp}`);
-    }
-}
-/** Distinct LOUD note when the write proceeds against a fresh/never-activated
- *  shell that has no committed active version — nothing to snapshot (Rule 7 is
- *  satisfied because there is no prior source to protect). Kept separate from
- *  the 'new_object' (genuine 404) path so the transcript is honest about which
- *  case it was — this is the RAP behaviour-pool ZBP first-write. */
-function emitNewShellNote(ctx, type, name) {
-    ctx.chunkEmitter?.emit('warn', `${type} ${name}: new/empty shell — no active version, no prior source to snapshot; proceeding with first write`);
-}
-/** Map the snapshot-gate outcome onto the chain line's honest states.
- *  `undefined` covers the best-effort gates whose failure was swallowed.
- *  'object_not_found' is a genuine ADT 404 only; any other read failure maps
- *  to 'source_read_failed' (+ short detail) — never to "(new object)".
- *  'new_shell' (exists but no active version — nothing to save) reuses the
- *  'new_object' chain glyph; the honest which-case distinction is carried by
- *  the LOUD emitNewShellNote line, not the compact chain. */
-function snapshotChainState(snap) {
-    if (snap?.taken)
-        return { snapshot: 'taken' };
-    if (snap?.reason === 'object_not_found' || snap?.reason === 'new_shell') {
-        return { snapshot: 'new_object' };
-    }
-    if (snap?.reason === 'source_read_failed') {
-        return { snapshot: 'source_read_failed', snapshotDetail: snap.detail };
-    }
-    return { snapshot: 'best_effort_failed' };
-}
-/**
- * Review r7 I-3 — sap-client 0.1.15's setSource/updateMethod run their own
- * (correct) syntax check and, on errors, return a 2xx writeStatus with
- * `syntaxResult.hasErrors` and `error: 'Syntax check found errors —
- * activation skipped'`. The source IS written (an inactive version exists):
- * that is written-with-errors — the normal Rule 10 gate below reports it —
- * never write_failed.
- */
-function writtenWithSyntaxErrors(r) {
-    return r.writeStatus !== undefined && r.writeStatus >= 200 && r.writeStatus < 300 && r.syntaxResult?.hasErrors === true;
-}
-async function verifyWriteActivation(ctx, r, name, type) {
-    const a = r.activationResult;
-    if (!a)
-        return undefined;
-    const errors = (a.messages ?? []).filter((m) => m.severity === 'error').map((m) => m.shortText ?? '').filter(Boolean).slice(0, 5);
-    if (!a.success)
-        return { success: false, verified: false, errors };
-    const v = await verifyActive(ctx.adt, name, type);
-    if (v.verifyError !== undefined)
-        return { success: true, verified: false, errors, verifyError: v.verifyError };
-    return v.active ? { success: true, verified: true, errors } : { success: true, verified: false, errors, stillInactive: true };
-}
-/** Round 8 item 5 + A-I1 — the change-frame state from the verified activation. */
-function chainActivation(w) {
-    if (!w)
-        return undefined;
-    if (!w.success)
-        return { state: 'failed', detail: w.errors[0] };
-    if (w.verified)
-        return { state: 'active' };
-    return w.stillInactive ? { state: 'still_inactive' } : { state: 'unverified' };
-}
-/**
- * 1.1.31 — the write itself activated and verified an object of the joined team
- * project: CSPeach wrote it, so the fix is recorded for the developer (rehearsal
- * 2026-10-07: the refactor's write activated the class; no separate sap_activate
- * ran, so the hook in sap_activate alone never fired).
- */
-/** Guided clean-core journey on: the fix lines in solo words (register/offer.ts). */
-const journeyWording = (ctx) => (isJourneyActive(ctx.session) ? { wording: 'journey' } : {});
-function recordOwnFixAfterWrite(ctx, type, name, transport, w) {
-    if (!w?.success || !w.verified)
-        return;
-    const written = new Map([[String(name).trim().toUpperCase(), String(transport ?? '').trim().toUpperCase()]]);
-    for (const line of teamFixOffers([{ type, name }], { written, ...journeyWording(ctx) }))
-        ctx.chunkEmitter?.emit('info', line);
-}
-function activatedByWrite(w) {
-    if (!w)
-        return {};
-    return { activated_by_write: { success: w.success, verified: w.verified, errors: w.errors } };
-}
-/** A-I1 minor — after a verified activation on write, say so instead of "activation_allowed". */
-function nextStepAfterWrite(syntaxOk, w) {
-    if (!syntaxOk)
-        return 'activation_blocked_until_syntax_errors_fixed';
-    if (w?.success && w.verified)
-        return 'already activated by the write — verify with sap_inactive_objects before reporting it active';
-    return 'activation_allowed';
-}
-/** Compact ①②③④ pipeline summary — derived from the real gate results.
- *  Panels look: a change card (same honest chain in its footer). */
-function emitWriteChain(ctx, input) {
-    const text = getLook() === 'panels' && input.card
-        ? buildChangeCard(input, getEffectiveBodyWidth())
-        : buildWriteChainLine(input);
-    ctx.chunkEmitter?.emit('chunk', text + '\n');
-}
-/** Old source for the change card: ONLY from a snapshot actually taken. */
-function snapshotSource(snap) {
-    if (!snap?.taken || !snap.entry?.filePath)
-        return undefined;
-    try {
-        return readFileSync(snap.entry.filePath, 'utf8');
-    }
-    catch {
-        return undefined;
-    }
-}
+import { snapshotChainState, writtenWithSyntaxErrors, chainActivation, journeyWording, activatedByWrite, nextStepAfterWrite, snapshotSource, writeToolHandler, } from './write-pipeline.js';
+const SET_SOURCE_SPEC = {
+    tool: 'sap_set_source',
+    approval: {
+        object: (a) => a.name,
+        op: 'modify',
+        claims: (a, ctx) => ({ type: a.type, transport: a.transport ?? ctx.currentTransport?.get() ?? null }),
+    },
+    transport: { mode: 'resolve', type: (a) => a.type, name: (a) => a.name, grantMismatch: true },
+    snapshot: { kind: 'source', hard: true, type: (a) => a.type, name: (a) => a.name },
+    safetyConfirm: (a, transport) => ({
+        rule: 'RULE_7_SNAPSHOT_BEFORE_WRITE',
+        op: 'set_source',
+        object: { type: a.type, name: a.name },
+        what_will_happen: 'Overwrites full object source; snapshot is taken first.',
+        rollback_available: true,
+        transport,
+        args: { ...a },
+    }),
+    walArgs: (a) => ({ name: a.name, type: a.type }),
+    call: (a, ctx, pre) => ctx.adt.setSource(a.type, a.name, a.source, pre.transport),
+    errorCode: 'write_failed',
+    landed: (r) => (r.error && !writtenWithSyntaxErrors(r)) || (r.writeStatus !== undefined && r.writeStatus >= 400)
+        ? { ok: false, detail: r.error ?? `Write returned HTTP ${r.writeStatus} but did not throw`, extra: { write_status: r.writeStatus } }
+        : { ok: true },
+    audit: { method: 'setSource', type: (a) => a.type, name: (a) => a.name },
+    verify: { syntax: true, activation: true },
+    chain: (a, pre, syntax, act) => {
+        // Old source is read (once) only for the panels card; legacy reads nothing extra.
+        const oldSource = getLook() === 'panels' ? snapshotSource(pre.snapshot) : undefined;
+        return {
+            ...snapshotChainState(pre.snapshot),
+            written: true,
+            syntax: { ok: syntax.ok, errors: syntax.errors },
+            activation: chainActivation(act),
+            card: {
+                object: a.name,
+                what: 'source',
+                transport: pre.transport,
+                oldSource,
+                newSource: oldSource !== undefined ? a.source : undefined,
+            },
+        };
+    },
+    envelope: (_a, _r, pre, syntax, act) => ({
+        written: true,
+        syntax_ok: syntax.ok,
+        errors: syntax.errors,
+        warnings: syntax.warnings,
+        ...activatedByWrite(act),
+        ...(pre.owning ? { transport_used: pre.owning, transport_note: pre.note } : {}),
+        next_step: nextStepAfterWrite(syntax.ok, act),
+    }),
+};
 registerTool({
     name: 'sap_set_source',
     requires: byObjectType,
@@ -191,175 +115,89 @@ registerTool({
         },
         required: ['name', 'type', 'source', 'approval_id'],
     },
-    handler: async (args, ctx) => {
-        // ── Gate 1: Approval ────────────────────────────────────────────────────
-        const verify = await verifyAndSpendApprovalId(args.approval_id, args.name, 'modify');
-        if (!verify.ok) {
-            return {
-                content: JSON.stringify({ error: ERR.APPROVAL_INVALID, reason: verify.reason }),
-                is_error: true,
-            };
-        }
-        // 2026-10-04 — a plan-grant id holds the write to its claims (type, package, transport).
-        {
-            const claim = grantClaimMismatch(verify.payload, { type: args.type, transport: args.transport ?? ctx.currentTransport?.get() ?? null });
-            if (claim)
-                return { content: JSON.stringify({ error: ERR.APPROVAL_INVALID, reason: claim }), is_error: true };
-        }
-        const toolUseId = ctx.toolUseId ?? crypto.randomUUID();
-        const startedAt = Date.now();
-        // ── Rule 9 conflict warning ──────────────────────────────────────────────
-        // Emit a warning if the LLM passed an explicit transport that differs from
-        // the session current-transport. Prefer LLM intent (explicit caller); this
-        // is informational only and does NOT block the operation.
-        {
-            const sessionTransport = ctx.currentTransport?.get() ?? null;
-            if (args.transport && sessionTransport && args.transport !== sessionTransport) {
-                ctx.chunkEmitter?.emit('warn', `LLM passed transport=${args.transport} but session current-transport=${sessionTransport}`);
-            }
-        }
-        // ── Rule 9 owning-transport check (D15/D20) ──────────────────────────────
-        // If the object is already locked in an open request, write under THAT
-        // request — any other transport is a guaranteed CTS lock conflict.
-        const resolved = await resolveWriteTransport(ctx, args.type, args.name, args.transport);
-        // 2026-10-04 — a plan-grant id never writes into a transport other than the grant's.
-        if (grantOwningTransportMismatch(verify.payload, resolved.owning)) {
-            return {
-                content: JSON.stringify({ error: ERR.APPROVAL_INVALID, reason: 'transport_mismatch', detail: grantOwningTransportDetail(args.name, resolved.owning) }),
-                is_error: true,
-            };
-        }
-        // ── Gate 2: Snapshot (Rule 7) — HARD gate ────────────────────────────────
-        // Only a genuine 404 (new object) may proceed snapshot-less. A read
-        // failure on a possibly-EXISTING object means no recovery copy → block.
-        let snapOutcome;
-        try {
-            snapOutcome = await autoSnapshot(args.name, args.type, ctx.adt);
-        }
-        catch (err) {
-            return {
-                content: JSON.stringify({ error: ERR.SNAPSHOT_FAILED, detail: String(err) }),
-                is_error: true,
-            };
-        }
-        if (snapOutcome?.reason === 'source_read_failed') {
-            return {
-                content: JSON.stringify({
-                    error: ERR.SNAPSHOT_FAILED,
-                    reason: 'source_read_failed',
-                    detail: snapOutcome.detail,
-                    recovery: 'Pre-write source read failed (non-404) and no committed active version could be confirmed — the object may exist with source we could not read, so no snapshot was possible. If this is a live connection/auth problem, fix it and retry. If this is a freshly-created shell that got edit-locked by an earlier aborted write, recover it directly: unlock it (or activate the empty shell, then delete it) and re-run the create+write. Do not bypass Rule 7 by writing over source you never read.',
-                }),
-                is_error: true,
-            };
-        }
-        // Fresh/never-activated shell (no active version → nothing to snapshot):
-        // proceed like a new object, but say so LOUDLY and distinctly.
-        if (snapOutcome?.reason === 'new_shell')
-            emitNewShellNote(ctx, args.type, args.name);
-        emitSnapshotNotice(ctx, snapOutcome, args.type, args.name);
-        // ── Gate 3: Safety confirmation (Rule 7) ─────────────────────────────────
-        if (isSafetyConfirmEnabled()) {
-            const r = await presentSafetyConfirmation({
-                rule: 'RULE_7_SNAPSHOT_BEFORE_WRITE',
-                op: 'set_source',
-                object: { type: args.type, name: args.name },
-                what_will_happen: 'Overwrites full object source; snapshot is taken first.',
-                rollback_available: true,
-                transport: resolved.transport ?? ctx.currentTransport?.get() ?? '',
-                args: { ...args },
-            });
-            if (!r.confirmed) {
-                return {
-                    content: JSON.stringify({ error: 'cancelled_by_user', reason: r.reason }),
-                    is_error: true,
-                };
-            }
+    handler: writeToolHandler(SET_SOURCE_SPEC),
+});
+/** Rule 7 recovery text in the class wording (sap_update_method always targets a class). */
+const CLASS_READ_RECOVERY = 'Pre-write source read failed (non-404) and no committed active version could be confirmed — the class may exist with source we could not read, so no snapshot was possible. If this is a live connection/auth problem, fix it and retry. If this is a freshly-created class shell that got edit-locked by an earlier aborted write, recover it directly: unlock it (or activate the empty shell, then delete it) and re-run the create+write. Do not bypass Rule 7 by writing over source you never read.';
+const UPDATE_METHOD_SPEC = {
+    tool: 'sap_update_method',
+    approval: {
+        object: (a) => a.class_name,
+        op: 'modify',
+        claims: (a, ctx) => ({ type: 'CLAS', transport: a.transport ?? ctx.currentTransport?.get() ?? null }),
+    },
+    transport: { mode: 'resolve', type: () => 'CLAS', name: (a) => a.class_name, grantMismatch: true },
+    // sap_update_method always targets an EXISTING class, so a read failure
+    // (non-404) means no recovery copy → block. (A genuine 404 falls through
+    // here but the preview gate fails on the same missing class.)
+    snapshot: { kind: 'source', hard: true, type: () => 'CLAS', name: (a) => a.class_name, recovery: CLASS_READ_RECOVERY },
+    // Gate 3: diff preview & confirmation (Rule 7a).
+    preGate: async (a, ctx, pre) => {
+        if (!ctx.previewHook) {
+            return { error: { error: 'preview_hook_unavailable', detail: 'cannot confirm method body changes in this execution context' } };
         }
-        // ── WAL: record pending entry ────────────────────────────────────────────
-        await appendPending(ctx.session, {
-            tool_use_id: toolUseId,
-            tool: 'sap_set_source',
-            args: { name: args.name, type: args.type },
-            started_at: new Date().toISOString(),
-        });
-        // ── Write ────────────────────────────────────────────────────────────────
-        // setSource(type, name, source, transport?) — transport is optional.
-        //
-        // CRITICAL: AdtClient.setSource only THROWS for catastrophic errors (network
-        // down, all retries exhausted). For HTTP 4xx responses (e.g., the second PUT
-        // after 423-recovery still failing) it RETURNS a WriteResult with
-        // writeStatus >= 400 and `error: '...'`. The handler MUST check the return
-        // value — without it, we silently report success on a failed write.
-        // Regression evidence + diagnosis: memory/project_phase3_lite_regression.md.
-        let writeResult;
+        const minimal = {
+            getSource: ({ type, name }) => ctx.adt.getSource(type, name),
+        };
+        const call = {
+            className: a.class_name,
+            methodName: a.method_name,
+            methodSource: a.method_source,
+            transport: pre.transport ?? ctx.currentTransport?.get() ?? '',
+        };
         try {
-            writeResult = await ctx.adt.setSource(args.type, args.name, args.source, resolved.transport);
+            await interceptUpdateMethod(minimal, call, ctx.previewHook);
         }
         catch (err) {
-            const errStr = String(err);
-            await finalizeToolCall(ctx.session, toolUseId, errStr, true, Date.now() - startedAt);
-            return {
-                content: JSON.stringify({ error: 'write_failed', detail: errStr }),
-                is_error: true,
-            };
+            if (err instanceof CancelledByUserError)
+                return { error: { error: 'cancelled_by_user', detail: err.message } };
+            return { error: { error: 'preview_failed', detail: String(err) } };
         }
-        if ((writeResult.error && !writtenWithSyntaxErrors(writeResult)) || (writeResult.writeStatus !== undefined && writeResult.writeStatus >= 400)) {
-            const detail = writeResult.error ?? `Write returned HTTP ${writeResult.writeStatus} but did not throw`;
-            await finalizeToolCall(ctx.session, toolUseId, detail, true, Date.now() - startedAt);
+        return { ok: true };
+    },
+    walArgs: (a) => ({ class_name: a.class_name, method_name: a.method_name }),
+    // Same return semantics as setSource — RETURNS a WriteResult on HTTP-level failure.
+    call: (a, ctx, pre) => ctx.adt.updateMethod(a.class_name, a.method_name, a.method_source, pre.transport),
+    // Bug 13 (2026-05-15): updateMethod throws SapError(409) when the class has
+    // pending inactive changes (split state) — a recoverable envelope, so the
+    // model suggests activating / discarding the inactive version first.
+    onThrow: (err, a) => {
+        const errStr = String(err);
+        const httpStatus = err?.httpStatus;
+        if (httpStatus === 409 && /pending inactive/i.test(errStr)) {
             return {
-                content: JSON.stringify({
-                    error: 'write_failed',
-                    detail,
-                    write_status: writeResult.writeStatus,
-                }),
-                is_error: true,
+                error: 'split_state',
+                detail: errStr,
+                class_name: a.class_name,
+                recovery: 'Activate (sap_activate) or discard the inactive version of this class, then retry sap_update_method.',
             };
         }
-        await auditLog('setSource', args.type, args.name, 'success', Date.now() - startedAt);
-        noteWriteTransport(resolved.transport); // F-L2-1 statusline wire
-        // ── Gate 4: Verify — syntax check (Rule 10) ──────────────────────────────
-        const syntax = await verifySyntax(ctx.adt, args.name, args.type);
-        await finalizeToolCall(ctx.session, toolUseId, JSON.stringify({ written: true, syntax }), false, Date.now() - startedAt);
-        const writeActivation = await verifyWriteActivation(ctx, writeResult, args.name, args.type);
-        // Tour slide-7 chain — derived from the gates that actually ran.
-        // Old source is read (once) only for the panels card; legacy reads nothing extra.
-        const oldSource = getLook() === 'panels' ? snapshotSource(snapOutcome) : undefined;
-        emitWriteChain(ctx, {
-            ...snapshotChainState(snapOutcome),
-            written: true,
-            syntax: { ok: syntax.ok, errors: syntax.errors },
-            activation: chainActivation(writeActivation),
-            card: {
-                object: args.name,
-                what: 'source',
-                transport: resolved.transport,
-                oldSource,
-                newSource: oldSource !== undefined ? args.source : undefined,
-            },
-        });
-        recordOwnFixAfterWrite(ctx, args.type, args.name, resolved.owning ?? resolved.transport, writeActivation);
-        return {
-            content: JSON.stringify({
-                written: true,
-                syntax_ok: syntax.ok,
-                errors: syntax.errors,
-                warnings: syntax.warnings,
-                ...activatedByWrite(writeActivation),
-                ...(resolved.owning ? { transport_used: resolved.owning, transport_note: resolved.note } : {}),
-                next_step: nextStepAfterWrite(syntax.ok, writeActivation),
-            }),
-        };
+        return undefined;
     },
-});
-// ── sap_update_method ────────────────────────────────────────────────────────
-//
-// Rule 7a: method-body-only edits. Reads current source, replaces the named
-// method block in-memory, then delegates to setSource internally via
-// AdtClient.updateMethod. Does NOT rewrite the class definition.
-//
-// Signature: updateMethod(className, methodName, methodBody, transport?)
-//   methodBody — the lines BETWEEN METHOD x. and ENDMETHOD. (no wrappers)
+    errorCode: 'update_failed',
+    landed: (r) => (r.error && !writtenWithSyntaxErrors(r)) || (r.writeStatus !== undefined && r.writeStatus >= 400)
+        ? { ok: false, detail: r.error ?? `Update returned HTTP ${r.writeStatus} but did not throw`, extra: { write_status: r.writeStatus } }
+        : { ok: true },
+    audit: { method: 'updateMethod', type: () => 'CLAS', name: (a) => a.class_name, detail: (a) => `method=${a.method_name}` },
+    verify: { syntax: true, activation: true },
+    walResult: (_a, _r, _pre, syntax) => ({ updated: true, syntax }),
+    chain: (a, pre, syntax, act) => ({
+        ...snapshotChainState(pre.snapshot),
+        written: true,
+        syntax: { ok: syntax.ok, errors: syntax.errors },
+        activation: chainActivation(act),
+        card: { object: a.class_name, what: `method ${a.method_name}`, transport: pre.transport },
+    }),
+    envelope: (_a, _r, pre, syntax, act) => ({
+        updated: true,
+        syntax_ok: syntax.ok,
+        errors: syntax.errors,
+        warnings: syntax.warnings,
+        ...activatedByWrite(act),
+        ...(pre.owning ? { transport_used: pre.owning, transport_note: pre.note } : {}),
+        next_step: nextStepAfterWrite(syntax.ok, act),
+    }),
+};
 registerTool({
     name: 'sap_update_method',
     description: 'Replace the body of a single method in an existing class. '
@@ -380,193 +218,42 @@ registerTool({
         },
         required: ['class_name', 'method_name', 'method_source', 'approval_id'],
     },
-    handler: async (args, ctx) => {
-        // ── Gate 1: Approval ────────────────────────────────────────────────────
-        const verify = await verifyAndSpendApprovalId(args.approval_id, args.class_name, 'modify');
-        if (!verify.ok) {
-            return {
-                content: JSON.stringify({ error: ERR.APPROVAL_INVALID, reason: verify.reason }),
-                is_error: true,
-            };
-        }
-        // 2026-10-04 — a plan-grant id holds the write to its claims (type, package, transport).
-        {
-            const claim = grantClaimMismatch(verify.payload, { type: 'CLAS', transport: args.transport ?? ctx.currentTransport?.get() ?? null });
-            if (claim)
-                return { content: JSON.stringify({ error: ERR.APPROVAL_INVALID, reason: claim }), is_error: true };
-        }
-        const toolUseId = ctx.toolUseId ?? crypto.randomUUID();
-        const startedAt = Date.now();
-        // ── Rule 9 conflict warning ──────────────────────────────────────────────
-        // Emit a warning if the LLM passed an explicit transport that differs from
-        // the session current-transport. Prefer LLM intent (explicit caller); this
-        // is informational only and does NOT block the operation.
-        {
-            const sessionTransport = ctx.currentTransport?.get() ?? null;
-            if (args.transport && sessionTransport && args.transport !== sessionTransport) {
-                ctx.chunkEmitter?.emit('warn', `LLM passed transport=${args.transport} but session current-transport=${sessionTransport}`);
-            }
-        }
-        // ── Rule 9 owning-transport check (D15/D20) ──────────────────────────────
-        const resolved = await resolveWriteTransport(ctx, 'CLAS', args.class_name, args.transport);
-        // 2026-10-04 — a plan-grant id never writes into a transport other than the grant's.
-        if (grantOwningTransportMismatch(verify.payload, resolved.owning)) {
-            return {
-                content: JSON.stringify({ error: ERR.APPROVAL_INVALID, reason: 'transport_mismatch', detail: grantOwningTransportDetail(args.class_name, resolved.owning) }),
-                is_error: true,
-            };
-        }
-        // ── Gate 2: Snapshot (Rule 7) — HARD gate ────────────────────────────────
-        // sap_update_method always targets an EXISTING class, so a read failure
-        // (non-404) means no recovery copy → block. (A genuine 404 falls through
-        // here but the preview gate below fails on the same missing class.)
-        let snapOutcome;
-        try {
-            snapOutcome = await autoSnapshot(args.class_name, 'CLAS', ctx.adt);
-        }
-        catch (err) {
-            return {
-                content: JSON.stringify({ error: ERR.SNAPSHOT_FAILED, detail: String(err) }),
-                is_error: true,
-            };
-        }
-        if (snapOutcome?.reason === 'source_read_failed') {
-            return {
-                content: JSON.stringify({
-                    error: ERR.SNAPSHOT_FAILED,
-                    reason: 'source_read_failed',
-                    detail: snapOutcome.detail,
-                    recovery: 'Pre-write source read failed (non-404) and no committed active version could be confirmed — the class may exist with source we could not read, so no snapshot was possible. If this is a live connection/auth problem, fix it and retry. If this is a freshly-created class shell that got edit-locked by an earlier aborted write, recover it directly: unlock it (or activate the empty shell, then delete it) and re-run the create+write. Do not bypass Rule 7 by writing over source you never read.',
-                }),
-                is_error: true,
-            };
-        }
-        // Fresh/never-activated class shell (no active version → nothing to
-        // snapshot): proceed like a new object, but say so LOUDLY and distinctly.
-        if (snapOutcome?.reason === 'new_shell')
-            emitNewShellNote(ctx, 'CLAS', args.class_name);
-        emitSnapshotNotice(ctx, snapOutcome, 'CLAS', args.class_name);
-        // ── Gate 3: Diff preview & confirmation (Rule 7a) ────────────────────────
-        if (!ctx.previewHook) {
-            return {
-                content: JSON.stringify({
-                    error: 'preview_hook_unavailable',
-                    detail: 'cannot confirm method body changes in this execution context',
-                }),
-                is_error: true,
-            };
-        }
-        const minimal = {
-            getSource: ({ type, name }) => ctx.adt.getSource(type, name),
-        };
-        const call = {
-            className: args.class_name,
-            methodName: args.method_name,
-            methodSource: args.method_source,
-            transport: resolved.transport ?? ctx.currentTransport?.get() ?? '',
-        };
-        try {
-            await interceptUpdateMethod(minimal, call, ctx.previewHook);
-        }
-        catch (err) {
-            if (err instanceof CancelledByUserError) {
-                return {
-                    content: JSON.stringify({ error: 'cancelled_by_user', detail: err.message }),
-                    is_error: true,
-                };
-            }
-            return {
-                content: JSON.stringify({ error: 'preview_failed', detail: String(err) }),
-                is_error: true,
-            };
-        }
-        // ── WAL: record pending entry ────────────────────────────────────────────
-        await appendPending(ctx.session, {
-            tool_use_id: toolUseId,
-            tool: 'sap_update_method',
-            args: { class_name: args.class_name, method_name: args.method_name },
-            started_at: new Date().toISOString(),
-        });
-        // ── Write ────────────────────────────────────────────────────────────────
-        // updateMethod(className, methodName, methodBody, transport?). Same return
-        // semantics as setSource — RETURNS a WriteResult on HTTP-level failure
-        // rather than throwing. Must check writeStatus / error on the return value.
-        //
-        // Bug 13 (2026-05-15): AdtClient.updateMethod now throws SapError(409)
-        // when the class has pending inactive changes (split state). Surface that
-        // as a recoverable `split_state` envelope so the model can suggest the
-        // user activate / discard the inactive version before retrying — without
-        // silently overwriting the inactive-only declarations.
-        let updateResult;
-        try {
-            updateResult = await ctx.adt.updateMethod(args.class_name, args.method_name, args.method_source, resolved.transport);
-        }
-        catch (err) {
-            const errStr = String(err);
-            const httpStatus = err?.httpStatus;
-            if (httpStatus === 409 && /pending inactive/i.test(errStr)) {
-                await finalizeToolCall(ctx.session, toolUseId, errStr, true, Date.now() - startedAt);
-                return {
-                    content: JSON.stringify({
-                        error: 'split_state',
-                        detail: errStr,
-                        class_name: args.class_name,
-                        recovery: 'Activate (sap_activate) or discard the inactive version of this class, then retry sap_update_method.',
-                    }),
-                    is_error: true,
-                };
-            }
-            await finalizeToolCall(ctx.session, toolUseId, errStr, true, Date.now() - startedAt);
-            return {
-                content: JSON.stringify({ error: 'update_failed', detail: errStr }),
-                is_error: true,
-            };
-        }
-        if ((updateResult.error && !writtenWithSyntaxErrors(updateResult)) || (updateResult.writeStatus !== undefined && updateResult.writeStatus >= 400)) {
-            const detail = updateResult.error ?? `Update returned HTTP ${updateResult.writeStatus} but did not throw`;
-            await finalizeToolCall(ctx.session, toolUseId, detail, true, Date.now() - startedAt);
-            return {
-                content: JSON.stringify({
-                    error: 'update_failed',
-                    detail,
-                    write_status: updateResult.writeStatus,
-                }),
-                is_error: true,
-            };
-        }
-        await auditLog('updateMethod', 'CLAS', args.class_name, 'success', Date.now() - startedAt, `method=${args.method_name}`);
-        noteWriteTransport(resolved.transport); // F-L2-1 statusline wire
-        // ── Gate 4: Verify — syntax check (Rule 10) ──────────────────────────────
-        const syntax = await verifySyntax(ctx.adt, args.class_name, 'CLAS');
-        await finalizeToolCall(ctx.session, toolUseId, JSON.stringify({ updated: true, syntax }), false, Date.now() - startedAt);
-        const writeActivation = await verifyWriteActivation(ctx, updateResult, args.class_name, 'CLAS');
-        // Tour slide-7 chain — derived from the gates that actually ran.
-        emitWriteChain(ctx, {
-            ...snapshotChainState(snapOutcome),
-            written: true,
-            syntax: { ok: syntax.ok, errors: syntax.errors },
-            activation: chainActivation(writeActivation),
-            card: { object: args.class_name, what: `method ${args.method_name}`, transport: resolved.transport },
-        });
-        recordOwnFixAfterWrite(ctx, 'CLAS', args.class_name, resolved.owning ?? resolved.transport, writeActivation);
+    handler: writeToolHandler(UPDATE_METHOD_SPEC),
+});
+const DELETE_OBJECT_SPEC = {
+    tool: 'sap_delete_object',
+    approval: { object: (a) => a.name, op: 'delete' },
+    transport: { mode: 'resolve', type: (a) => a.type, name: (a) => a.name, grantMismatch: false },
+    // Best-effort: the object may be a shell with no readable source.
+    snapshot: { kind: 'source', hard: false, type: (a) => a.type, name: (a) => a.name },
+    // Rule 7 — delete is irreversible-ish.
+    safetyConfirm: (a, transport) => ({
+        rule: 'RULE_7_SNAPSHOT_BEFORE_WRITE',
+        op: 'delete_object',
+        object: { type: a.type, name: a.name },
+        what_will_happen: 'Deletes object from SAP; snapshot is taken first; recovery via sap_snapshot_read + sap_set_source (LLM composes the rollback).',
+        rollback_available: true,
+        transport,
+        args: { ...a },
+    }),
+    walArgs: (a) => ({ name: a.name, type: a.type }),
+    // Same return semantics as setSource — RETURNS rather than throws on HTTP 4xx.
+    call: (a, ctx, pre) => ctx.adt.deleteObject(a.type, a.name, pre.transport),
+    errorCode: 'delete_failed',
+    landed: (r) => r.error || (r.status !== undefined && r.status >= 400)
+        ? { ok: false, detail: r.error ?? `Delete returned HTTP ${r.status} but did not throw`, extra: { status: r.status } }
+        : { ok: true },
+    audit: { method: 'deleteObject', type: (a) => a.type, name: (a) => a.name },
+    verify: { syntax: false, activation: false, deletedCheck: true },
+    envelope: (_a, _r, pre) => {
+        const stillExists = pre.extra['still_exists'];
         return {
-            content: JSON.stringify({
-                updated: true,
-                syntax_ok: syntax.ok,
-                errors: syntax.errors,
-                warnings: syntax.warnings,
-                ...activatedByWrite(writeActivation),
-                ...(resolved.owning ? { transport_used: resolved.owning, transport_note: resolved.note } : {}),
-                next_step: nextStepAfterWrite(syntax.ok, writeActivation),
-            }),
+            deleted: !stillExists,
+            still_exists: stillExists,
+            ...(pre.owning ? { transport_used: pre.owning, transport_note: pre.note } : {}),
         };
     },
-});
-// ── sap_delete_object ────────────────────────────────────────────────────────
-//
-// Signature: deleteObject(type, name, transport?) → { status: number; error?: string }
-// AdtClient auto-snapshots before delete (Rule 7 built-in), but we also call
-// autoSnapshot here for belt-and-suspenders consistency with the CLI gate model.
+};
 registerTool({
     name: 'sap_delete_object',
     requires: byObjectType,
@@ -586,113 +273,116 @@ registerTool({
         },
         required: ['name', 'type', 'approval_id'],
     },
-    handler: async (args, ctx) => {
-        // ── Gate 1: Approval ────────────────────────────────────────────────────
-        const verify = await verifyAndSpendApprovalId(args.approval_id, args.name, 'delete');
-        if (!verify.ok) {
-            return {
-                content: JSON.stringify({ error: ERR.APPROVAL_INVALID, reason: verify.reason }),
-                is_error: true,
-            };
-        }
-        const toolUseId = ctx.toolUseId ?? crypto.randomUUID();
-        const startedAt = Date.now();
-        // ── Rule 9 conflict warning ──────────────────────────────────────────────
-        // Emit a warning if the LLM passed an explicit transport that differs from
-        // the session current-transport. Prefer LLM intent (explicit caller); this
-        // is informational only and does NOT block the operation.
-        {
-            const sessionTransport = ctx.currentTransport?.get() ?? null;
-            if (args.transport && sessionTransport && args.transport !== sessionTransport) {
-                ctx.chunkEmitter?.emit('warn', `LLM passed transport=${args.transport} but session current-transport=${sessionTransport}`);
-            }
-        }
-        // ── Rule 9 owning-transport check (D15/D20) ──────────────────────────────
-        const resolved = await resolveWriteTransport(ctx, args.type, args.name, args.transport);
-        // ── Gate 2: Snapshot (Rule 7) — best-effort, object may not have source ──
-        let snapOutcome;
-        try {
-            snapOutcome = await autoSnapshot(args.name, args.type, ctx.adt);
-        }
-        catch {
-            // Silently ignore — object may be a shell with no readable source.
-        }
-        emitSnapshotNotice(ctx, snapOutcome, args.type, args.name);
-        // ── Gate 3: Safety confirmation (Rule 7 — delete is irreversible-ish) ────
-        if (isSafetyConfirmEnabled()) {
-            const r = await presentSafetyConfirmation({
-                rule: 'RULE_7_SNAPSHOT_BEFORE_WRITE',
-                op: 'delete_object',
-                object: { type: args.type, name: args.name },
-                what_will_happen: 'Deletes object from SAP; snapshot is taken first; recovery via sap_snapshot_read + sap_set_source (LLM composes the rollback).',
-                rollback_available: true,
-                transport: resolved.transport ?? ctx.currentTransport?.get() ?? '',
-                args: { ...args },
-            });
-            if (!r.confirmed) {
-                return {
-                    content: JSON.stringify({ error: 'cancelled_by_user', reason: r.reason }),
-                    is_error: true,
-                };
-            }
-        }
-        // ── WAL: record pending entry ────────────────────────────────────────────
-        await appendPending(ctx.session, {
-            tool_use_id: toolUseId,
-            tool: 'sap_delete_object',
-            args: { name: args.name, type: args.type },
-            started_at: new Date().toISOString(),
-        });
-        // ── Delete ───────────────────────────────────────────────────────────────
-        // deleteObject(type, name, transport?) → { status: number; error?: string }.
-        // Same return semantics as setSource — RETURNS rather than throws on HTTP
-        // 4xx. Must check status / error on the return value.
-        let deleteResult;
+    handler: writeToolHandler(DELETE_OBJECT_SPEC),
+});
+const isDevcCreate = (a) => String(a.type ?? '').toUpperCase().split('/')[0].trim() === 'DEVC';
+const devcTransportCreated = (pre) => pre.extra['devc_transport_created'];
+const CREATE_OBJECT_SPEC = {
+    tool: 'sap_create_object',
+    // 2026-10-04 — a plan-grant id holds the write to its claims (type, package, transport).
+    approval: {
+        object: (a) => a.name, op: 'create',
+        claims: (a, ctx) => ({ type: a.type, package: a.package, transport: a.transport ?? ctx.currentTransport?.get() ?? null }),
+    },
+    transport: { mode: 'three-tier' },
+    snapshot: { kind: 'none', reason: 'a new object has no prior source' },
+    // 1.1.31: does the chosen request fit the package? (see transport-fit-check.ts)
+    // A package create decides its own transport in the walGate (§10a), so only objects.
+    preGate: async (a, ctx, pre) => {
+        if (isDevcCreate(a))
+            return { ok: true };
+        const fit = await checkTransportFit(ctx.adt, { type: a.type, name: a.name, pkg: a.package, transport: pre.transport });
+        return fit.ok ? { ok: true } : { error: fit.refusal };
+    },
+    walArgs: (a) => ({ name: a.name, type: a.type, package: a.package }),
+    // §10a: a new package and its first transport, under this ONE approval.
+    walGate: async (a, ctx, pre) => {
+        if (!isDevcCreate(a))
+            return { ok: true };
+        let flow;
         try {
-            deleteResult = await ctx.adt.deleteObject(args.type, args.name, resolved.transport);
+            flow = await prepareNewPackage(a, ctx);
         }
         catch (err) {
-            const errStr = String(err);
-            await finalizeToolCall(ctx.session, toolUseId, errStr, true, Date.now() - startedAt);
-            return {
-                content: JSON.stringify({ error: 'delete_failed', detail: errStr }),
-                is_error: true,
-            };
+            // A throw (network, auth, …) must still close the pending entry and
+            // reach the person in plain words, never as a raw exception.
+            const msg = err instanceof Error ? err.message : String(err);
+            const answered = typeof err?.status === 'number';
+            const message = answered
+                ? `SAP refused to create the transport: ${msg}`
+                : `Could not reach SAP to create the transport: ${msg}`;
+            return { error: { error: 'transport_create_failed', message, next: 'Next: check the connection to SAP and try again.' }, log: message };
+        }
+        if ('refused' in flow)
+            return { error: flow.refused, log: flow.refused.message };
+        pre.transport = flow.corrNr;
+        if (flow.created) {
+            // Same auto-attach as sap_transport_create: later creates in the new
+            // package pick this request up through the 3-tier fallback.
+            setCurrentTransport(flow.created);
+            markTransportCreatedThisSession(flow.created);
         }
-        if (deleteResult.error || (deleteResult.status !== undefined && deleteResult.status >= 400)) {
-            const detail = deleteResult.error ?? `Delete returned HTTP ${deleteResult.status} but did not throw`;
-            await finalizeToolCall(ctx.session, toolUseId, detail, true, Date.now() - startedAt);
+        return {
+            ok: true,
+            extra: {
+                devc_transport_created: flow.created,
+                devc_extras: {
+                    softwareComponent: a.softwareComponent,
+                    transportLayer: flow.layer,
+                    applicationComponent: a.applicationComponent,
+                    superPackage: a.superPackage ? String(a.superPackage).toUpperCase() : undefined,
+                    responsible: a.responsible,
+                },
+            },
+        };
+    },
+    // createObject(objtype, name, packageName, description, transport?, extras?)
+    call: (a, ctx, pre) => ctx.adt.createObject(a.type, a.name, a.package, a.description, pre.transport, {
+        serviceDefinition: a.serviceDefinition,
+        bindingType: a.bindingType,
+        bindingVersion: a.bindingVersion,
+        ...(pre.extra['devc_extras'] ?? {}),
+        // Review fix round 1, I-1: a sap_lock handle lives in the stateful
+        // session; sap-client ends that session before a create unless told.
+        keepSession: hasManualLocks(),
+    }),
+    onThrow: (err, _a, pre) => ({ error: 'create_failed', detail: String(err), ...orphanRequest(devcTransportCreated(pre)) }),
+    errorCode: 'create_failed',
+    landed: (r, pre) => r.status === 'created'
+        ? { ok: true }
+        : { ok: false, detail: r.error, log: JSON.stringify(r), extra: orphanRequest(devcTransportCreated(pre)) },
+    audit: { method: 'createObject', type: (a) => a.type, name: (a) => a.name },
+    verify: { syntax: false, activation: false },
+    walResult: (_a, r) => r,
+    envelope: (a, r, pre) => {
+        if (isDevcCreate(a)) {
+            const pkgName = r.objectName || String(a.name).toUpperCase();
+            const created = devcTransportCreated(pre);
             return {
-                content: JSON.stringify({
-                    error: 'delete_failed',
-                    detail,
-                    status: deleteResult.status,
-                }),
-                is_error: true,
+                created: true,
+                object: pkgName,
+                type: 'DEVC',
+                ...(pre.transport ? { transport: pre.transport } : {}),
+                ...(created ? { transport_created: true } : {}),
+                message: pre.transport
+                    ? `Created package ${pkgName} on request ${pre.transport}.`
+                    : `Created package ${pkgName} (no transport needed).`,
+                next_step: 'create_objects_in_the_package_on_this_transport',
             };
         }
-        await auditLog('deleteObject', args.type, args.name, 'success', Date.now() - startedAt);
-        noteWriteTransport(resolved.transport); // F-L2-1 statusline wire
-        // ── Post-check: object should no longer exist ────────────────────────────
-        const stillExists = await ctx.adt.objectStructure(args.type, args.name)
-            .then(() => true)
-            .catch(() => false);
-        await finalizeToolCall(ctx.session, toolUseId, JSON.stringify({ deleted: !stillExists }), false, Date.now() - startedAt);
         return {
-            content: JSON.stringify({
-                deleted: !stillExists,
-                still_exists: stillExists,
-                ...(resolved.owning ? { transport_used: resolved.owning, transport_note: resolved.note } : {}),
-            }),
+            created: true,
+            object: r.objectName,
+            type: r.objectType,
+            package: r.packageName,
+            // A message class has no source and is never activated: its messages
+            // go in through sap_message_maintain (bug 3, 2026-10-12).
+            next_step: String(r.objectType ?? '').toUpperCase() === 'MSAG'
+                ? 'add_messages_via_sap_message_maintain (a message class has no source and no activation)'
+                : 'write_source_via_sap_set_source_then_activate',
         };
     },
-});
-// ── sap_create_object ────────────────────────────────────────────────────────
-//
-// Signature: createObject(objtype, name, packageName, description, transport?, extras?)
-//   → Promise<CreateResult>
-// NOTE: arg order differs from the plan snippet — packageName comes before description.
-// No snapshot needed: new object has no prior source.
+};
 registerTool({
     name: 'sap_create_object',
     requires: byObjectType,
@@ -728,162 +418,10 @@ registerTool({
             applicationComponent: { type: 'string', description: 'DEVC ONLY (optional): application component, e.g. FI-AR.' },
             superPackage: { type: 'string', description: 'DEVC ONLY (optional): parent package.' },
             responsible: { type: 'string', description: 'DEVC ONLY (optional): responsible user. Default: the logged-on user (upper case).' },
-        },
-        required: ['name', 'type', 'package', 'description', 'approval_id'],
-    },
-    handler: async (args, ctx) => {
-        // ── Gate 1: Approval ────────────────────────────────────────────────────
-        const verify = await verifyAndSpendApprovalId(args.approval_id, args.name, 'create');
-        if (!verify.ok) {
-            return {
-                content: JSON.stringify({ error: ERR.APPROVAL_INVALID, reason: verify.reason }),
-                is_error: true,
-            };
-        }
-        // 2026-10-04 — a plan-grant id holds the write to its claims (type, package, transport).
-        {
-            const claim = grantClaimMismatch(verify.payload, { type: args.type, package: args.package, transport: args.transport ?? ctx.currentTransport?.get() ?? null });
-            if (claim)
-                return { content: JSON.stringify({ error: ERR.APPROVAL_INVALID, reason: claim }), is_error: true };
-        }
-        const toolUseId = ctx.toolUseId ?? crypto.randomUUID();
-        const startedAt = Date.now();
-        // No snapshot — new object has no prior source.
-        // ── Rule 9 conflict warning + 3-tier transport fallback ──────────────────
-        // Emit a warning if the LLM passed an explicit transport that differs from
-        // the session current-transport. Prefer LLM intent (explicit caller); this
-        // is informational only and does NOT block the operation.
-        {
-            const sessionTransport = ctx.currentTransport?.get() ?? null;
-            if (args.transport && sessionTransport && args.transport !== sessionTransport) {
-                ctx.chunkEmitter?.emit('warn', `LLM passed transport=${args.transport} but session current-transport=${sessionTransport}`);
-            }
-        }
-        // 3-tier fallback: explicit arg → session current-transport → undefined
-        let effectiveTransport = args.transport ?? ctx.currentTransport?.get() ?? undefined;
-        // ── 1.1.31: does the chosen request fit the package? (see transport-fit-check.ts)
-        // A package create decides its own transport below (§10a), so only objects.
-        const isDevc = String(args.type ?? '').toUpperCase().split('/')[0].trim() === 'DEVC';
-        if (!isDevc) {
-            const fit = await checkTransportFit(ctx.adt, {
-                type: args.type, name: args.name, pkg: args.package, transport: effectiveTransport,
-            });
-            if (!fit.ok)
-                return { content: JSON.stringify(fit.refusal), is_error: true };
-        }
-        // ── WAL: record pending entry ────────────────────────────────────────────
-        await appendPending(ctx.session, {
-            tool_use_id: toolUseId,
-            tool: 'sap_create_object',
-            args: { name: args.name, type: args.type, package: args.package },
-            started_at: new Date().toISOString(),
-        });
-        // ── §10a: a new package and its first transport, under this ONE approval ─
-        let devcExtras = {};
-        let devcTransportCreated;
-        if (isDevc) {
-            let flow;
-            try {
-                flow = await prepareNewPackage(args, ctx);
-            }
-            catch (err) {
-                // A throw (network, auth, …) must still close the pending entry and
-                // reach the person in plain words, never as a raw exception.
-                const msg = err instanceof Error ? err.message : String(err);
-                const answered = typeof err?.status === 'number';
-                const message = answered
-                    ? `SAP refused to create the transport: ${msg}`
-                    : `Could not reach SAP to create the transport: ${msg}`;
-                await finalizeToolCall(ctx.session, toolUseId, message, true, Date.now() - startedAt);
-                return {
-                    content: JSON.stringify({ error: 'transport_create_failed', message, next: 'Next: check the connection to SAP and try again.' }),
-                    is_error: true,
-                };
-            }
-            if ('refused' in flow) {
-                await finalizeToolCall(ctx.session, toolUseId, flow.refused.message, true, Date.now() - startedAt);
-                return { content: JSON.stringify(flow.refused), is_error: true };
-            }
-            effectiveTransport = flow.corrNr;
-            devcTransportCreated = flow.created;
-            if (flow.created) {
-                // Same auto-attach as sap_transport_create: later creates in the new
-                // package pick this request up through the 3-tier fallback.
-                setCurrentTransport(flow.created);
-                markTransportCreatedThisSession(flow.created);
-            }
-            devcExtras = {
-                softwareComponent: args.softwareComponent,
-                transportLayer: flow.layer,
-                applicationComponent: args.applicationComponent,
-                superPackage: args.superPackage ? String(args.superPackage).toUpperCase() : undefined,
-                responsible: args.responsible,
-            };
-        }
-        // ── Create ───────────────────────────────────────────────────────────────
-        // createObject(objtype, name, packageName, description, transport?, extras?)
-        let result;
-        try {
-            result = await ctx.adt.createObject(args.type, args.name, args.package, args.description, effectiveTransport, {
-                serviceDefinition: args.serviceDefinition,
-                bindingType: args.bindingType,
-                bindingVersion: args.bindingVersion,
-                ...devcExtras,
-                // Review fix round 1, I-1: a sap_lock handle lives in the stateful
-                // session; sap-client ends that session before a create unless told.
-                keepSession: hasManualLocks(),
-            });
-            await auditLog('createObject', args.type, args.name, 'success', Date.now() - startedAt);
-        }
-        catch (err) {
-            const errStr = String(err);
-            await finalizeToolCall(ctx.session, toolUseId, errStr, true, Date.now() - startedAt);
-            return {
-                content: JSON.stringify({ error: 'create_failed', detail: errStr, ...orphanRequest(devcTransportCreated) }),
-                is_error: true,
-            };
-        }
-        if (result.status !== 'created') {
-            await finalizeToolCall(ctx.session, toolUseId, JSON.stringify(result), true, Date.now() - startedAt);
-            return {
-                content: JSON.stringify({ error: 'create_failed', detail: result.error, ...orphanRequest(devcTransportCreated) }),
-                is_error: true,
-            };
-        }
-        // F-L2-1 statusline wire. This path never reaches resolveWriteTransport —
-        // the 3-tier effectiveTransport above is what SAP stamped.
-        noteWriteTransport(effectiveTransport);
-        await finalizeToolCall(ctx.session, toolUseId, JSON.stringify(result), false, Date.now() - startedAt);
-        if (isDevc) {
-            const pkgName = result.objectName || String(args.name).toUpperCase();
-            return {
-                content: JSON.stringify({
-                    created: true,
-                    object: pkgName,
-                    type: 'DEVC',
-                    ...(effectiveTransport ? { transport: effectiveTransport } : {}),
-                    ...(devcTransportCreated ? { transport_created: true } : {}),
-                    message: effectiveTransport
-                        ? `Created package ${pkgName} on request ${effectiveTransport}.`
-                        : `Created package ${pkgName} (no transport needed).`,
-                    next_step: 'create_objects_in_the_package_on_this_transport',
-                }),
-            };
-        }
-        return {
-            content: JSON.stringify({
-                created: true,
-                object: result.objectName,
-                type: result.objectType,
-                package: result.packageName,
-                // A message class has no source and is never activated: its messages
-                // go in through sap_message_maintain (bug 3, 2026-10-12).
-                next_step: String(result.objectType ?? '').toUpperCase() === 'MSAG'
-                    ? 'add_messages_via_sap_message_maintain (a message class has no source and no activation)'
-                    : 'write_source_via_sap_set_source_then_activate',
-            }),
-        };
+        },
+        required: ['name', 'type', 'package', 'description', 'approval_id'],
     },
+    handler: writeToolHandler(CREATE_OBJECT_SPEC),
 });
 /**
  * §10a — when the package create fails after the flow already made a request,
@@ -969,16 +507,54 @@ async function prepareNewPackage(args, ctx) {
         return { refused: reusedRequestRefusal(tr) };
     return { corrNr: tr.transportNumber, layer, created: tr.transportNumber };
 }
-// ── sap_set_class_include ─────────────────────────────────────────────────────
-//
-// Signature: setClassInclude(className, includeType, source, transport?)
-//   → Promise<ClassIncludeResult>
-// Writes a class local-include source (CCDEF/CCIMP/CCMAC/test classes). This is
-// how RAP behaviour-pool handlers (which live in CCIMP / locals_imp) get landed.
-// AdtClient locks the CLASS object, tries a ladder of PUT URL/content-type
-// variants (first 2xx wins), and always unlocks. The Rule-7 snapshot is of the
-// INCLUDE itself (autoSnapshotClassInclude). It is non-blocking — a fresh
-// class's include may not be readable yet — but a failed one warns loudly.
+const CLASS_INCLUDE_SPEC = {
+    tool: 'sap_set_class_include',
+    approval: {
+        object: (a) => a.className,
+        op: 'modify',
+        claims: (a, ctx) => ({ type: 'CLAS', transport: a.transport ?? ctx.currentTransport?.get() ?? null }),
+    },
+    transport: { mode: 'fallback-resolve', type: () => 'CLAS', name: (a) => a.className, grantMismatch: true },
+    snapshot: { kind: 'include', className: (a) => a.className, includeType: (a) => a.includeType },
+    walArgs: (a) => ({ className: a.className, includeType: a.includeType }),
+    // setClassInclude THROWS only when it cannot acquire the class lock; for the
+    // all-variants-failed case it RETURNS { written:false, ... } (landed).
+    call: (a, ctx, pre) => ctx.adt.setClassInclude(a.className, a.includeType, a.source, pre.transport),
+    errorCode: 'class_include_write_failed',
+    // D14: `error` carries SAP's T100 diagnosis verbatim when a variant hit a
+    // CTS/lock conflict — passed through unaltered, plus the owning transport so
+    // the model can retry correctly instead of declaring the change manual-only.
+    landed: (r) => (r.written
+        ? { ok: true }
+        : {
+            ok: false,
+            detail: r.error ?? `All PUT variants failed (last HTTP ${r.httpStatus})`,
+            log: JSON.stringify(r),
+            extra: {
+                http_status: r.httpStatus,
+                ...(r.lockedInTransport ? {
+                    locked_in_transport: r.lockedInTransport,
+                    recovery: `Retry this exact write with transport=${r.lockedInTransport} — that request already owns the object.`,
+                } : {}),
+                attempts: r.attempts,
+            },
+        }),
+    audit: { method: 'setClassInclude', type: () => 'CLAS', name: (a) => a.className, detail: (a) => `include=${a.includeType}` },
+    verify: { syntax: false, activation: false },
+    walResult: (_a, r) => ({ written: true, variant: r.variantUsed }),
+    chain: (a, pre) => ({
+        ...snapshotChainState(pre.snapshot),
+        written: true,
+        syntax: 'not_checked',
+        card: { object: a.className, what: `include ${a.includeType}`, transport: pre.transport },
+    }),
+    envelope: (_a, r, pre) => ({
+        written: true,
+        variant: r.variantUsed,
+        ...(pre.owning ? { transport_used: pre.owning, transport_note: pre.note } : {}),
+        next_step: 'activate_the_class',
+    }),
+};
 registerTool({
     name: 'sap_set_class_include',
     description: 'Write a class local-include source (CCDEF locals_def, CCIMP locals_imp, '
@@ -1003,130 +579,78 @@ registerTool({
         },
         required: ['className', 'includeType', 'source', 'approval_id'],
     },
-    handler: async (args, ctx) => {
-        // ── Gate 1: Approval ────────────────────────────────────────────────────
-        const verify = await verifyAndSpendApprovalId(args.approval_id, args.className, 'modify');
-        if (!verify.ok) {
-            return {
-                content: JSON.stringify({ error: ERR.APPROVAL_INVALID, reason: verify.reason }),
-                is_error: true,
-            };
-        }
+    handler: writeToolHandler(CLASS_INCLUDE_SPEC),
+});
+function ddicCreateSpec(tool, type, auditType, create) {
+    return {
+        tool,
         // 2026-10-04 — a plan-grant id holds the write to its claims (type, package, transport).
-        {
-            const claim = grantClaimMismatch(verify.payload, { type: 'CLAS', transport: args.transport ?? ctx.currentTransport?.get() ?? null });
-            if (claim)
-                return { content: JSON.stringify({ error: ERR.APPROVAL_INVALID, reason: claim }), is_error: true };
-        }
-        const toolUseId = ctx.toolUseId ?? crypto.randomUUID();
-        const startedAt = Date.now();
-        // ── Rule 9 conflict warning + 3-tier transport fallback ──────────────────
-        {
-            const sessionTransport = ctx.currentTransport?.get() ?? null;
-            if (args.transport && sessionTransport && args.transport !== sessionTransport) {
-                ctx.chunkEmitter?.emit('warn', `LLM passed transport=${args.transport} but session current-transport=${sessionTransport}`);
+        approval: {
+            object: (a) => a.name, op: 'create',
+            claims: (a, ctx) => ({ type, package: a.package, transport: a.transport ?? ctx.currentTransport?.get() ?? null }),
+        },
+        transport: { mode: 'three-tier' },
+        snapshot: { kind: 'none', reason: 'a new object has no prior source' },
+        walArgs: (a) => ({ name: a.name, type, package: a.package }),
+        call: async (a, ctx, pre) => {
+            const r = await create(a, ctx, pre.transport);
+            // F-L2-1 statusline wire, recorded on CREATED, not on active: a
+            // create-succeeded / activation-failed run must still show which request
+            // holds the object. The pipeline notes a landed create itself; this one
+            // is a miss there.
+            if (r.created && !r.active)
+                noteWriteTransport(pre.transport);
+            return r;
+        },
+        errorCode: 'create_failed',
+        landed: (r) => {
+            if (!r.created)
+                return { ok: false, detail: r.error, log: JSON.stringify(r) };
+            // Rule 10: created but did not activate — surface as an error.
+            // Final review I-2: the object now exists in SAP, so the audit log says so.
+            if (!r.active) {
+                return {
+                    ok: false, detail: r.error, log: JSON.stringify(r), body: { error: 'activation_failed', object: r.name, detail: r.error },
+                    audit: { status: 'error', reason: `created in SAP but not activated${r.error ? `: ${r.error}` : ''}` },
+                };
             }
-        }
-        const effectiveTransport = args.transport ?? ctx.currentTransport?.get() ?? undefined;
-        // ── Rule 9 owning-transport check (D15/D20) ──────────────────────────────
-        // The CCIMP piece (LIMU CINC) is exactly the kind of object that sits
-        // locked in a request from earlier work — battery S1's 409 root cause.
-        const resolved = await resolveWriteTransport(ctx, 'CLAS', args.className, effectiveTransport);
-        // 2026-10-04 — a plan-grant id never writes into a transport other than the grant's.
-        if (grantOwningTransportMismatch(verify.payload, resolved.owning)) {
-            return {
-                content: JSON.stringify({ error: ERR.APPROVAL_INVALID, reason: 'transport_mismatch', detail: grantOwningTransportDetail(args.className, resolved.owning) }),
-                is_error: true,
-            };
-        }
-        // ── Gate 2: Snapshot (Rule 7) — of the INCLUDE being overwritten ─────────
-        // Not the class main source: for a behaviour pool that is an empty shell and
-        // the change lives in CCIMP (2026-09-21 — the old main-source snapshot left
-        // the change with no restore point, and rewind "restored" the wrong thing).
-        // Still non-blocking (a fresh class's include may not be readable yet), but
-        // a missing restore point is now said out loud instead of swallowed.
-        let snapOutcome;
-        try {
-            snapOutcome = await autoSnapshotClassInclude(args.className, args.includeType, ctx.adt);
-        }
-        catch (err) {
-            snapOutcome = { taken: false, reason: 'source_read_failed', detail: String(err) };
-        }
-        emitSnapshotNotice(ctx, snapOutcome, includeSnapshotType(args.includeType), args.className);
-        if (snapOutcome?.reason === 'source_read_failed') {
-            ctx.chunkEmitter?.emit('warn', `CLAS ${args.className} ${args.includeType}: could not snapshot the include before writing `
-                + `(${snapOutcome.detail ?? 'read failed'}) — this write has NO restore point; rewind cannot undo it`);
-        }
-        // ── WAL: record pending entry ────────────────────────────────────────────
-        await appendPending(ctx.session, {
-            tool_use_id: toolUseId,
-            tool: 'sap_set_class_include',
-            args: { className: args.className, includeType: args.includeType },
-            started_at: new Date().toISOString(),
-        });
-        // ── Write ────────────────────────────────────────────────────────────────
-        // setClassInclude THROWS only when it cannot acquire the class lock;
-        // for the all-variants-failed case it RETURNS { written:false, ... }.
-        // Both paths must surface as an error envelope.
-        let result;
-        try {
-            result = await ctx.adt.setClassInclude(args.className, args.includeType, args.source, resolved.transport);
-        }
-        catch (err) {
-            const errStr = String(err);
-            await finalizeToolCall(ctx.session, toolUseId, errStr, true, Date.now() - startedAt);
-            return {
-                content: JSON.stringify({ error: 'class_include_write_failed', detail: errStr }),
-                is_error: true,
-            };
-        }
-        if (!result.written) {
-            // D14: `result.error` now carries SAP's T100 diagnosis verbatim when a
-            // variant hit a CTS/lock conflict — pass it through unaltered, plus the
-            // structured owning transport so the model can retry correctly instead
-            // of declaring the change manual-only.
-            const detail = result.error ?? `All PUT variants failed (last HTTP ${result.httpStatus})`;
-            await finalizeToolCall(ctx.session, toolUseId, JSON.stringify(result), true, Date.now() - startedAt);
-            return {
-                content: JSON.stringify({
-                    error: 'class_include_write_failed',
-                    detail,
-                    http_status: result.httpStatus,
-                    ...(result.lockedInTransport ? {
-                        locked_in_transport: result.lockedInTransport,
-                        recovery: `Retry this exact write with transport=${result.lockedInTransport} — that request already owns the object.`,
-                    } : {}),
-                    attempts: result.attempts,
-                }),
-                is_error: true,
-            };
-        }
-        await auditLog('setClassInclude', 'CLAS', args.className, 'success', Date.now() - startedAt, `include=${args.includeType}`);
-        noteWriteTransport(resolved.transport); // F-L2-1 statusline wire
-        await finalizeToolCall(ctx.session, toolUseId, JSON.stringify({ written: true, variant: result.variantUsed }), false, Date.now() - startedAt);
-        // Tour slide-7 chain. Honest states: includes have no standalone syntax
-        // gate (checked at activation), so ③ renders as deferred, never faked.
-        emitWriteChain(ctx, {
-            ...snapshotChainState(snapOutcome),
-            written: true,
-            syntax: 'not_checked',
-            card: { object: args.className, what: `include ${args.includeType}`, transport: resolved.transport },
-        });
-        return {
-            content: JSON.stringify({
-                written: true,
-                variant: result.variantUsed,
-                ...(resolved.owning ? { transport_used: resolved.owning, transport_note: resolved.note } : {}),
-                next_step: 'activate_the_class',
-            }),
-        };
-    },
-});
-// ── sap_create_domain ────────────────────────────────────────────────────────
-//
-// Signature: createDomain(spec, transport?) → Promise<DdicCreateResult>
-// AdtClient creates → activates → verifies in one call (Rule 10 internal).
-// No snapshot needed: new object has no prior source.
+            return { ok: true };
+        },
+        audit: { method: 'createObject', type: () => auditType, name: (a) => a.name },
+        verify: { syntax: false, activation: false },
+        walResult: (_a, r) => r,
+        envelope: (_a, r) => ({
+            created: true,
+            active: true,
+            object: r.name,
+            type: r.type,
+            next_step: 'use_in_table_field',
+        }),
+    };
+}
+const DOMAIN_HANDLER = writeToolHandler(ddicCreateSpec('sap_create_domain', 'DOMA', 'DOMA/DD', (args, ctx, transport) => {
+    // Build spec (omit undefined optionals).
+    const spec = {
+        name: args.name,
+        description: args.description,
+        package: args.package,
+        dataType: args.dataType,
+        length: args.length,
+    };
+    if (args.decimals !== undefined)
+        spec.decimals = args.decimals;
+    if (args.outputLength !== undefined)
+        spec.outputLength = args.outputLength;
+    if (args.lowercase !== undefined)
+        spec.lowercase = args.lowercase;
+    if (args.signExists !== undefined)
+        spec.signExists = args.signExists;
+    if (args.valueTable !== undefined)
+        spec.valueTable = args.valueTable;
+    if (args.fixedValues !== undefined)
+        spec.fixedValues = args.fixedValues;
+    return ctx.adt.createDomain(spec, transport);
+}));
 registerTool({
     name: 'sap_create_domain',
     requires: 'ddic.domains',
@@ -1165,110 +689,27 @@ registerTool({
         },
         required: ['name', 'description', 'package', 'dataType', 'length', 'approval_id'],
     },
-    handler: async (args, ctx) => {
-        // ── Gate 1: Approval ────────────────────────────────────────────────────
-        const verify = await verifyAndSpendApprovalId(args.approval_id, args.name, 'create');
-        if (!verify.ok) {
-            return {
-                content: JSON.stringify({ error: ERR.APPROVAL_INVALID, reason: verify.reason }),
-                is_error: true,
-            };
-        }
-        // 2026-10-04 — a plan-grant id holds the write to its claims (type, package, transport).
-        {
-            const claim = grantClaimMismatch(verify.payload, { type: 'DOMA', package: args.package, transport: args.transport ?? ctx.currentTransport?.get() ?? null });
-            if (claim)
-                return { content: JSON.stringify({ error: ERR.APPROVAL_INVALID, reason: claim }), is_error: true };
-        }
-        const toolUseId = ctx.toolUseId ?? crypto.randomUUID();
-        const startedAt = Date.now();
-        // No snapshot — new object has no prior source.
-        // ── Rule 9 conflict warning + 3-tier transport fallback ──────────────────
-        {
-            const sessionTransport = ctx.currentTransport?.get() ?? null;
-            if (args.transport && sessionTransport && args.transport !== sessionTransport) {
-                ctx.chunkEmitter?.emit('warn', `LLM passed transport=${args.transport} but session current-transport=${sessionTransport}`);
-            }
-        }
-        const effectiveTransport = args.transport ?? ctx.currentTransport?.get() ?? undefined;
-        // ── WAL: record pending entry ────────────────────────────────────────────
-        await appendPending(ctx.session, {
-            tool_use_id: toolUseId,
-            tool: 'sap_create_domain',
-            args: { name: args.name, type: 'DOMA', package: args.package },
-            started_at: new Date().toISOString(),
-        });
-        // ── Build spec (omit undefined optionals) ────────────────────────────────
-        const spec = {
-            name: args.name,
-            description: args.description,
-            package: args.package,
-            dataType: args.dataType,
-            length: args.length,
-        };
-        if (args.decimals !== undefined)
-            spec.decimals = args.decimals;
-        if (args.outputLength !== undefined)
-            spec.outputLength = args.outputLength;
-        if (args.lowercase !== undefined)
-            spec.lowercase = args.lowercase;
-        if (args.signExists !== undefined)
-            spec.signExists = args.signExists;
-        if (args.valueTable !== undefined)
-            spec.valueTable = args.valueTable;
-        if (args.fixedValues !== undefined)
-            spec.fixedValues = args.fixedValues;
-        // ── Create → activate → verify (AdtClient does all three) ────────────────
-        let result;
-        try {
-            result = await ctx.adt.createDomain(spec, effectiveTransport);
-            await auditLog('createObject', 'DOMA/DD', args.name, 'success', Date.now() - startedAt);
-        }
-        catch (err) {
-            const errStr = String(err);
-            await finalizeToolCall(ctx.session, toolUseId, errStr, true, Date.now() - startedAt);
-            return {
-                content: JSON.stringify({ error: 'create_failed', detail: errStr }),
-                is_error: true,
-            };
-        }
-        if (!result.created) {
-            await finalizeToolCall(ctx.session, toolUseId, JSON.stringify(result), true, Date.now() - startedAt);
-            return {
-                content: JSON.stringify({ error: 'create_failed', detail: result.error }),
-                is_error: true,
-            };
-        }
-        // F-L2-1 statusline wire. Recorded on CREATED, not on active: the object is
-        // already in effectiveTransport by then, so a create-succeeded /
-        // activation-failed run must still show which request holds it. DDIC creates
-        // bypass resolveWriteTransport — effectiveTransport is what SAP stamped.
-        noteWriteTransport(effectiveTransport);
-        if (!result.active) {
-            // Rule 10: created but did not activate — surface as an error.
-            await finalizeToolCall(ctx.session, toolUseId, JSON.stringify(result), true, Date.now() - startedAt);
-            return {
-                content: JSON.stringify({ error: 'activation_failed', object: result.name, detail: result.error }),
-                is_error: true,
-            };
-        }
-        await finalizeToolCall(ctx.session, toolUseId, JSON.stringify(result), false, Date.now() - startedAt);
-        return {
-            content: JSON.stringify({
-                created: true,
-                active: true,
-                object: result.name,
-                type: result.type,
-                next_step: 'use_in_table_field',
-            }),
-        };
-    },
+    handler: DOMAIN_HANDLER,
 });
-// ── sap_create_data_element ──────────────────────────────────────────────────
-//
-// Signature: createDataElement(spec, transport?) → Promise<DdicCreateResult>
-// AdtClient creates → activates → verifies in one call (Rule 10 internal).
-// No snapshot needed: new object has no prior source.
+const DATA_ELEMENT_HANDLER = writeToolHandler(ddicCreateSpec('sap_create_data_element', 'DTEL', 'DTEL/DE', (args, ctx, transport) => {
+    // Build spec (omit undefined optionals).
+    const spec = {
+        name: args.name,
+        description: args.description,
+        package: args.package,
+        domainName: args.domainName,
+        dataType: args.dataType,
+        length: args.length,
+        labels: args.labels,
+    };
+    if (args.decimals !== undefined)
+        spec.decimals = args.decimals;
+    if (args.searchHelp !== undefined)
+        spec.searchHelp = args.searchHelp;
+    if (args.searchHelpParameter !== undefined)
+        spec.searchHelpParameter = args.searchHelpParameter;
+    return ctx.adt.createDataElement(spec, transport);
+}));
 registerTool({
     name: 'sap_create_data_element',
     requires: 'ddic.dataelements',
@@ -1305,97 +746,7 @@ registerTool({
         },
         required: ['name', 'description', 'package', 'domainName', 'dataType', 'length', 'labels', 'approval_id'],
     },
-    handler: async (args, ctx) => {
-        // ── Gate 1: Approval ────────────────────────────────────────────────────
-        const verify = await verifyAndSpendApprovalId(args.approval_id, args.name, 'create');
-        if (!verify.ok) {
-            return {
-                content: JSON.stringify({ error: ERR.APPROVAL_INVALID, reason: verify.reason }),
-                is_error: true,
-            };
-        }
-        // 2026-10-04 — a plan-grant id holds the write to its claims (type, package, transport).
-        {
-            const claim = grantClaimMismatch(verify.payload, { type: 'DTEL', package: args.package, transport: args.transport ?? ctx.currentTransport?.get() ?? null });
-            if (claim)
-                return { content: JSON.stringify({ error: ERR.APPROVAL_INVALID, reason: claim }), is_error: true };
-        }
-        const toolUseId = ctx.toolUseId ?? crypto.randomUUID();
-        const startedAt = Date.now();
-        // No snapshot — new object has no prior source.
-        // ── Rule 9 conflict warning + 3-tier transport fallback ──────────────────
-        {
-            const sessionTransport = ctx.currentTransport?.get() ?? null;
-            if (args.transport && sessionTransport && args.transport !== sessionTransport) {
-                ctx.chunkEmitter?.emit('warn', `LLM passed transport=${args.transport} but session current-transport=${sessionTransport}`);
-            }
-        }
-        const effectiveTransport = args.transport ?? ctx.currentTransport?.get() ?? undefined;
-        // ── WAL: record pending entry ────────────────────────────────────────────
-        await appendPending(ctx.session, {
-            tool_use_id: toolUseId,
-            tool: 'sap_create_data_element',
-            args: { name: args.name, type: 'DTEL', package: args.package },
-            started_at: new Date().toISOString(),
-        });
-        // ── Build spec (omit undefined optionals) ────────────────────────────────
-        const spec = {
-            name: args.name,
-            description: args.description,
-            package: args.package,
-            domainName: args.domainName,
-            dataType: args.dataType,
-            length: args.length,
-            labels: args.labels,
-        };
-        if (args.decimals !== undefined)
-            spec.decimals = args.decimals;
-        if (args.searchHelp !== undefined)
-            spec.searchHelp = args.searchHelp;
-        if (args.searchHelpParameter !== undefined)
-            spec.searchHelpParameter = args.searchHelpParameter;
-        // ── Create → activate → verify (AdtClient does all three) ────────────────
-        let result;
-        try {
-            result = await ctx.adt.createDataElement(spec, effectiveTransport);
-            await auditLog('createObject', 'DTEL/DE', args.name, 'success', Date.now() - startedAt);
-        }
-        catch (err) {
-            const errStr = String(err);
-            await finalizeToolCall(ctx.session, toolUseId, errStr, true, Date.now() - startedAt);
-            return {
-                content: JSON.stringify({ error: 'create_failed', detail: errStr }),
-                is_error: true,
-            };
-        }
-        if (!result.created) {
-            await finalizeToolCall(ctx.session, toolUseId, JSON.stringify(result), true, Date.now() - startedAt);
-            return {
-                content: JSON.stringify({ error: 'create_failed', detail: result.error }),
-                is_error: true,
-            };
-        }
-        // F-L2-1 statusline wire — see the createDomain note above (created, not active).
-        noteWriteTransport(effectiveTransport);
-        if (!result.active) {
-            // Rule 10: created but did not activate — surface as an error.
-            await finalizeToolCall(ctx.session, toolUseId, JSON.stringify(result), true, Date.now() - startedAt);
-            return {
-                content: JSON.stringify({ error: 'activation_failed', object: result.name, detail: result.error }),
-                is_error: true,
-            };
-        }
-        await finalizeToolCall(ctx.session, toolUseId, JSON.stringify(result), false, Date.now() - startedAt);
-        return {
-            content: JSON.stringify({
-                created: true,
-                active: true,
-                object: result.name,
-                type: result.type,
-                next_step: 'use_in_table_field',
-            }),
-        };
-    },
+    handler: DATA_ELEMENT_HANDLER,
 });
 // ── sap_activate ─────────────────────────────────────────────────────────────
 //
@@ -1719,6 +1070,117 @@ function messageRowsProblem(rows) {
     }
     return null;
 }
+const msagThrowText = (err) => (err instanceof Error ? err.message : String(err));
+const msagName = (a) => String(a.messageClass ?? '').trim().toUpperCase();
+const msagRows = (a) => messageRowsFromArgs(a);
+const msagLockNote = (pre) => pre.extra['lock_note'];
+const MESSAGE_MAINTAIN_SPEC = {
+    tool: 'sap_message_maintain',
+    beforeApproval: (a, ctx) => {
+        // Input check — before the approval is spent.
+        const className = msagName(a);
+        const problem = !className
+            ? 'Give the message class name.'
+            : !MESSAGE_CLASS_NAME_RE.test(className)
+                ? `"${String(a.messageClass)}" is not a valid message class name (letters, digits and _ only, 20 characters at most).`
+                : messageRowsProblem(msagRows(a));
+        if (problem)
+            return { error: 'invalid_messages', detail: problem };
+        // Capability — before the approval is spent (review I-1; an old sap-client pin).
+        const adt = ctx.adt;
+        if (typeof adt.readMessageClass !== 'function' || typeof adt.maintainMessages !== 'function') {
+            return { error: 'message_maintain_unavailable', detail: 'This CSPeach build cannot write messages yet. Update CSPeach and try again.' };
+        }
+        return undefined;
+    },
+    approval: {
+        object: (a) => a.messageClass,
+        op: 'modify',
+        claims: (a, ctx) => ({ type: 'MSAG', transport: a.transport ?? ctx.currentTransport?.get() ?? null }),
+    },
+    transport: { mode: 'fallback-resolve', type: () => 'MSAG', name: msagName, grantMismatch: true },
+    snapshot: { kind: 'messages', name: msagName },
+    walArgs: (a) => ({ messageClass: msagName(a), messages: msagRows(a).map((r) => r.msgno) }),
+    // sap-client locks, PUTs, unlocks in a finally and reads back. A lock it may
+    // have left is said right after the call, on success and failure (review M-1).
+    call: async (a, ctx, pre) => {
+        const r = await ctx.adt.maintainMessages({
+            name: msagName(a),
+            messages: msagRows(a),
+            ...(pre.transport ? { transport: pre.transport } : {}),
+        });
+        const lockNote = lockWarning(msagName(a), r);
+        pre.extra['lock_note'] = lockNote;
+        if (lockNote)
+            ctx.chunkEmitter?.emit('warn', lockNote);
+        return r;
+    },
+    // One source for the thrown text: the envelope detail and the WAL log say the same (final review M-4).
+    onThrow: (err) => ({ error: 'message_maintain_failed', detail: msagThrowText(err) }),
+    throwLog: msagThrowText,
+    errorCode: 'message_maintain_failed',
+    // Success is SAP's read-back (`verified`), never HTTP 200.
+    landed: (r, pre) => {
+        if (r.verified)
+            return { ok: true };
+        const lockNote = msagLockNote(pre);
+        const detail = r.error ?? 'The messages could not be confirmed in SAP.';
+        return {
+            ok: false,
+            detail,
+            log: JSON.stringify(r),
+            body: {
+                error: 'message_maintain_failed',
+                ...(lockNote ? { lock_warning: lockNote } : {}),
+                detail,
+                missing: r.missing,
+                ...(r.httpStatus !== undefined ? { http_status: r.httpStatus } : {}),
+                ...(r.lockedInTransport ? {
+                    locked_in_transport: r.lockedInTransport,
+                    recovery: `Retry this exact call with transport=${r.lockedInTransport} — that request already owns the message class.`,
+                } : {}),
+            },
+        };
+    },
+    // Controller ruling (Task 12 review I-1.4): the call landed, nothing was
+    // written — WAL closed clean, NO audit row, is_error absent.
+    noWrite: (a, r) => (r.noChange
+        ? {
+            walResult: { unchanged: true },
+            envelope: {
+                written: false,
+                unchanged: true,
+                message_class: msagName(a),
+                changes: r.changes,
+                message: `Message class ${msagName(a)} already has these texts. Nothing was changed.`,
+            },
+        }
+        : undefined),
+    audit: {
+        method: 'maintainMessages', type: () => 'MSAG', name: msagName,
+        detail: (_a, r) => r.changes.map((c) => `${c.msgno}:${c.action}`).join(' '),
+    },
+    verify: { syntax: false, activation: false },
+    walResult: (_a, r) => ({ written: true, verified: true, changes: r.changes }),
+    after: (a, r, _pre, ctx) => {
+        const written = r.changes.filter((c) => c.action !== 'unchanged').map((c) => c.msgno);
+        ctx.chunkEmitter?.emit('info', `messages ✓ ${msagName(a)} ${written.join(' ')} (no activation needed)`);
+    },
+    envelope: (a, r, pre) => {
+        const className = msagName(a);
+        const lockNote = msagLockNote(pre);
+        const first = r.changes.filter((c) => c.action !== 'unchanged').map((c) => c.msgno)[0] ?? msagRows(a)[0].msgno;
+        return {
+            written: true,
+            verified: true,
+            message_class: className,
+            changes: r.changes,
+            ...(pre.owning ? { transport_used: pre.owning, transport_note: pre.note } : {}),
+            ...(lockNote ? { lock_warning: lockNote } : {}),
+            next_step: `Done — no activation needed. Raise these from code by number, e.g. MESSAGE e${first}(${className.toLowerCase()}) WITH …, or a T100 textid in an exception class. Never hard-code the texts.`,
+        };
+    },
+};
 registerTool({
     name: 'sap_message_maintain',
     requires: 'msag',
@@ -1754,169 +1216,7 @@ registerTool({
         },
         required: ['messageClass', 'approval_id'],
     },
-    handler: async (args, ctx) => {
-        const className = String(args.messageClass ?? '').trim().toUpperCase();
-        // ── Input check — before the approval is spent ──────────────────────────
-        const rows = messageRowsFromArgs(args);
-        const problem = !className
-            ? 'Give the message class name.'
-            : !MESSAGE_CLASS_NAME_RE.test(className)
-                ? `"${String(args.messageClass)}" is not a valid message class name (letters, digits and _ only, 20 characters at most).`
-                : messageRowsProblem(rows);
-        if (problem) {
-            return { content: JSON.stringify({ error: 'invalid_messages', detail: problem }), is_error: true };
-        }
-        // ── Capability — before the approval is spent (review I-1) ──────────────
-        const adt = ctx.adt;
-        if (typeof adt.readMessageClass !== 'function' || typeof adt.maintainMessages !== 'function') {
-            return {
-                content: JSON.stringify({
-                    error: 'message_maintain_unavailable',
-                    detail: 'This CSPeach build cannot write messages yet. Update CSPeach and try again.',
-                }),
-                is_error: true,
-            };
-        }
-        const msagClient = adt;
-        // ── Gate 1: Approval ────────────────────────────────────────────────────
-        const verify = await verifyAndSpendApprovalId(args.approval_id, args.messageClass, 'modify');
-        if (!verify.ok) {
-            return {
-                content: JSON.stringify({ error: ERR.APPROVAL_INVALID, reason: verify.reason }),
-                is_error: true,
-            };
-        }
-        // 2026-10-04 — a plan-grant id holds the write to its claims (type, package, transport).
-        {
-            const claim = grantClaimMismatch(verify.payload, { type: 'MSAG', transport: args.transport ?? ctx.currentTransport?.get() ?? null });
-            if (claim)
-                return { content: JSON.stringify({ error: ERR.APPROVAL_INVALID, reason: claim }), is_error: true };
-        }
-        const toolUseId = ctx.toolUseId ?? crypto.randomUUID();
-        const startedAt = Date.now();
-        // ── Rule 9 conflict warning + 3-tier transport fallback ──────────────────
-        {
-            const sessionTransport = ctx.currentTransport?.get() ?? null;
-            if (args.transport && sessionTransport && args.transport !== sessionTransport) {
-                ctx.chunkEmitter?.emit('warn', `LLM passed transport=${args.transport} but session current-transport=${sessionTransport}`);
-            }
-        }
-        const effectiveTransport = args.transport ?? ctx.currentTransport?.get() ?? undefined;
-        const resolved = await resolveWriteTransport(ctx, 'MSAG', className, effectiveTransport);
-        // 2026-10-04 — a plan-grant id never writes into a transport other than the grant's.
-        if (grantOwningTransportMismatch(verify.payload, resolved.owning)) {
-            return {
-                content: JSON.stringify({ error: ERR.APPROVAL_INVALID, reason: 'transport_mismatch', detail: grantOwningTransportDetail(className, resolved.owning) }),
-                is_error: true,
-            };
-        }
-        // ── Gate 2: Snapshot (Rule 7) — HARD gate, of the whole class ────────────
-        let snapOutcome;
-        try {
-            snapOutcome = await autoSnapshotMessageClass(className, msagClient);
-        }
-        catch (err) {
-            return {
-                content: JSON.stringify({ error: ERR.SNAPSHOT_FAILED, detail: String(err) }),
-                is_error: true,
-            };
-        }
-        if (snapOutcome.reason === 'object_not_found') {
-            return {
-                content: JSON.stringify({
-                    error: 'message_class_not_found',
-                    detail: `Message class ${className} does not exist. Create it first with sap_create_object type MSAG, then add the messages.`,
-                }),
-                is_error: true,
-            };
-        }
-        if (!snapOutcome.taken) {
-            return {
-                content: JSON.stringify({
-                    error: ERR.SNAPSHOT_FAILED,
-                    reason: snapOutcome.reason ?? 'source_read_failed',
-                    detail: snapOutcome.detail,
-                    recovery: 'The message class could not be read, so no snapshot was possible and nothing was written. If this is a connection or sign-in problem, fix it and try again.',
-                }),
-                is_error: true,
-            };
-        }
-        emitSnapshotNotice(ctx, snapOutcome, 'MSAG', className);
-        // ── WAL: record pending entry ────────────────────────────────────────────
-        await appendPending(ctx.session, {
-            tool_use_id: toolUseId,
-            tool: 'sap_message_maintain',
-            args: { messageClass: className, messages: rows.map((r) => r.msgno) },
-            started_at: new Date().toISOString(),
-        });
-        // ── Write (sap-client locks, PUTs, unlocks and reads back) ───────────────
-        let result;
-        try {
-            result = await msagClient.maintainMessages({
-                name: className,
-                messages: rows,
-                ...(resolved.transport ? { transport: resolved.transport } : {}),
-            });
-        }
-        catch (err) {
-            const detail = err instanceof Error ? err.message : String(err);
-            await finalizeToolCall(ctx.session, toolUseId, detail, true, Date.now() - startedAt);
-            return {
-                content: JSON.stringify({ error: 'message_maintain_failed', detail }),
-                is_error: true,
-            };
-        }
-        const lockNote = lockWarning(className, result);
-        if (lockNote)
-            ctx.chunkEmitter?.emit('warn', lockNote);
-        if (!result.verified) {
-            await finalizeToolCall(ctx.session, toolUseId, JSON.stringify(result), true, Date.now() - startedAt);
-            return {
-                content: JSON.stringify({
-                    error: 'message_maintain_failed',
-                    ...(lockNote ? { lock_warning: lockNote } : {}),
-                    detail: result.error ?? 'The messages could not be confirmed in SAP.',
-                    missing: result.missing,
-                    ...(result.httpStatus !== undefined ? { http_status: result.httpStatus } : {}),
-                    ...(result.lockedInTransport ? {
-                        locked_in_transport: result.lockedInTransport,
-                        recovery: `Retry this exact call with transport=${result.lockedInTransport} — that request already owns the message class.`,
-                    } : {}),
-                }),
-                is_error: true,
-            };
-        }
-        if (result.noChange) {
-            await finalizeToolCall(ctx.session, toolUseId, JSON.stringify({ unchanged: true }), false, Date.now() - startedAt);
-            return {
-                content: JSON.stringify({
-                    written: false,
-                    unchanged: true,
-                    message_class: className,
-                    changes: result.changes,
-                    message: `Message class ${className} already has these texts. Nothing was changed.`,
-                }),
-            };
-        }
-        // Audit only after SAP's read-back confirmed every message.
-        await auditLog('maintainMessages', 'MSAG', className, 'success', Date.now() - startedAt, result.changes.map((c) => `${c.msgno}:${c.action}`).join(' '));
-        noteWriteTransport(resolved.transport); // F-L2-1 statusline wire
-        await finalizeToolCall(ctx.session, toolUseId, JSON.stringify({ written: true, verified: true, changes: result.changes }), false, Date.now() - startedAt);
-        const written = result.changes.filter((c) => c.action !== 'unchanged').map((c) => c.msgno);
-        ctx.chunkEmitter?.emit('info', `messages ✓ ${className} ${written.join(' ')} (no activation needed)`);
-        const first = written[0] ?? rows[0].msgno;
-        return {
-            content: JSON.stringify({
-                written: true,
-                verified: true,
-                message_class: className,
-                changes: result.changes,
-                ...(resolved.owning ? { transport_used: resolved.owning, transport_note: resolved.note } : {}),
-                ...(lockNote ? { lock_warning: lockNote } : {}),
-                next_step: `Done — no activation needed. Raise these from code by number, e.g. MESSAGE e${first}(${className.toLowerCase()}) WITH …, or a T100 textid in an exception class. Never hard-code the texts.`,
-            }),
-        };
-    },
+    handler: writeToolHandler(MESSAGE_MAINTAIN_SPEC),
 });
 // ── sap_number_range_intervals (STUB) ─────────────────────────────────────────
 //