@cspeach/cli 0.9.0 → 1.1.0

package/dist/tools/sap-write.js

@@ -15,6 +15,7 @@
  *   lock(type, name)                                 → Promise<LockResult>       line 1914
  *   unlock(type, name, lockHandle)                   → Promise<void>             line 1949
  *   serviceBindingPublish(name)                      → Promise<{status,error?}>  line 2658
+ *   serviceBindingUnpublish(name)                    → Promise<{status,error?}>
  *   messageMaintain (STUB — not yet in sap-client)
  *   numberRangeIntervals (STUB — not yet in sap-client)
  *
@@ -24,18 +25,65 @@ import crypto from 'node:crypto';
 import { registerTool } from './index.js';
 import { verifyAndSpendApprovalId } from '../approvals/jwt.js';
 import { autoSnapshot } from './snapshot.js';
+import { buildWriteChainLine } from '../renderer/verify-chain.js';
 import { verifySyntax, verifyActive } from './verify.js';
 import { appendPending, finalizeToolCall } from '../session/pending.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';
 import { presentSafetyConfirmation } from '../repl/safety-confirm.js';
 import { isSafetyConfirmEnabled } from '../repl/safety-mode-state.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' };
+}
+/** Compact ①②③④ pipeline summary — derived from the real gate results. */
+function emitWriteChain(ctx, input) {
+    ctx.chunkEmitter?.emit('chunk', buildWriteChainLine(input) + '\n');
+}
 registerTool({
     name: 'sap_set_source',
     description: 'Overwrite the full source of an ABAP object. Requires approval_id. '
         + 'Use for class-definition changes, new methods, or any change not confined to '
-        + 'a single method body. For method-body-only edits use sap_update_method (Rule 7a).',
+        + 'a single method body. For method-body-only edits use sap_update_method (Rule 7a). '
+        + 'The transport auto-resolves to the owning request if the object is already locked.',
     isMutating: true,
     input_schema: {
         type: 'object',
@@ -57,7 +105,7 @@ registerTool({
                 is_error: true,
             };
         }
-        const toolUseId = crypto.randomUUID();
+        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
@@ -69,9 +117,16 @@ registerTool({
                 ctx.chunkEmitter?.emit('warn', `LLM passed transport=${args.transport} but session current-transport=${sessionTransport}`);
             }
         }
-        // ── Gate 2: Snapshot (Rule 7) ────────────────────────────────────────────
+        // ── 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);
+        // ── 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 {
-            await autoSnapshot(args.name, args.type, ctx.adt);
+            snapOutcome = await autoSnapshot(args.name, args.type, ctx.adt);
         }
         catch (err) {
             return {
@@ -79,6 +134,22 @@ registerTool({
                 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({
@@ -87,7 +158,7 @@ registerTool({
                 object: { type: args.type, name: args.name },
                 what_will_happen: 'Overwrites full object source; snapshot is taken first.',
                 rollback_available: true,
-                transport: args.transport ?? ctx.currentTransport?.get() ?? '',
+                transport: resolved.transport ?? ctx.currentTransport?.get() ?? '',
             });
             if (!r.confirmed) {
                 return {
@@ -114,7 +185,7 @@ registerTool({
         // Regression evidence + diagnosis: memory/project_phase3_lite_regression.md.
         let writeResult;
         try {
-            writeResult = await ctx.adt.setSource(args.type, args.name, args.source, args.transport);
+            writeResult = await ctx.adt.setSource(args.type, args.name, args.source, resolved.transport);
         }
         catch (err) {
             const errStr = String(err);
@@ -140,12 +211,19 @@ registerTool({
         // ── 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);
+        // Tour slide-7 chain — derived from the gates that actually ran.
+        emitWriteChain(ctx, {
+            ...snapshotChainState(snapOutcome),
+            written: true,
+            syntax: { ok: syntax.ok, errors: syntax.errors },
+        });
         return {
             content: JSON.stringify({
                 written: true,
                 syntax_ok: syntax.ok,
                 errors: syntax.errors,
                 warnings: syntax.warnings,
+                ...(resolved.owning ? { transport_used: resolved.owning, transport_note: resolved.note } : {}),
                 next_step: syntax.ok
                     ? 'activation_allowed'
                     : 'activation_blocked_until_syntax_errors_fixed',
@@ -166,7 +244,8 @@ registerTool({
     description: 'Replace the body of a single method in an existing class. '
         + 'Preferred over sap_set_source for method-body-only changes (Rule 7a) — '
         + 'does NOT rewrite the class definition. '
-        + 'method_source must be the lines between METHOD x. and ENDMETHOD. (no wrappers).',
+        + 'method_source must be the lines between METHOD x. and ENDMETHOD. (no wrappers). '
+        + 'The transport auto-resolves to the owning request if the class is already locked.',
     isMutating: true,
     input_schema: {
         type: 'object',
@@ -188,7 +267,7 @@ registerTool({
                 is_error: true,
             };
         }
-        const toolUseId = crypto.randomUUID();
+        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
@@ -200,9 +279,15 @@ registerTool({
                 ctx.chunkEmitter?.emit('warn', `LLM passed transport=${args.transport} but session current-transport=${sessionTransport}`);
             }
         }
-        // ── Gate 2: Snapshot (Rule 7) ────────────────────────────────────────────
+        // ── Rule 9 owning-transport check (D15/D20) ──────────────────────────────
+        const resolved = await resolveWriteTransport(ctx, 'CLAS', args.class_name, args.transport);
+        // ── 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 {
-            await autoSnapshot(args.class_name, 'CLAS', ctx.adt);
+            snapOutcome = await autoSnapshot(args.class_name, 'CLAS', ctx.adt);
         }
         catch (err) {
             return {
@@ -210,6 +295,22 @@ registerTool({
                 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 {
@@ -227,7 +328,7 @@ registerTool({
             className: args.class_name,
             methodName: args.method_name,
             methodSource: args.method_source,
-            transport: args.transport ?? ctx.currentTransport?.get() ?? '',
+            transport: resolved.transport ?? ctx.currentTransport?.get() ?? '',
         };
         try {
             await interceptUpdateMethod(minimal, call, ctx.previewHook);
@@ -263,7 +364,7 @@ registerTool({
         // silently overwriting the inactive-only declarations.
         let updateResult;
         try {
-            updateResult = await ctx.adt.updateMethod(args.class_name, args.method_name, args.method_source, args.transport);
+            updateResult = await ctx.adt.updateMethod(args.class_name, args.method_name, args.method_source, resolved.transport);
         }
         catch (err) {
             const errStr = String(err);
@@ -302,12 +403,19 @@ registerTool({
         // ── 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);
+        // Tour slide-7 chain — derived from the gates that actually ran.
+        emitWriteChain(ctx, {
+            ...snapshotChainState(snapOutcome),
+            written: true,
+            syntax: { ok: syntax.ok, errors: syntax.errors },
+        });
         return {
             content: JSON.stringify({
                 updated: true,
                 syntax_ok: syntax.ok,
                 errors: syntax.errors,
                 warnings: syntax.warnings,
+                ...(resolved.owning ? { transport_used: resolved.owning, transport_note: resolved.note } : {}),
                 next_step: syntax.ok
                     ? 'activation_allowed'
                     : 'activation_blocked_until_syntax_errors_fixed',
@@ -324,7 +432,8 @@ registerTool({
     name: 'sap_delete_object',
     description: 'Delete an ABAP object. Requires approval_id. '
         + 'A snapshot is taken automatically before deletion. '
-        + 'Post-check: confirms the object no longer exists.',
+        + 'Post-check: confirms the object no longer exists. '
+        + 'The transport auto-resolves to the owning request if the object is already locked.',
     isMutating: true,
     input_schema: {
         type: 'object',
@@ -345,7 +454,7 @@ registerTool({
                 is_error: true,
             };
         }
-        const toolUseId = crypto.randomUUID();
+        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
@@ -357,13 +466,17 @@ registerTool({
                 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 {
-            await autoSnapshot(args.name, args.type, ctx.adt);
+            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({
@@ -372,7 +485,7 @@ registerTool({
                 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: args.transport ?? ctx.currentTransport?.get() ?? '',
+                transport: resolved.transport ?? ctx.currentTransport?.get() ?? '',
             });
             if (!r.confirmed) {
                 return {
@@ -394,7 +507,7 @@ registerTool({
         // 4xx. Must check status / error on the return value.
         let deleteResult;
         try {
-            deleteResult = await ctx.adt.deleteObject(args.type, args.name, args.transport);
+            deleteResult = await ctx.adt.deleteObject(args.type, args.name, resolved.transport);
         }
         catch (err) {
             const errStr = String(err);
@@ -423,7 +536,11 @@ registerTool({
             .catch(() => false);
         await finalizeToolCall(ctx.session, toolUseId, JSON.stringify({ deleted: !stillExists }), false, Date.now() - startedAt);
         return {
-            content: JSON.stringify({ deleted: !stillExists, still_exists: stillExists }),
+            content: JSON.stringify({
+                deleted: !stillExists,
+                still_exists: stillExists,
+                ...(resolved.owning ? { transport_used: resolved.owning, transport_note: resolved.note } : {}),
+            }),
         };
     },
 });
@@ -448,6 +565,11 @@ registerTool({
             description: { type: 'string', description: 'Short description' },
             transport: { type: 'string', description: 'Target transport (optional — required for workbench packages)' },
             approval_id: { type: 'string', description: 'JWT from request_approval' },
+            // SRVB-only: a service binding must name the activated service definition it
+            // binds, plus the protocol/version. Required for type=SRVB; ignored otherwise.
+            serviceDefinition: { type: 'string', description: 'SRVB ONLY — REQUIRED when type=SRVB: name of the activated service definition (SRVD) to bind, e.g. ZUI_MYSERVICE.' },
+            bindingType: { type: 'string', description: 'SRVB ONLY (optional): binding protocol. Default ODATA.' },
+            bindingVersion: { type: 'string', description: 'SRVB ONLY (optional): binding version. Default V4 (OData V4 UI). Use V2 for OData V2.' },
         },
         required: ['name', 'type', 'package', 'description', 'approval_id'],
     },
@@ -460,7 +582,7 @@ registerTool({
                 is_error: true,
             };
         }
-        const toolUseId = crypto.randomUUID();
+        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 ──────────────────
@@ -486,7 +608,11 @@ registerTool({
         // createObject(objtype, name, packageName, description, transport?, extras?)
         let result;
         try {
-            result = await ctx.adt.createObject(args.type, args.name, args.package, args.description, effectiveTransport);
+            result = await ctx.adt.createObject(args.type, args.name, args.package, args.description, effectiveTransport, {
+                serviceDefinition: args.serviceDefinition,
+                bindingType: args.bindingType,
+                bindingVersion: args.bindingVersion,
+            });
             await auditLog('createObject', args.type, args.name, 'success', Date.now() - startedAt);
         }
         catch (err) {
@@ -516,6 +642,386 @@ registerTool({
         };
     },
 });
+// ── 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. Snapshot is best-effort:
+// the include source may not be independently readable, so a failed snapshot
+// must not block the write (consistent with sap_delete_object).
+registerTool({
+    name: 'sap_set_class_include',
+    description: 'Write a class local-include source (CCDEF locals_def, CCIMP locals_imp, '
+        + 'CCMAC macros, or test classes). Required for RAP behaviour-pool handlers, '
+        + 'which live in the CCIMP (locals_imp) include. Requires approval_id. '
+        + 'After writing, activate the class via sap_activate. '
+        + 'The transport auto-resolves to the owning request if the class is already locked.',
+    isMutating: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            className: { type: 'string', description: 'ABAP class name (e.g. ZBP_FOO)' },
+            includeType: {
+                type: 'string',
+                enum: ['locals_def', 'locals_imp', 'macros', 'testclasses'],
+                description: 'Which local include to write (locals_imp = CCIMP, where RAP handlers live)',
+            },
+            source: { type: 'string', description: 'Include source body' },
+            transport: { type: 'string', description: 'Transport request number (optional)' },
+            approval_id: { type: 'string', description: 'JWT from request_approval' },
+        },
+        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,
+            };
+        }
+        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;
+        // ── 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);
+        // ── Gate 2: Snapshot (Rule 7) — best-effort, include may not be readable ─
+        let snapOutcome;
+        try {
+            snapOutcome = await autoSnapshot(args.className, 'CLAS', ctx.adt);
+        }
+        catch {
+            // Silently ignore — include source may not be independently readable.
+        }
+        emitSnapshotNotice(ctx, snapOutcome, 'CLAS', args.className);
+        // ── 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}`);
+        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',
+        });
+        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.
+registerTool({
+    name: 'sap_create_domain',
+    description: 'Create a DDIC domain (DOMA), then activate and verify it. '
+        + 'Requires approval_id. No snapshot needed (new object). '
+        + 'Use the domain in a data element via sap_create_data_element.',
+    isMutating: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            name: { type: 'string', description: 'Domain name (Z*/Y*)' },
+            description: { type: 'string', description: 'Short description' },
+            package: { type: 'string', description: 'Development package (Z*/Y* or $TMP)' },
+            dataType: { type: 'string', description: 'ABAP data type (CHAR/NUMC/DEC/CURR/QUAN/INT1/INT2/INT4/DATS/TIMS/…)' },
+            length: { type: 'number', description: 'Domain length (number of characters/digits)' },
+            decimals: { type: 'number', description: 'Number of decimal places (DEC/CURR/QUAN)' },
+            outputLength: { type: 'number', description: 'Output length (optional)' },
+            lowercase: { type: 'boolean', description: 'Allow lowercase (optional)' },
+            signExists: { type: 'boolean', description: 'Value can be negative (optional)' },
+            valueTable: { type: 'string', description: 'Check / value table (optional)' },
+            fixedValues: {
+                type: 'array',
+                description: 'Fixed value list (optional)',
+                items: {
+                    type: 'object',
+                    properties: {
+                        value: { type: 'string', description: 'Fixed value' },
+                        text: { type: 'string', description: 'Description text' },
+                    },
+                    required: ['value', 'text'],
+                },
+            },
+            transport: { type: 'string', description: 'Target transport (optional)' },
+            approval_id: { type: 'string', description: 'JWT from request_approval' },
+        },
+        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,
+            };
+        }
+        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,
+            };
+        }
+        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',
+            }),
+        };
+    },
+});
+// ── 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.
+registerTool({
+    name: 'sap_create_data_element',
+    description: 'Create a DDIC data element (DTEL) bound to an existing domain, then '
+        + 'activate and verify it. Requires approval_id. No snapshot needed (new object). '
+        + 'Use the data element as a table/structure field type.',
+    isMutating: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            name: { type: 'string', description: 'Data element name (Z*/Y*)' },
+            description: { type: 'string', description: 'Short description' },
+            package: { type: 'string', description: 'Development package (Z*/Y* or $TMP)' },
+            domainName: { type: 'string', description: 'Referenced domain name' },
+            dataType: { type: 'string', description: "Referenced domain's data type (CHAR/NUMC/CURR/…)" },
+            length: { type: 'number', description: 'Domain length' },
+            decimals: { type: 'number', description: 'Decimal places (optional)' },
+            labels: {
+                type: 'object',
+                description: 'Field labels',
+                properties: {
+                    short: { type: 'string', description: 'Short label' },
+                    medium: { type: 'string', description: 'Medium label' },
+                    long: { type: 'string', description: 'Long label' },
+                    heading: { type: 'string', description: 'Heading label' },
+                },
+                required: ['short', 'medium', 'long', 'heading'],
+            },
+            searchHelp: { type: 'string', description: 'Attached search help name (optional)' },
+            searchHelpParameter: { type: 'string', description: 'Search help parameter (optional)' },
+            transport: { type: 'string', description: 'Target transport (optional)' },
+            approval_id: { type: 'string', description: 'JWT from request_approval' },
+        },
+        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,
+            };
+        }
+        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,
+            };
+        }
+        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',
+            }),
+        };
+    },
+});
 // ── sap_activate ─────────────────────────────────────────────────────────────
 //
 // Signature: activate(type, name) → Promise<ActivationResult>
@@ -565,7 +1071,7 @@ registerTool({
                 is_error: true,
             };
         }
-        const toolUseId = crypto.randomUUID();
+        const toolUseId = ctx.toolUseId ?? crypto.randomUUID();
         const startedAt = Date.now();
         // ── WAL: record pending entry ────────────────────────────────────────────
         await appendPending(ctx.session, {
@@ -700,6 +1206,29 @@ registerTool({
         return { content: JSON.stringify(result) };
     },
 });
+// ── sap_service_binding_unpublish ─────────────────────────────────────────────
+//
+// Unpublish a service binding (inverse of publish). REQUIRED before deleting a
+// published binding — SAP returns HTTP 412 "… is published" otherwise (Bug #6).
+// Signature: serviceBindingUnpublish(name) → Promise<{ status: number; error?: string }>
+// NOTE: the unpublishjobs endpoint is inferred-not-yet-live-verified (VPN down).
+registerTool({
+    name: 'sap_service_binding_unpublish',
+    description: 'Unpublish an ADT service binding so its OData endpoint is removed. '
+        + 'Required before deleting a published binding (SAP returns HTTP 412 "is published" otherwise).',
+    isMutating: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            name: { type: 'string', description: 'Service binding name (e.g. ZSALES_UI_V4)' },
+        },
+        required: ['name'],
+    },
+    handler: async (args, ctx) => {
+        const result = await ctx.adt.serviceBindingUnpublish(args.name);
+        return { content: JSON.stringify(result) };
+    },
+});
 // ── sap_message_maintain (STUB) ───────────────────────────────────────────────
 //
 // STUB — MSAG message-class maintenance requires XML message-class-format