@avocadostudio-ai/orchestrator-core 0.3.1 → 0.3.2

package/dist/chat/chat-pipeline.js

@@ -1171,6 +1171,7 @@ export async function runChatPipeline(ctx, body, options) {
                         blockId: entry.blockId,
                         blockType: entry.blockType,
                         propName: entry.propName,
+                        allowedProps: entry.allowedProps,
                         plannerSource: source,
                         modelKey,
                         modelUsed

package/dist/chat/hallucination-validator.d.ts

@@ -15,6 +15,12 @@ export type HallucinatedProp = {
     blockId: string;
     blockType: string;
     propName: string;
+    /**
+     * What the block *does* accept. Present so the log line that records a strip
+     * carries the answer next to the question — the integrator who hit this spent
+     * nine minutes proving the block was fine, and this is the line they read.
+     */
+    allowedProps: string[];
 };
 export type HallucinationValidationResult = {
     plan: EditPlan;

package/dist/chat/hallucination-validator.js

@@ -45,6 +45,22 @@ function findBlockType(args) {
     }
     return undefined;
 }
+/*
+ * Does this key read as a visual/presentational one?
+ *
+ * Deliberately a small allow-list of stems rather than a clever rule: the
+ * default has to be "content", because the expensive mistake is telling
+ * somebody their content edit was a styling limitation, not the reverse.
+ */
+const VISUAL_PROP_STEMS = [
+    "color", "colour", "background", "gradient", "animation", "animate", "shadow",
+    "font", "size", "spacing", "padding", "margin", "border", "radius", "opacity",
+    "align", "theme", "style", "variant", "width", "height", "position", "layout"
+];
+function isVisualPropName(prop) {
+    const lower = prop.toLowerCase();
+    return VISUAL_PROP_STEMS.some((stem) => lower.includes(stem));
+}
 function humanBlockName(blockType) {
     const meta = getBlockMeta(blockType);
     return meta?.displayName ?? blockType;
@@ -81,15 +97,33 @@ export function validateAndStripHallucinatedProps(args) {
             if (allowedKeys.has(key))
                 continue;
             delete patchCandidate[key];
-            hallucinatedProps.push({ blockId: op.blockId, blockType, propName: key });
+            hallucinatedProps.push({
+                blockId: op.blockId,
+                blockType,
+                propName: key,
+                allowedProps: [...allowedKeys].sort()
+            });
         }
     }
     if (hallucinatedProps.length > 0) {
-        // Merge duplicates into a single readable note keyed by blockType. We
-        // intentionally avoid echoing the raw prop name back to the user —
-        // doing so is (a) jargon-y (users don't think in prop keys), and (b)
-        // makes the note trivially collide with eval banned-word checks that
-        // try to prove the planner didn't promise the unsupported behavior.
+        /*
+         * Two different events used to share one sentence, and the wrong one was
+         * the default.
+         *
+         * "Some requested styling isn't available" is true when the planner
+         * promised a colour, a gradient or an animation the block has no field
+         * for. It is false — and actively misleading — when the planner simply
+         * used the wrong *name* for a field the block does have under another
+         * name: nothing about that is styling, and the sentence sends the reader
+         * to look at their design system. An integrator lost nine minutes to
+         * exactly that, on a block whose schema, registry and ops path were all
+         * correct.
+         *
+         * So classify the stripped key. A visual key keeps the original wording,
+         * because that is the case it was written for and the evals that check it
+         * are checking that case. A content key gets a sentence that names it,
+         * which is the one piece of information that ends the search.
+         */
         const byBlockType = new Map();
         for (const entry of hallucinatedProps) {
             const bucket = byBlockType.get(entry.blockType) ?? new Set();
@@ -97,9 +131,16 @@ export function validateAndStripHallucinatedProps(args) {
             byBlockType.set(entry.blockType, bucket);
         }
         const noteParts = [];
-        for (const [blockType] of byBlockType) {
+        for (const [blockType, props] of byBlockType) {
             const name = humanBlockName(blockType);
-            noteParts.push(`Some requested styling isn't available on the ${name} block — applied the supported parts.`);
+            const visual = [...props].filter(isVisualPropName);
+            const content = [...props].filter((prop) => !isVisualPropName(prop));
+            if (visual.length > 0) {
+                noteParts.push(`Some requested styling isn't available on the ${name} block — applied the supported parts.`);
+            }
+            for (const prop of content) {
+                noteParts.push(`The ${name} block has no “${prop}” field, so that part wasn't applied.`);
+            }
         }
         const note = noteParts.join(" ");
         const summary = plan.summary_for_user?.trimEnd() ?? "";

package/dist/cms/adapter.d.ts

@@ -51,6 +51,7 @@ export interface CmsPublishContext {
  */
 export type CmsPublishResult = void | {
     ok: true;
+    written?: boolean;
     unsupported?: string[];
 } | {
     ok: false;

package/dist/handler/create-orchestrator.js

@@ -771,20 +771,31 @@ export function createOrchestrator(config = {}) {
              *
              * This is the copy the bootstrap already took, not a fresh read — a
              * second `getPages()` here is 45 sequential Sanity calls on the
-             * integration that motivated it. It is therefore absent after a restart
-             * that reloaded the draft from SQLite, which is why the contract says to
-             * treat undefined as "no baseline" and never as "the site was empty".
+             * integration that motivated it. It used to be absent for the rest of a
+             * process's life after a restart that reloaded the draft from SQLite,
+             * which quietly disabled publishing for any adapter that refuses without
+             * a baseline; `ensure` now recovers it on the first request instead.
+             *
+             * It can still be undefined — the adapter read can fail, and baselines
+             * are evicted FIFO — so the contract is unchanged: treat undefined as
+             * "no baseline available" and never as "the site was empty".
              */
             const published = runtime.bootstrapCache.baselineFor(scopedSession) ?? undefined;
             const context = body.assets || published
                 ? { ...(body.assets ? { assets: body.assets } : {}), ...(published ? { published } : {}) }
                 : undefined;
             let unsupported = [];
+            // Default true: an adapter that does not mention `written` means what
+            // every adapter written before the field existed meant.
+            let written = true;
             try {
                 const result = await runtime.adapter.onPublish(pages, config, context);
                 if (result && typeof result === "object" && Array.isArray(result.unsupported)) {
                     unsupported = result.unsupported;
                 }
+                if (result && typeof result === "object" && result.ok === true && result.written === false) {
+                    written = false;
+                }
                 if (result && typeof result === "object" && result.ok === false) {
                     const message = result.error ?? "adapter.onPublish returned not-ok";
                     runtime.log.warn({ session: scopedSession, adapter: runtime.adapter.id, error: result.error }, "library-publish: adapter.onPublish() returned not-ok");
@@ -810,13 +821,15 @@ export function createOrchestrator(config = {}) {
              * image beside it — that is neither a plain success, which claims the
              * whole edit shipped, nor an error, which claims none of it did.
              */
-            const summary = buildPublishSummary({ changedSlugs: [], removedSlugs: [], totalPages: pages.length, hasDiff: false });
+            const summary = written
+                ? buildPublishSummary({ changedSlugs: [], removedSlugs: [], totalPages: pages.length, hasDiff: false })
+                : `Computed ${pages.length} ${pages.length === 1 ? "page" : "pages"} — nothing written`;
             record(true, unsupported.length > 0
                 ? `${summary} ${unsupported.length} change${unsupported.length === 1 ? "" : "s"} could not be published.`
                 : summary);
             return jsonResponse({
                 ok: true,
-                written: true,
+                written,
                 count: pages.length,
                 ...(unsupported.length > 0 ? { unsupported } : {})
             }, { status: 200, cors });

package/dist/nlp/deterministic-planner-suggestions.js

@@ -31,7 +31,7 @@ export function promptFromPropKey(propKey, blockType) {
         return CLARIFICATION_LABELS[propKey];
     const human = blockType ? getPropDisplayName(blockType, propKey) : propKey;
     // Fall back to the registry-declared label so host-app overrides (e.g.
-    // villa's TwoColumn adding `sectionId`) surface as "Edit Section id" rather
+    // a host site's TwoColumn adding `sectionId`) surface as "Edit Section id" rather
     // than leaking the raw camelCase key into the UI.
     return human === propKey ? `Edit ${propKey}` : `Edit ${human.toLowerCase()}`;
 }

package/dist/nlp/plan-normalizer.js

@@ -1,6 +1,135 @@
-import { allowedBlockTypes, declaredDefaultPropsForType, defaultPropsForType as sharedDefaultPropsForType } from "@avocadostudio-ai/shared";
+import { allowedBlockTypes, blockSchemas, declaredDefaultPropsForType, defaultPropsForType as sharedDefaultPropsForType, getBlockMeta } from "@avocadostudio-ai/shared";
 import { extractRouteMentions, firstRouteMention, normalizeRouteCandidate, parseCreatePageRequest } from "./intent-helpers.js";
 // ---------------------------------------------------------------------------
+// Prop-name aliasing, asked of the registry rather than of a literal
+// ---------------------------------------------------------------------------
+/*
+ * Models confuse Avocado's own prop names — `heading` for a section that calls
+ * it `title`, `question`/`answer` for FAQ items that call them `q`/`a`. The
+ * aliases below exist to repair that, and they are worth keeping.
+ *
+ * They were applied by comparing the block type against the literal string
+ * "Hero", which is a name only Avocado's own catalogue has. Every other block
+ * in the world is `!== "Hero"`, so a site that brings its own blocks and names
+ * a text prop `heading` had that prop deleted here and replaced with `title` —
+ * a prop its schema does not have. The ops engine then stripped `title` as a
+ * hallucinated prop, the edit vanished, and the user was told that "some
+ * requested styling isn't available" on their block. Nothing in the chain was
+ * wrong about its own job; the first link was answering a question about a name
+ * instead of about a schema.
+ *
+ * So ask the registry. A rename now requires positive evidence in both
+ * directions: the block cannot take the key the planner used, and can take the
+ * one we would rewrite it to. Every other case — unknown block type, a block
+ * that accepts both, a block that accepts neither — leaves the value alone,
+ * which is the answer that loses no data.
+ */
+function blockAcceptsProp(blockType, prop) {
+    if (!blockType)
+        return false;
+    const meta = getBlockMeta(blockType);
+    if (meta?.fields && prop in meta.fields)
+        return true;
+    // Manifest-registered blocks may carry a schema richer than their derived
+    // meta, so the schema gets the second look rather than the first refusal.
+    const shape = blockSchemas[blockType]?.shape;
+    return Boolean(shape && prop in shape);
+}
+/*
+ * Avocado's own `autoplay` / `loop` / `striped` are string enums ("true" /
+ * "false"), not booleans, so a model that emits a real boolean has to be
+ * coerced. That coercion ran on every block type, and a custom block whose
+ * `loop` is a genuine `z.boolean()` had the string `"true"` written into it —
+ * silently, and only on the chat path, so it looked like a CMS problem.
+ *
+ * Coerce only where the block actually declares the prop as a string enum.
+ */
+const BOOLEAN_ENUM_PROPS = ["autoplay", "loop", "striped"];
+/**
+ * Ask the block's own schema, which is the only thing that actually knows:
+ * rewrite a boolean to `"true"`/`"false"` exactly when the schema rejects the
+ * boolean and accepts the string. A block that takes a real boolean keeps it,
+ * a block that takes either keeps what the planner sent, and an unregistered
+ * type is left alone.
+ */
+function coerceBooleanEnumProps(blockType, props) {
+    const shape = blockSchemas[blockType]?.shape;
+    if (!shape)
+        return;
+    for (const key of BOOLEAN_ENUM_PROPS) {
+        const value = props[key];
+        if (typeof value !== "boolean")
+            continue;
+        const field = shape[key];
+        if (typeof field?.safeParse !== "function")
+            continue;
+        const asString = value ? "true" : "false";
+        /*
+         * Round-trip, not merely "parses". Avocado's own `autoplay` is
+         * `z.enum(["true","false"]).default("false").catch("false")`, and `.catch`
+         * means a boolean parses *successfully* — into the wrong value. Accepting
+         * that as "the block wants a boolean" would leave the silent wrong answer
+         * in place. A schema genuinely wants a boolean only when it gives the
+         * boolean back unchanged.
+         */
+        const asBool = field.safeParse(value);
+        if (asBool.success && asBool.data === value)
+            continue;
+        const asStr = field.safeParse(asString);
+        if (!asStr.success || asStr.data !== asString)
+            continue;
+        props[key] = asString;
+    }
+}
+/** Rename `from`→`to` only when the block demonstrably wants `to` and not `from`. */
+function shouldAliasProp(blockType, from, to) {
+    return !blockAcceptsProp(blockType, from) && blockAcceptsProp(blockType, to);
+}
+/*
+ * The same question for a key inside a list item. `listFields[key].itemFields`
+ * is the declared shape; a block with no declared list metadata answers "no"
+ * to both halves and is therefore left alone.
+ */
+function listItemAcceptsKey(blockType, listKey, itemKey) {
+    if (!blockType)
+        return false;
+    const itemFields = getBlockMeta(blockType)?.listFields?.[listKey]?.itemFields;
+    return Boolean(itemFields && itemKey in itemFields);
+}
+function shouldAliasItemKey(blockType, listKey, from, to) {
+    return (!listItemAcceptsKey(blockType, listKey, from) && listItemAcceptsKey(blockType, listKey, to));
+}
+const ITEM_KEY_ALIASES = {
+    question: "q",
+    answer: "a",
+    testimonial: "quote",
+    review: "quote"
+};
+/**
+ * Apply the list-item aliases to one array prop, block-type aware.
+ * Shared by the `update_props` and `add_block` paths so they cannot drift.
+ */
+function aliasListItems(blockType, listKey, value) {
+    return value.map((item) => {
+        if (!item || typeof item !== "object" || Array.isArray(item))
+            return item;
+        const entry = item;
+        let changed = false;
+        const mapped = {};
+        for (const [k, v] of Object.entries(entry)) {
+            const alias = ITEM_KEY_ALIASES[k.toLowerCase()];
+            if (alias && !(alias in entry) && shouldAliasItemKey(blockType, listKey, k.toLowerCase(), alias)) {
+                mapped[alias] = v;
+                changed = true;
+            }
+            else {
+                mapped[k] = v;
+            }
+        }
+        return changed ? mapped : entry;
+    });
+}
+// ---------------------------------------------------------------------------
 // Op reordering: create_page must precede ops targeting the same slug
 // ---------------------------------------------------------------------------
 function reorderCreatePageFirst(ops) {
@@ -886,38 +1015,17 @@ export function normalizePlanCandidate(input, args) {
             const patch = raw.patch;
             const targetBlock = args?.currentPage?.blocks.find((b) => b.id === raw.blockId);
             const blockType = targetBlock?.type ?? "";
-            if (blockType !== "Hero" && "heading" in patch && !("title" in patch)) {
+            if ("heading" in patch && !("title" in patch) && shouldAliasProp(blockType, "heading", "title")) {
                 patch.title = patch.heading;
                 delete patch.heading;
             }
-            const itemKeyAliases = { question: "q", answer: "a", testimonial: "quote", review: "quote" };
             for (const [propKey, propVal] of Object.entries(patch)) {
                 if (!Array.isArray(propVal))
                     continue;
-                patch[propKey] = propVal.map((item) => {
-                    if (!item || typeof item !== "object" || Array.isArray(item))
-                        return item;
-                    const entry = item;
-                    let changed = false;
-                    const mapped = {};
-                    for (const [k, v] of Object.entries(entry)) {
-                        const alias = itemKeyAliases[k.toLowerCase()];
-                        if (alias && !(alias in entry)) {
-                            mapped[alias] = v;
-                            changed = true;
-                        }
-                        else {
-                            mapped[k] = v;
-                        }
-                    }
-                    return changed ? mapped : entry;
-                });
+                patch[propKey] = aliasListItems(blockType, propKey, propVal);
             }
             // Block-specific prop key remapping and type coercion (mirrors add_block path)
-            for (const k of ["autoplay", "loop", "striped"]) {
-                if (typeof patch[k] === "boolean")
-                    patch[k] = patch[k] ? "true" : "false";
-            }
+            coerceBooleanEnumProps(blockType, patch);
             if (blockType === "Carousel" && Array.isArray(patch.slides) && !patch.items) {
                 patch.items = patch.slides;
                 delete patch.slides;
@@ -1153,36 +1261,20 @@ export function normalizePlanCandidate(input, args) {
             if (block.props && typeof block.props === "object" && !Array.isArray(block.props)) {
                 const bProps = block.props;
                 const blockType = typeof block.type === "string" ? block.type : "";
-                if (blockType !== "Hero" && "heading" in bProps && !("title" in bProps)) {
+                if ("heading" in bProps && !("title" in bProps) && shouldAliasProp(blockType, "heading", "title")) {
                     bProps.title = bProps.heading;
                     delete bProps.heading;
                 }
             }
-            // Remap list item keys inside add_block props (e.g., question→q, answer→a)
+            // Remap list item keys inside add_block props (e.g., question→q, answer→a),
+            // asking the block's own list metadata rather than rewriting every array.
             if (block.props && typeof block.props === "object" && !Array.isArray(block.props)) {
                 const bProps = block.props;
-                const itemKeyAliases = { question: "q", answer: "a", testimonial: "quote", review: "quote" };
+                const blockType = typeof block.type === "string" ? block.type : "";
                 for (const [propKey, propVal] of Object.entries(bProps)) {
                     if (!Array.isArray(propVal))
                         continue;
-                    bProps[propKey] = propVal.map((item) => {
-                        if (!item || typeof item !== "object" || Array.isArray(item))
-                            return item;
-                        const entry = item;
-                        let changed = false;
-                        const mapped = {};
-                        for (const [k, v] of Object.entries(entry)) {
-                            const alias = itemKeyAliases[k.toLowerCase()];
-                            if (alias && !(alias in entry)) {
-                                mapped[alias] = v;
-                                changed = true;
-                            }
-                            else {
-                                mapped[k] = v;
-                            }
-                        }
-                        return changed ? mapped : entry;
-                    });
+                    bProps[propKey] = aliasListItems(blockType, propKey, propVal);
                 }
             }
             // Block-specific prop key remapping and type coercion
@@ -1190,10 +1282,7 @@ export function normalizePlanCandidate(input, args) {
                 const cProps = block.props;
                 const bt = block.type;
                 // Coerce boolean→string for "true"/"false" enum props (Carousel, Video, Table)
-                for (const k of ["autoplay", "loop", "striped"]) {
-                    if (typeof cProps[k] === "boolean")
-                        cProps[k] = cProps[k] ? "true" : "false";
-                }
+                coerceBooleanEnumProps(typeof bt === "string" ? bt : "", cProps);
                 // Carousel: slides→items
                 if (bt === "Carousel" && Array.isArray(cProps.slides) && !cProps.items) {
                     cProps.items = cProps.slides;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/orchestrator-core",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
@@ -23,8 +23,8 @@
     "openai": "^4.87.1",
     "sharp": "^0.34.5",
     "zod": "^4.3.6",
-    "@avocadostudio-ai/migration-sdk": "^0.3.1",
-    "@avocadostudio-ai/shared": "^0.3.1"
+    "@avocadostudio-ai/migration-sdk": "^0.3.2",
+    "@avocadostudio-ai/shared": "^0.3.2"
   },
   "devDependencies": {
     "@google/genai": "^1.46.0",