@cspeach/cli 1.0.0 → 1.1.0

package/dist/tools/fiori/tools.js

@@ -37,7 +37,7 @@
  *
  * FLAG / LOCAL_BUILD
  * ------------------
- * All four are flagGated:true (category 'fiori') and listed in
+ * Every fiori_* tool here is flagGated:true (category 'fiori') and listed in
  * LOCAL_BUILD_TOOLS, so `cspeach config set local_build on` enables them
  * alongside file_write/shell_exec — they are part of "build apps locally".
  *
@@ -53,6 +53,21 @@ import { applyEntry } from './apply.js';
 import { listCatalog } from './catalog/index.js';
 import { writeDeployConfig } from './deploy-config.js';
 import { scaffoldFioriElements } from './fe-scaffold.js';
+import { feExtend, FE_EXTEND_OPS, NotV4FeAppError } from './fe-extend.js';
+import { runSmoke } from './smoke/run-smoke.js';
+import { deriveFreestyleSmokeSpec, FreestyleSmokeDerivationError } from './smoke/freestyle-spec.js';
+import { loadConfig, resolveRenderSmoke } from '../../config/loader.js';
+import { searchSamples } from './samples/search.js';
+import { loadSampleSource, SampleFetchError, UnsafeSampleNameError } from './samples/loader.js';
+// The grounding corpus ships as an imported JSON module + the bundled
+// SAMPLE_SOURCES map (read inside loadSampleSource). NEVER readFileSync the
+// corpus — the import is the only shipping-safe read (rule A-C1).
+import sampleIndexJson from './samples/data/index.json' with { type: 'json' };
+const SAMPLE_INDEX = sampleIndexJson;
+// Short provenance line, always attached to a fiori_sample_get payload so the
+// model can cite the source (licensing constraint A-M1). Derived from the
+// corpus NOTICE: OpenUI5 sources, adapted, under Apache-2.0.
+const SAMPLE_ATTRIBUTION = 'Adapted from OpenUI5 (github.com/SAP/openui5) sample sources, licensed under Apache-2.0.';
 /** Resolve a user-supplied dir inside the project root, mapping the escape error. */
 function safeDir(ctx, userPath) {
     try {
@@ -213,6 +228,9 @@ export async function fioriScaffoldFeHandler(args, ctx) {
         return { content: 'error: appId is required', is_error: true };
     if (!args.mainEntity)
         return { content: 'error: mainEntity is required', is_error: true };
+    if (args.localAnnotations && (!args.localAnnotations.technicalName || !args.localAnnotations.xml)) {
+        return { content: 'error: localAnnotations requires both technicalName and xml', is_error: true };
+    }
     // metadata is OPTIONAL (the FE writer does not need it — spike §4); no $metadata fetch.
     const resolved = safeDir(ctx, args.basePath);
     if ('error' in resolved)
@@ -226,6 +244,7 @@ export async function fioriScaffoldFeHandler(args, ctx) {
             service: { url: args.serviceUrl, path: args.servicePath, version: args.serviceVersion ?? '4.0', metadata: args.metadata, client: args.client },
             mainEntity: args.mainEntity,
             ui5Version: args.ui5Version,
+            localAnnotations: args.localAnnotations,
         });
     }
     catch (err) {
@@ -239,6 +258,171 @@ export async function fioriScaffoldFeHandler(args, ctx) {
             `Files:\n${files.map((f) => `  ${f}`).join('\n')}`,
     };
 }
+// ───────────────────────────── fiori_fe_extend ────────────────────────────
+export async function feExtendHandler(args, ctx) {
+    if (!args.basePath)
+        return { content: 'error: basePath is required', is_error: true };
+    if (!args.op)
+        return { content: 'error: op is required', is_error: true };
+    if (!FE_EXTEND_OPS.includes(args.op)) {
+        return { content: `error: unknown op "${args.op}" — expected one of ${FE_EXTEND_OPS.join(', ')}`, is_error: true };
+    }
+    const resolved = safeDir(ctx, args.basePath);
+    if ('error' in resolved)
+        return { content: `error: ${resolved.error}`, is_error: true };
+    const before = new Set(await listFilesUnder(ctx, resolved.abs));
+    try {
+        await feExtend({ basePath: resolved.abs, op: args.op, params: args.params ?? {} });
+    }
+    catch (err) {
+        // V4-only scope limit: fe-fpm-writer refuses non-V4-FE apps (no
+        // sap.fe.templates) — surfaced as a clean typed line, not the writer's
+        // internal wording.
+        if (err instanceof NotV4FeAppError)
+            return { content: `error: ${err.message}`, is_error: true };
+        return { content: `error: fe extend failed — ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+    }
+    // Report only the newly-written files (the generator also touches manifest.json).
+    const after = await listFilesUnder(ctx, resolved.abs);
+    const created = after.filter((f) => !before.has(f));
+    const appDir = rel(ctx, resolved.abs);
+    return {
+        content: `Added FE extension "${args.op}" to ${appDir}/ (manifest.json updated).\n` +
+            (created.length
+                ? `New files:\n${created.map((f) => `  ${f}`).join('\n')}`
+                : `No new files (manifest-only change).`),
+    };
+}
+/**
+ * FREESTYLE MODE (appDir given): derive a SmokeSpec from the app's own webapp/
+ * tree via deriveFreestyleSmokeSpec, then let explicit spec args override the
+ * derived fields FIELD-BY-FIELD (explicit wins). `appUrl` always comes from the
+ * arg — derivation produces no URL. Returns the merged spec + derivation warnings,
+ * or a clean `error` string (bad appDir, or a typed derivation failure — named).
+ *
+ * Kept as a pure, exported helper so the derive+merge contract is unit-testable
+ * without launching a browser; the handler only orchestrates.
+ */
+export function resolveFreestyleSmokeSpec(args, ctx) {
+    const resolved = safeDir(ctx, args.appDir);
+    if ('error' in resolved)
+        return { error: resolved.error };
+    let derived;
+    try {
+        derived = deriveFreestyleSmokeSpec(resolved.abs);
+    }
+    catch (err) {
+        // Name the typed derivation failure (no stack trace) so the model sees WHY.
+        if (err instanceof FreestyleSmokeDerivationError) {
+            return { error: `${err.name}: ${err.message}` };
+        }
+        return { error: err instanceof Error ? err.message : String(err) };
+    }
+    const { warnings } = derived;
+    // Field-by-field merge (explicit wins). `??` keeps an explicitly-provided empty
+    // array/false as an override, and omits fields that are neither explicit nor derived.
+    const controlKind = args.controlKind ?? derived.controlKind;
+    const expectedColumns = args.expectedColumns ?? derived.expectedColumns;
+    const exercises = args.exercises ?? derived.exercises;
+    const spec = {
+        appUrl: args.appUrl, // always the arg — derivation carries no real preview URL
+        ...(controlKind !== undefined ? { controlKind } : {}),
+        ...(expectedColumns !== undefined ? { expectedColumns } : {}),
+        ...(args.allowEmptyRows !== undefined ? { allowEmptyRows: args.allowEmptyRows } : {}),
+        ...(exercises !== undefined ? { exercises } : {}),
+    };
+    return { spec, warnings };
+}
+export async function fioriRenderSmokeHandler(args, ctx, 
+// Test seam: injected runSmoke deps (browser/openApp/renderSmokeEnabled). In
+// production this is undefined and the real config-driven deps are used.
+deps) {
+    if (!args.appUrl) {
+        return {
+            content: 'error: appUrl is required — the LOCAL AUTHENTICATED PREVIEW URL (the `npm run start` / ' +
+                '`fiori run` URL, e.g. http://localhost:8080/index.html), NOT the deployed BSP URL.',
+            is_error: true,
+        };
+    }
+    // FE mode (no appDir): byte-identical to Track 2 — `args` is the spec, no warnings.
+    // Freestyle mode (appDir): derive + merge, and surface the derivation warnings.
+    let spec = args;
+    let warnings;
+    if (args.appDir) {
+        const derived = resolveFreestyleSmokeSpec(args, ctx);
+        if ('error' in derived) {
+            return {
+                content: `error: could not derive a freestyle smoke spec from appDir "${args.appDir}" — ${derived.error}`,
+                is_error: true,
+            };
+        }
+        spec = derived.spec;
+        warnings = derived.warnings;
+    }
+    // The render_smoke config toggle (plain default true) gates whether a browser
+    // is actually launched; when off, runSmoke returns a skipped manual result.
+    const cfg = await loadConfig();
+    const runDeps = { renderSmokeEnabled: resolveRenderSmoke(cfg), ...deps };
+    const result = await runSmoke(spec, runDeps);
+    // A skip is NOT a tool error — it's a valid `verification:'manual'` outcome the
+    // caller must see and act on (bring the preview up, etc.). Return the full
+    // SmokeResult as JSON either way. In freestyle mode attach the derivation
+    // warnings (always present — even []) so the model sees skipped presses/routes.
+    const payload = warnings !== undefined ? { ...result, warnings } : result;
+    return { content: JSON.stringify(payload, null, 2) };
+}
+// ─────────────────────────────── fiori_sample_search ──────────────────────
+export async function fioriSampleSearchHandler(args, _ctx) {
+    if (!args.text || !args.text.trim()) {
+        return { content: 'error: text is required — free-text keywords to match against the sample corpus', is_error: true };
+    }
+    // searchSamples is pure (Task 2): score the imported index, keep only real
+    // matches, ordered by descending score. Shape each hit as a compact,
+    // CatalogIndexItem-style summary + its score for the model to pick from.
+    // Clamp at the tool boundary: a model-supplied 0, negative, or fractional max
+    // would otherwise reach searchSamples' slice as-is (0 → no hits at all, a
+    // negative → silently drops from the tail). Undefined still means "default".
+    const max = args.max === undefined ? undefined : Math.max(1, Math.floor(args.max) || 1);
+    const hits = searchSamples(SAMPLE_INDEX, { text: args.text, control: args.control, max });
+    const summaries = hits.map(({ entry, score }) => ({
+        name: entry.name,
+        control: entry.control,
+        library: entry.library,
+        description: entry.description,
+        keywords: entry.keywords,
+        vendored: entry.sourceRef.vendored,
+        score,
+    }));
+    return { content: JSON.stringify(summaries, null, 2) };
+}
+// ─────────────────────────────── fiori_sample_get ─────────────────────────
+export async function fioriSampleGetHandler(args, _ctx) {
+    if (!args.name || !args.name.trim()) {
+        return { content: 'error: name is required — the sample name from fiori_sample_search (e.g. "sap.m/Wizard")', is_error: true };
+    }
+    const entry = SAMPLE_INDEX.find((e) => e.name === args.name);
+    if (!entry) {
+        return {
+            content: `error: sample "${args.name}" is not found in the sample index — call fiori_sample_search first to get a valid name.`,
+            is_error: true,
+        };
+    }
+    // loadSampleSource (Task 3): vendored → bundled SAMPLE_SOURCES; un-vendored →
+    // lazy fetch + cache. Its typed errors carry actionable, model-facing messages
+    // (fall back to recipes + sap-docs) — surface them verbatim, don't mask them.
+    try {
+        const loaded = await loadSampleSource(entry, {});
+        return {
+            content: JSON.stringify({ name: entry.name, files: loaded.files, license: 'Apache-2.0', attribution: SAMPLE_ATTRIBUTION }, null, 2),
+        };
+    }
+    catch (err) {
+        if (err instanceof SampleFetchError || err instanceof UnsafeSampleNameError) {
+            return { content: `error: ${err.message}`, is_error: true };
+        }
+        return { content: `error: could not load sample "${args.name}" — ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+    }
+}
 // ─────────────────────────────── registration ─────────────────────────────
 registerTool({
     name: 'fiori_scaffold',
@@ -327,7 +511,7 @@ registerTool({
 });
 registerTool({
     name: 'fiori_scaffold_fe',
-    description: 'Scaffold a trivial Fiori Elements app shell (List Report Object Page, Worklist, or Overview Page) ' +
+    description: 'Scaffold a trivial Fiori Elements app shell (List Report Object Page, Worklist, Overview Page, or Analytical List Page) ' +
         'against an ALREADY-PUBLISHED OData service. Driven entirely by the backend @UI annotations on the ' +
         'CDS projection/DDLX — authors NO local annotation.xml (not an FE generator). metadata is OPTIONAL ' +
         '(the running app reads it from the live service); pass it only if you already have it. basePath ' +
@@ -341,7 +525,7 @@ registerTool({
             basePath: { type: 'string', description: 'Directory to scaffold into (relative to project root).' },
             appId: { type: 'string', description: 'App namespace, e.g. "z.tcrs.courses".' },
             appTitle: { type: 'string', description: 'Human-readable title. Defaults to appId.' },
-            template: { type: 'string', enum: ['lrop', 'worklist', 'ovp'], description: 'FE template. Default "lrop". All three ship.' },
+            template: { type: 'string', enum: ['lrop', 'worklist', 'ovp', 'alp'], description: 'FE template: lrop (List Report), worklist, ovp (Overview Page), or alp (Analytical List Page). Default "lrop". All four ship.' },
             serviceUrl: { type: 'string', description: 'Backend host, e.g. "https://host:44300".' },
             servicePath: { type: 'string', description: 'OData service path, e.g. "/sap/opu/odata4/sap/zc_x/srvd/sap/zc_x/0001/".' },
             serviceVersion: { type: 'string', enum: ['2.0', '4.0'], description: 'OData version. Default "4.0".' },
@@ -349,8 +533,149 @@ registerTool({
             client: { type: 'string', description: 'OPTIONAL SAP client (e.g. "100"), written to the manifest for the proxy layer.' },
             mainEntity: { type: 'string', description: 'The entity set to bind, e.g. "Course".' },
             ui5Version: { type: 'string', description: 'UI5 version. Default 1.120.0.' },
+            localAnnotations: {
+                type: 'object',
+                description: 'OPTIONAL local annotations.xml for a FOREIGN OData service you do NOT own (cannot add backend @UI). ' +
+                    'Wires the given EDMX as a LOCAL ODataAnnotation dataSource (annotations/<technicalName>.xml) that ' +
+                    'resolves at runtime — no catalog fetch. Omit for services whose backend already carries @UI annotations.',
+                properties: {
+                    technicalName: { type: 'string', description: 'Local annotation name; also the dataSource key and file name (annotations/<technicalName>.xml).' },
+                    xml: { type: 'string', description: 'The annotations EDMX (UI.LineItem/HeaderInfo/SelectionFields/Facets in EDMX form).' },
+                },
+                required: ['technicalName', 'xml'],
+            },
         },
         required: ['basePath', 'appId', 'serviceUrl', 'servicePath', 'mainEntity'],
     },
     handler: fioriScaffoldFeHandler,
 });
+registerTool({
+    name: 'fiori_fe_extend',
+    description: 'Add a Fiori Elements extension point to an EXISTING V4 FE app on disk via @sap-ux/fe-fpm-writer: ' +
+        'a custom-column (table column + fragment), custom-action (toolbar/table action), custom-section ' +
+        '(object-page section + fragment), or controller-extension (a .controller.js/.ts + manifest wiring). ' +
+        'V4 Fiori Elements ONLY (LROP/Worklist/ALP/FEOP) — OVP and all OData V2 apps are refused with a typed ' +
+        'error. params map 1:1 to fe-fpm-writer\'s CustomTableColumn / CustomAction / CustomSection / ' +
+        'ControllerExtension config and are passed verbatim. basePath is sandboxed to the project root.',
+    isMutating: true,
+    category: 'fiori',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            basePath: { type: 'string', description: 'App root of the existing V4 FE app (the folder containing webapp/manifest.json), relative to the project root.' },
+            op: {
+                type: 'string',
+                enum: [...FE_EXTEND_OPS],
+                description: 'Extension point to add: custom-column, custom-action, custom-section, or controller-extension.',
+            },
+            params: {
+                type: 'object',
+                description: 'Extension config, passed VERBATIM to the matching fe-fpm-writer generator. Required fields per op: ' +
+                    'custom-column → { name, target (routing target, e.g. "<Entity>List"), targetEntity, position { placement: "After"|"Before"|"End", anchor? }, header }; ' +
+                    'custom-action → { name, target { page (routing target), control ("@com.sap.vocabularies.UI.v1.LineItem" for a table action) }, settings { text } }; ' +
+                    'custom-section → { name, target (object-page routing target, e.g. "<Entity>ObjectPage"), title }; ' +
+                    'controller-extension → { name, extension ("ListReport"|"ObjectPage" or a page-target object) }. ' +
+                    'eventHandler is optional on column/action/section.',
+            },
+        },
+        required: ['basePath', 'op', 'params'],
+    },
+    handler: feExtendHandler,
+});
+registerTool({
+    name: 'fiori_render_smoke',
+    description: 'Content-asserting render smoke (Track 2 D-4): launch a headless Edge/Chrome against the LOCAL ' +
+        'AUTHENTICATED PREVIEW (the `npm run start` URL — NEVER the deployed BSP URL) and assert the app ' +
+        'actually rendered — booted with no console errors, no failed OData ($metadata/$batch/entity) calls, ' +
+        'expected columns present, and (for a list) rows returned. TWO MODES: FIORI-ELEMENTS mode — pass the ' +
+        'spec fields (expectedColumns/controlKind/…) yourself. FREESTYLE mode — pass `appDir` (the scaffolded ' +
+        'app root) plus `appUrl` and the spec is DERIVED from the app\'s own webapp/ views + i18n + manifest ' +
+        '(controlKind, expected columns, press/route exercises); any spec field you ALSO pass overrides the ' +
+        'derived one. Derivation notes surface as a `warnings` array in the result. SKIPPABLE BUT NEVER ' +
+        'SILENTLY GREEN: when the render_smoke config is off, no browser is found, the preview is unreachable, ' +
+        'or the page is a SAP logon form, it returns verification:"manual" + passed:false with a "skipped" ' +
+        'check explaining why — it can never report a passing smoke without a real render. Flag-gated (enabled ' +
+        'with local_build), read-only.',
+    isMutating: false,
+    category: 'fiori',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            appUrl: {
+                type: 'string',
+                description: 'The LOCAL AUTHENTICATED PREVIEW URL (the `npm run start` / `fiori run` URL that proxies to the ' +
+                    'real backend with your auth), e.g. "http://localhost:8080/index.html". NOT the deployed BSP URL.',
+            },
+            appDir: {
+                type: 'string',
+                description: 'FREESTYLE mode only: the scaffolded app root (relative to the project root, sandboxed). When ' +
+                    'given, the SmokeSpec is DERIVED from that app\'s webapp/ views + i18n + manifest, and any spec ' +
+                    'field you also pass overrides the derived one. Omit for Fiori Elements mode (pass the spec fields directly).',
+            },
+            expectedColumns: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Column headers that MUST be present (checked case-insensitively). Omit for non-list controls.',
+            },
+            controlKind: {
+                type: 'string',
+                enum: ['table', 'cards', 'chart', 'form', 'custom'],
+                description: 'The app\'s primary control. Only "table" gets a row-count assertion.',
+            },
+            allowEmptyRows: {
+                type: 'boolean',
+                description: 'When true, a table that renders 0 rows still passes (empty list acknowledged). Default false.',
+            },
+            exercises: {
+                type: 'array',
+                description: 'Post-boot interactions to exercise (press/route). Declared for Track 3; unused in Track 2.',
+                items: { type: 'object' },
+            },
+        },
+        required: ['appUrl'],
+    },
+    handler: fioriRenderSmokeHandler,
+});
+registerTool({
+    name: 'fiori_sample_search',
+    description: 'Search the vendored UI5 Demo Kit sample corpus (grounding for the freestyle composer): free-text ' +
+        'keywords + an optional exact control name return the best-matching samples as scored summaries ' +
+        '(name, control, library, description, keywords, vendored flag, score), highest score first. Use this ' +
+        'to FIND a real UI5 sample to ground a control against, then fiori_sample_get to read its source. ' +
+        'Read-only; flag-gated (enabled with local_build).',
+    isMutating: false,
+    category: 'fiori',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            text: { type: 'string', description: 'Free-text keywords, e.g. "wizard step" or "value help dialog".' },
+            control: { type: 'string', description: 'OPTIONAL exact UI5 control name (e.g. "Wizard") — an exact match dominates the ranking.' },
+            max: { type: 'number', description: 'Max results to return. Default 5.' },
+        },
+        required: ['text'],
+    },
+    handler: fioriSampleSearchHandler,
+});
+registerTool({
+    name: 'fiori_sample_get',
+    description: 'Fetch one UI5 sample\'s source files by name (the grounding payload the composer reads). Returns ' +
+        '{ files: [{ path, content }], license: "Apache-2.0", attribution }. Vendored samples are served from ' +
+        'the bundled corpus; un-vendored ones are lazily fetched and cached. The Apache-2.0 attribution line ' +
+        'is ALWAYS included. Call fiori_sample_search first to get a valid name. An unknown name, or a sample ' +
+        'that cannot be retrieved, returns a clean error steering you to the recipes catalog + sap-docs. ' +
+        'Read-only; flag-gated (enabled with local_build).',
+    isMutating: false,
+    category: 'fiori',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            name: { type: 'string', description: 'The sample name from fiori_sample_search, e.g. "sap.m/Wizard".' },
+        },
+        required: ['name'],
+    },
+    handler: fioriSampleGetHandler,
+});

package/dist/tools/local-build.js

@@ -10,8 +10,13 @@
  *
  *   filesystem: file_read, file_write, file_edit, glob, grep
  *   shell:      shell_exec
- *   fiori:      fiori_scaffold, fiori_apply, fiori_list, fiori_deploy_config
+ *   fiori:      fiori_scaffold, fiori_apply, fiori_list, fiori_deploy_config,
+ *               fiori_scaffold_fe, fiori_fe_extend, fiori_render_smoke,
+ *               fiori_sample_search, fiori_sample_get
  *   extend:     extend_model_insert (anchored CDS/DDLX edit — abap-extend-model)
+ *   subagent:   agent_run (Task 7, 2026-07-03 — customers get subagent
+ *               dispatch when local_build is on; plan phases force its
+ *               read-only tool filter regardless of the model's args)
  *
  * This is what makes /abap-fiori-build runnable end to end — it writes local
  * app files (FS tools), runs safelisted build CLIs (shell), AND scaffolds /
@@ -56,8 +61,13 @@ export const LOCAL_BUILD_TOOLS = [
     'fiori_list',
     'fiori_deploy_config',
     'fiori_scaffold_fe',
+    'fiori_fe_extend',
+    'fiori_render_smoke',
+    'fiori_sample_search',
+    'fiori_sample_get',
     'extend_model_insert',
     'system_capability',
+    'agent_run',
 ];
 /**
  * Apply the persisted `local_build` toggle. When on, force-enables the FS +

package/dist/tools/sap-read.js

@@ -32,7 +32,9 @@ registerTool({
         + 'omitting it lets SAP choose (usually active). When the object has '
         + 'pending inactive changes and the caller did not pass `version`, '
         + 'the response is the active source AND a warning is emitted so the '
-        + 'caller knows the inactive edits are not visible.',
+        + 'caller knows the inactive edits are not visible. For a freshly '
+        + 'created object with NO active version yet, the inactive (working) '
+        + 'source is returned with version="inactive" and an honest note.',
     isMutating: false,
     input_schema: {
         type: 'object',
@@ -68,15 +70,41 @@ registerTool({
                 const conflict = inactive.find((o) => o.name.toUpperCase() === upperName &&
                     (o.type === '' || o.type.toUpperCase().startsWith(upperType)));
                 if (conflict) {
-                    // SAP defaults to the active version when version is unspecified,
-                    // but the caller should know an inactive copy exists so they don't
-                    // base dependent edits on stale committed source.
-                    resolvedVersion = 'active';
-                    splitStateWarning =
-                        `${args.type} ${args.name} has a pending inactive version. `
-                            + `This response is the ACTIVE source; pending edits are NOT included. `
-                            + `Pass version="inactive" to read the in-flight version, or have the user `
-                            + `activate (or discard) the inactive version before basing dependent code on this read.`;
+                    // Fable review 2026-07-06 (clas-create-hygiene I1): a FRESH shell
+                    // (created, never activated) ALSO appears in inactiveObjects(), but
+                    // it has NO active version at all — sap-client's inactive-read
+                    // fallback just served the INACTIVE (working) source. Claiming
+                    // "this is the ACTIVE source" here would be false. Cross-check
+                    // objectStructure's adtcore:version (honest for fresh shells now
+                    // that objectStructure carries the same inactive fallback):
+                    // 'inactive' ⇒ inactive-only shell.
+                    let inactiveOnly = false;
+                    try {
+                        const struct = await ctx.adt.objectStructure(args.type, args.name);
+                        const m = /\badtcore:version="([^"]*)"/.exec(struct.rawXml ?? '');
+                        inactiveOnly = m?.[1] === 'inactive';
+                    }
+                    catch {
+                        // Cross-check failed — fall through to the conservative
+                        // split-state warning (never claim inactive-only without proof).
+                    }
+                    if (inactiveOnly) {
+                        resolvedVersion = 'inactive';
+                        splitStateWarning =
+                            `${args.type} ${args.name} has no active version yet — this is the `
+                                + `inactive (working) source. Activate it via sap_activate when ready.`;
+                    }
+                    else {
+                        // SAP defaults to the active version when version is unspecified,
+                        // but the caller should know an inactive copy exists so they don't
+                        // base dependent edits on stale committed source.
+                        resolvedVersion = 'active';
+                        splitStateWarning =
+                            `${args.type} ${args.name} has a pending inactive version. `
+                                + `This response is the ACTIVE source; pending edits are NOT included. `
+                                + `Pass version="inactive" to read the in-flight version, or have the user `
+                                + `activate (or discard) the inactive version before basing dependent code on this read.`;
+                    }
                 }
                 else {
                     resolvedVersion = 'active';
@@ -112,7 +140,22 @@ registerTool({
     },
     handler: async (args, ctx) => {
         const result = await ctx.adt.objectStructure(args.type, args.name);
-        return { content: JSON.stringify(result, null, 2) };
+        // Fable review 2026-07-05 (audit-reverify item 2) — surface the object's
+        // adtcore:version EARLY in the JSON. The sap-client ObjectStructure has
+        // no parsed version field; adtcore:version lives deep inside rawXml,
+        // beyond the audit evidence's 200-char result excerpt — so the audit
+        // contract's "sap_object_structure reporting an active version" proof
+        // path for verify-only re-runs was unreachable in production, and a
+        // re-run that skipped sap_inactive_objects would false-FAIL an active
+        // object. Parsing here (CLI-side, no sap-client bump) and placing
+        // `version` right after name/type puts it inside the excerpt window.
+        const versionMatch = /\badtcore:version="([^"]*)"/.exec(result.rawXml ?? '');
+        const version = versionMatch?.[1] || 'unknown';
+        // name/type/version lead the serialized JSON (rawXml stays last via the
+        // rest spread), so `version` sits inside the excerpt window while every
+        // ObjectStructure field is preserved.
+        const { name, type, ...rest } = result;
+        return { content: JSON.stringify({ name, type, version, ...rest }, null, 2) };
     },
 });
 // -----------------------------------------------------------------------
@@ -475,6 +518,31 @@ registerTool({
     handler: async (args, ctx) => {
         // runUnitTest(type, name) — type first
         const result = await ctx.adt.runUnitTest(args.type, args.name);
+        // B2 false-green guard (project_aunit_run_gap): the ADT AUnit-run endpoint
+        // returns HTTP 200 with an EMPTY runResult (total:0, no programs) even for a
+        // class that is active + syntax-clean with a valid FOR TESTING local class —
+        // a known environmental gap, exhaustively probed (sap-client buildUnitTestXml
+        // comment). The raw {total:0} shape reads to a caller like "0 tests, nothing
+        // failed → green", so an unguarded pass-through risks a false-green test gate.
+        // When we detect that empty signature, wrap the (still-carried) raw result in
+        // an explicit UNVERIFIED envelope that names Eclipse "Run As → ABAP Unit" as
+        // the authoritative check. A genuine run (total > 0) passes through unchanged.
+        const summary = result?.summary;
+        const programs = result?.programs;
+        const noTestsRun = summary?.total === 0 && (!Array.isArray(programs) || programs.length === 0);
+        if (noTestsRun) {
+            return {
+                content: JSON.stringify({
+                    verification: 'UNVERIFIED',
+                    warning: 'ABAP Unit run enumerated 0 tests (empty runResult). This does NOT mean the tests ' +
+                        'passed — it means none executed. A FOR TESTING class that is active + syntax-clean ' +
+                        'still returning 0 is a known ADT AUnit-run gap (project_aunit_run_gap): the ' +
+                        'authoritative check is Eclipse "Run As → ABAP Unit" (Ctrl+Shift+F10). Do NOT treat ' +
+                        'this as a green test gate.',
+                    result,
+                }, null, 2),
+            };
+        }
         return { content: JSON.stringify(result, null, 2) };
     },
 });

package/dist/tools/sap-write.js

@@ -48,15 +48,27 @@ function emitSnapshotNotice(ctx, snap, type, name) {
         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)". */
+ *  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')
+    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 };
     }
@@ -128,11 +140,15 @@ registerTool({
                     error: ERR.SNAPSHOT_FAILED,
                     reason: 'source_read_failed',
                     detail: snapOutcome.detail,
-                    recovery: 'Pre-write source read failed (non-404) — the object may exist but no snapshot could be taken. Fix the read failure (connection/auth) and retry; do not bypass Rule 7.',
+                    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()) {
@@ -285,11 +301,15 @@ registerTool({
                     error: ERR.SNAPSHOT_FAILED,
                     reason: 'source_read_failed',
                     detail: snapOutcome.detail,
-                    recovery: 'Pre-write source read failed (non-404) — the class exists but no snapshot could be taken. Fix the read failure (connection/auth) and retry; do not bypass Rule 7.',
+                    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) {

package/dist/tools/snapshot.js

@@ -66,7 +66,33 @@ export async function autoSnapshot(objectName, objectType, adt) {
     catch (err) {
         if (isNotFound(err))
             return { taken: false, reason: 'object_not_found' }; // new object
-        return { taken: false, reason: 'source_read_failed', detail: shortErrorMessage(err) };
+        // The DEFAULT read failed for a non-404 reason. Before treating this as a
+        // hard read failure (which blocks the write, Rule 7), distinguish an
+        // empty/never-activated SHELL from a real object whose source we couldn't
+        // read. A freshly-created behaviour-pool CLAS (ZBP … FOR BEHAVIOR OF …)
+        // EXISTS but has no committed source yet, so the default read returns HTTP
+        // 400 — not 404. Such a shell has NO committed ACTIVE version. Probe for one:
+        //   - active read 404      → no active version ⇒ fresh shell, nothing to
+        //                             snapshot ⇒ proceed ('new_shell').
+        //   - active read succeeds → there IS committed source to protect ⇒
+        //                             snapshot THAT active source and proceed.
+        //   - active read fails otherwise → can't confirm emptiness ⇒ conservative
+        //                             block ('source_read_failed', unchanged).
+        let activeSrc;
+        try {
+            activeSrc = await adt.getSource(objectType, objectName, 'active');
+        }
+        catch (activeErr) {
+            if (isNotFound(activeErr))
+                return { taken: false, reason: 'new_shell' };
+            // Could not confirm the object is empty — keep the safety property: a
+            // real object with source we couldn't read must still block the write.
+            return { taken: false, reason: 'source_read_failed', detail: shortErrorMessage(err) };
+        }
+        // Committed active version exists — snapshot it. A snapshots.take failure
+        // still THROWS (Rule 7 hard-fail), same as the clean-read path below.
+        const activeEntry = await snapshots.take(objectType, objectName, activeSrc, 'before_write');
+        return { taken: true, entry: activeEntry };
     }
     const entry = await snapshots.take(objectType, objectName, src, 'before_write');
     return { taken: true, entry };