@cosmicdrift/kumiko-framework 0.334.0 → 0.336.0

package/dist/engine/build-config-feature-schema.js

@@ -16,6 +16,7 @@
 // ids/parent/screen-Refs (buildNavRegistrySliceForApp qualifiziert selbst).
 import { isOptionsQueryFieldRef } from "@cosmicdrift/kumiko-types/fields";
 import { CONFIG_EDIT_ENTITY, fieldLabelKey } from "../i18n/required-surface-keys.js";
+import { isEncryptedAtRest } from "./config-helpers.js";
 import { EXTENSION_SELECTOR_HINT_KEY, SELECTED_EXTENSIONS_QUERY, selectablePluginIds, } from "./extension-selector-plugins.js";
 import { createBooleanField, createNumberField, createSelectField, createTextField, } from "./factories.js";
 import { isKebabSegment, toKebab } from "./qualified-name.js";
@@ -619,7 +620,13 @@ function deriveField(key, selectorPluginIds, screenKeys, fieldIdOf) {
                 ? createSelectField({ options: def.options })
                 : createTextField({ personal: false, reason: "system_metadata" });
         default:
-            return createTextField({ personal: false, reason: "system_metadata" });
+            // A stored secret never goes back to the client: the form shows set/empty
+            // and sends only a replacement or a clear.
+            return createTextField({
+                personal: false,
+                reason: "system_metadata",
+                ...(def.type === "text" && isEncryptedAtRest(def) && { writeOnly: true }),
+            });
     }
 }
 function collectMaskedKeys(registry) {

package/dist/engine/changeset-changes.js

@@ -54,25 +54,35 @@ function parseBlock(raw, source) {
 function proseWithoutMetadata(markdown) {
     const withoutFrontmatter = markdown.replace(/^\s*---\n[\s\S]*?\n---\s*/, "");
     return withoutFrontmatter
-        .replace(BLOCK_RE, "")
         .split("\n")
         .map((line) => line.trim())
         .filter((line) => line !== "");
 }
+function sameTitle(title, line) {
+    const normalize = (text) => text.replace(/[.\s]+$/, "").toLowerCase();
+    return line !== undefined && normalize(title) === normalize(line);
+}
+// BLOCK_RE closes at the first line starting with "-->"; text after it on
+// that line means a field value contained one and the block ended early.
+function assertBlockNotClosedEarly(markdown, match, source) {
+    const restOfLine = markdown.slice(match.index + match[0].length).split("\n", 1)[0] ?? "";
+    if (restOfLine.trim() !== "") {
+        throw new Error(`${source}: kumiko-changes block closed early by a line starting with "-->"; field values must not contain such a line`);
+    }
+}
 /** Parse structured upgrade metadata embedded in a Changeset body. */
 export function parseChangesetChanges(markdown, source) {
     const changes = [];
-    const prose = proseWithoutMetadata(markdown);
+    // Each block only inherits prose from the markdown between the previous block
+    // and itself; document-wide prose would give two features the same title.
+    let segmentStart = 0;
     BLOCK_RE.lastIndex = 0;
     let match = BLOCK_RE.exec(markdown);
     while (match !== null) {
         const block = match[1];
-        // BLOCK_RE closes at the first line starting with "-->"; text after it on
-        // that line means a field value contained one and the block ended early.
-        const restOfLine = markdown.slice(match.index + match[0].length).split("\n", 1)[0] ?? "";
-        if (restOfLine.trim() !== "") {
-            throw new Error(`${source}: kumiko-changes block closed early by a line starting with "-->"; field values must not contain such a line`);
-        }
+        const prose = proseWithoutMetadata(markdown.slice(segmentStart, match.index));
+        segmentStart = match.index + match[0].length;
+        assertBlockNotClosedEarly(markdown, match, source);
         if (!block)
             throw new Error(`${source}: empty kumiko-changes block`);
         const fields = parseBlock(block, source);
@@ -81,12 +91,16 @@ export function parseChangesetChanges(markdown, source) {
         if (!TYPE_VALUES.has(rawType)) {
             throw new Error(`${source}: kumiko-changes type must be breaking, improvement, or fix`);
         }
-        const title = fields.get("title")?.trim() || prose[0];
+        const explicitTitle = fields.get("title")?.trim();
+        const title = explicitTitle || prose[0];
         if (!title)
             throw new Error(`${source}: kumiko-changes title is required`);
+        // The first prose line is the title's source only when no title was given or
+        // the explicit one restates it; otherwise it is genuine detail.
+        const firstLineIsTitle = !explicitTitle || sameTitle(explicitTitle, prose[0]);
         const detail = fields.get("detail")?.trim() ||
             prose
-                .slice(prose.length > 0 ? 1 : 0)
+                .slice(firstLineIsTitle ? 1 : 0)
                 .join("\n")
                 .trim();
         const migration = fields.get("migration")?.trim();

package/dist/engine/create-app.js

@@ -17,7 +17,16 @@ function inlineFormFieldMaps(screen) {
 function validateLiteralCurrencyCode(where, field, currencies) {
     // @cast-boundary schema-walk — feature-config inspection (Author may circumvent type-check)
     const shape = field;
-    if (shape.type === "money" && shape.currency?.kind === "literal") {
+    // skip: not a money field, or no currency source declared; nothing to validate.
+    if (shape.type !== "money" || shape.currency === undefined)
+        return;
+    // An unknown kind would project through to the renderer, which silently falls
+    // back to entity.defaultCurrency instead of failing.
+    if (shape.currency.kind !== "literal" && shape.currency.kind !== "tenant") {
+        throw new Error(`${where} declares an unknown currency kind ${JSON.stringify(shape.currency.kind)}. ` +
+            `Expected { kind: "tenant" } or { kind: "literal", code }.`);
+    }
+    if (shape.currency.kind === "literal") {
         const code = shape.currency.code;
         if (typeof code !== "string" || !currencies.includes(code)) {
             throw new Error(`${where} declares currency: { kind: "literal", code: ${JSON.stringify(code)} } which is ` +

package/dist/engine/extension-names.d.ts

@@ -101,6 +101,10 @@ export declare const EXT_DERIVATIVE_PUBLIC_PREDICATE: "derivativePublicPredicate
  * an image silently rendered without its QR would look correct while being
  * wrong.
  *
+ * `resolve()` runs on every `variant()` call — including cache hits on the
+ * anonymous public route — because the spec hash needs the resolved value.
+ * It must be cheap or cache its own lookups.
+ *
  * Registered/consumed by: `file-derivatives`'s `variant()`
  * (derivatives-context.ts), before the variant's spec hash is computed.
  */

package/dist/engine/extension-names.js

@@ -130,6 +130,10 @@ export const EXT_DERIVATIVE_PUBLIC_PREDICATE = "derivativePublicPredicate";
  * an image silently rendered without its QR would look correct while being
  * wrong.
  *
+ * `resolve()` runs on every `variant()` call — including cache hits on the
+ * anonymous public route — because the spec hash needs the resolved value.
+ * It must be cheap or cache its own lookups.
+ *
  * Registered/consumed by: `file-derivatives`'s `variant()`
  * (derivatives-context.ts), before the variant's spec hash is computed.
  */

package/dist/engine/feature-ast/extractors/events.js

@@ -61,6 +61,12 @@ function extractEventMigrationsField(node, sourceFile) {
             : undefined;
     return result && Object.keys(result).length > 0 ? result : undefined;
 }
+// `{ piiFields }` shorthand is a valid stance; its name node doubles as the location.
+function readPiiFieldsNode(obj) {
+    const prop = obj?.getProperty("piiFields");
+    return (prop?.asKind(SyntaxKind.PropertyAssignment)?.getInitializer() ??
+        prop?.asKind(SyntaxKind.ShorthandPropertyAssignment)?.getNameNode());
+}
 export function extractDefineEvent(call, sourceFile) {
     const args = call.getArguments();
     const first = args[0];
@@ -94,10 +100,7 @@ export function extractDefineEvent(call, sourceFile) {
             if (typeof v === "number")
                 version = v;
         }
-        const piiFieldsInit = obj
-            .getProperty("piiFields")
-            ?.asKind(SyntaxKind.PropertyAssignment)
-            ?.getInitializer();
+        const piiFieldsInit = readPiiFieldsNode(obj);
         if (!piiFieldsInit) {
             return fail("defineEvent", sourceLocationFromNode(call, sourceFile), 'requires an explicit `piiFields` stance (an object literal or "none")');
         }
@@ -130,11 +133,11 @@ export function extractDefineEvent(call, sourceFile) {
     let migrations;
     const optionsArg = args[2];
     const optionsObj = optionsArg?.asKind(SyntaxKind.ObjectLiteralExpression);
-    const piiFieldsInit = optionsObj
-        ?.getProperty("piiFields")
-        ?.asKind(SyntaxKind.PropertyAssignment)
-        ?.getInitializer();
+    const piiFieldsInit = readPiiFieldsNode(optionsObj);
     if (!piiFieldsInit) {
+        if (optionsArg && !optionsObj) {
+            return fail("defineEvent", sourceLocationFromNode(call, sourceFile), "options must be an object literal");
+        }
         return fail("defineEvent", sourceLocationFromNode(call, sourceFile), 'requires an explicit `piiFields` stance (an object literal or "none")');
     }
     if (optionsObj) {

package/dist/engine/feature-ast/extractors/handlers.js

@@ -44,6 +44,7 @@ const QUERY_HANDLER_KEY_KINDS = {
     agent: "modeled",
     rateLimit: "modeled",
     outputSchema: "opaque",
+    liveEntities: "opaque",
     escapeHatch: "modeled",
 };
 const STREAM_HANDLER_KEY_KINDS = {
@@ -62,6 +63,28 @@ const HANDLER_KEY_KINDS = {
 function lookupClassification(map, key) {
     return key in map ? map[key] : undefined;
 }
+function isStaticStringNode(node) {
+    const kind = node.getKind();
+    return kind === SyntaxKind.StringLiteral || kind === SyntaxKind.NoSubstitutionTemplateLiteral;
+}
+function isBooleanLiteralNode(node) {
+    const kind = node.getKind();
+    return kind === SyntaxKind.TrueKeyword || kind === SyntaxKind.FalseKeyword;
+}
+// The literal readers below only understand a static string `description` and
+// a true/false `unsafeSkipTransitionGuard`; any other value shape is lossy.
+function hasUnreadableLiteralValue(key, initializer) {
+    if (key === "description")
+        return !(initializer && isStaticStringNode(initializer));
+    if (key === "unsafeSkipTransitionGuard")
+        return !(initializer && isBooleanLiteralNode(initializer));
+    return false;
+}
+function readStaticStringProperty(obj, key) {
+    const initializer = obj.getProperty(key)?.asKind(SyntaxKind.PropertyAssignment)?.getInitializer();
+    return (initializer?.asKind(SyntaxKind.StringLiteral) ??
+        initializer?.asKind(SyntaxKind.NoSubstitutionTemplateLiteral))?.getLiteralValue();
+}
 // True when the call's object body/options carry a shape the extractor
 // cannot losslessly model property-by-property (a spread, a method/accessor
 // shorthand, a computed key, or a key outside the classification map above).
@@ -76,13 +99,21 @@ function hasUnmodeledShape(obj, methodName) {
         if (propAssign) {
             if (propAssign.getNameNode().getKind() === SyntaxKind.ComputedPropertyName)
                 return true;
-            if (lookupClassification(keyKinds, readPropertyKey(propAssign)) !== "modeled")
+            const key = readPropertyKey(propAssign);
+            if (lookupClassification(keyKinds, key) !== "modeled")
+                return true;
+            const initializer = propAssign.getInitializer();
+            if (hasUnreadableLiteralValue(key, initializer))
                 return true;
             continue;
         }
         const shorthand = prop.asKind(SyntaxKind.ShorthandPropertyAssignment);
         if (shorthand) {
-            if (lookupClassification(keyKinds, shorthand.getName()) !== "modeled")
+            const key = shorthand.getName();
+            if (lookupClassification(keyKinds, key) !== "modeled")
+                return true;
+            // A shorthand's value is invisible to the literal readers below.
+            if (key === "description" || key === "unsafeSkipTransitionGuard")
                 return true;
             continue;
         }
@@ -197,11 +228,7 @@ export function parseHandlerCall(call, sourceFile, methodName) {
         const headerResult = readHandlerHeaderFields(obj, methodName, sourceFile);
         if (headerResult.kind === "error")
             return headerResult;
-        const descriptionLiteral = obj
-            .getProperty("description")
-            ?.asKind(SyntaxKind.PropertyAssignment)
-            ?.getInitializer()
-            ?.asKind(SyntaxKind.StringLiteral);
+        const description = readStaticStringProperty(obj, "description");
         const skip = readBooleanProperty(obj, "unsafeSkipTransitionGuard");
         return ok({
             source: sourceLocationFromNode(call, sourceFile),
@@ -209,9 +236,7 @@ export function parseHandlerCall(call, sourceFile, methodName) {
             schemaSource: sourceLocationFromNode(schemaInit, sourceFile),
             handlerBody: sourceLocationFromNode(fn, sourceFile),
             ...headerResult.pattern,
-            ...(descriptionLiteral !== undefined && {
-                description: descriptionLiteral.getLiteralValue(),
-            }),
+            ...(description !== undefined && { description }),
             ...(skip === true && { unsafeSkipTransitionGuard: true }),
         });
     }
@@ -244,6 +269,7 @@ export function parseHandlerCall(call, sourceFile, methodName) {
     const optionsArg = args[3];
     let headerFields = {};
     let description;
+    let skipTransitionGuard;
     if (optionsArg) {
         const optionsObj = unwrapObjectLiteral(optionsArg);
         if (!optionsObj || hasUnmodeledShape(optionsObj, methodName)) {
@@ -253,12 +279,8 @@ export function parseHandlerCall(call, sourceFile, methodName) {
         if (headerResult.kind === "error")
             return headerResult;
         headerFields = headerResult.pattern;
-        description = optionsObj
-            .getProperty("description")
-            ?.asKind(SyntaxKind.PropertyAssignment)
-            ?.getInitializer()
-            ?.asKind(SyntaxKind.StringLiteral)
-            ?.getLiteralValue();
+        description = readStaticStringProperty(optionsObj, "description");
+        skipTransitionGuard = readBooleanProperty(optionsObj, "unsafeSkipTransitionGuard");
     }
     return ok({
         source: sourceLocationFromNode(call, sourceFile),
@@ -267,6 +289,7 @@ export function parseHandlerCall(call, sourceFile, methodName) {
         handlerBody: sourceLocationFromNode(fn, sourceFile),
         ...headerFields,
         ...(description !== undefined && { description }),
+        ...(skipTransitionGuard === true && { unsafeSkipTransitionGuard: true }),
     });
 }
 export function extractWriteHandler(call, sourceFile) {

package/dist/engine/feature-ast/extractors/resolve-import.d.ts

@@ -1,4 +1,5 @@
-import type { Node, SourceFile, VariableDeclaration } from "ts-morph";
+import type { SourceFile, VariableDeclaration } from "ts-morph";
+import { Node } from "ts-morph";
 export declare function resolveModuleFile(fromFile: SourceFile, specifier: string): SourceFile | undefined;
 export declare function findImportBindingForLocalName(sourceFile: SourceFile, localName: string): {
     readonly moduleSpecifier: string;
@@ -10,5 +11,9 @@ export declare function findImportBindingForLocalName(sourceFile: SourceFile, lo
  * the cycle guard; `depth` backstops pathological non-cyclic chains.
  */
 export declare function resolveExportedVariable(file: SourceFile, exportedName: string, visited?: Set<string>, depth?: number): VariableDeclaration | undefined;
-/** A function parameter of the same name shadows and stops the search — it has no statically readable initializer. */
+/**
+ * Any binding of the same name that is not a plain `const NAME = <init>`
+ * (parameter, destructuring, loop variable, catch variable) shadows and ends
+ * the search — it has no statically readable initializer.
+ */
 export declare function findScopedVariableDeclaration(identifier: Node, name: string): VariableDeclaration | undefined;

package/dist/engine/feature-ast/extractors/resolve-import.js

@@ -1,4 +1,4 @@
-import { SyntaxKind, ts } from "ts-morph";
+import { Node, SyntaxKind, ts } from "ts-morph";
 const MODULE_RESOLUTION_OPTIONS = {
     moduleResolution: ts.ModuleResolutionKind.Bundler,
     module: ts.ModuleKind.ESNext,
@@ -112,11 +112,14 @@ function resolveViaStarExport(file, exportedName, visited, depth) {
     }
     return undefined;
 }
-/** A function parameter of the same name shadows and stops the search — it has no statically readable initializer. */
+/**
+ * Any binding of the same name that is not a plain `const NAME = <init>`
+ * (parameter, destructuring, loop variable, catch variable) shadows and ends
+ * the search — it has no statically readable initializer.
+ */
 export function findScopedVariableDeclaration(identifier, name) {
     for (const ancestor of [identifier, ...identifier.getAncestors()]) {
-        const params = getShadowingParameters(ancestor);
-        if (params?.some((p) => p.getName() === name))
+        if (declaresShadowingBinding(ancestor, name))
             return undefined;
         const statements = getDirectStatements(ancestor);
         if (!statements)
@@ -125,21 +128,45 @@ export function findScopedVariableDeclaration(identifier, name) {
             const varStmt = stmt.asKind(SyntaxKind.VariableStatement);
             if (!varStmt)
                 continue;
-            const decl = varStmt
-                .getDeclarationList()
-                .getDeclarations()
-                .find((d) => d.getName() === name);
-            if (decl)
-                return decl;
+            for (const decl of varStmt.getDeclarationList().getDeclarations()) {
+                const nameNode = decl.getNameNode();
+                if (Node.isIdentifier(nameNode)) {
+                    if (nameNode.getText() === name)
+                        return decl;
+                }
+                else if (bindingNames(nameNode).includes(name)) {
+                    return undefined;
+                }
+            }
         }
     }
     return undefined;
 }
-function getShadowingParameters(node) {
-    const fn = node.asKind(SyntaxKind.ArrowFunction) ??
-        node.asKind(SyntaxKind.FunctionExpression) ??
-        node.asKind(SyntaxKind.FunctionDeclaration);
-    return fn?.getParameters();
+function bindingNames(nameNode) {
+    if (Node.isIdentifier(nameNode))
+        return [nameNode.getText()];
+    if (Node.isObjectBindingPattern(nameNode) || Node.isArrayBindingPattern(nameNode)) {
+        return nameNode
+            .getElements()
+            .flatMap((element) => Node.isBindingElement(element) ? bindingNames(element.getNameNode()) : []);
+    }
+    return [];
+}
+function declaresShadowingBinding(node, name) {
+    if (Node.isParametered(node)) {
+        return node.getParameters().some((p) => bindingNames(p.getNameNode()).includes(name));
+    }
+    if (Node.isForOfStatement(node) || Node.isForInStatement(node) || Node.isForStatement(node)) {
+        const initializer = node.getInitializer();
+        return (initializer !== undefined &&
+            Node.isVariableDeclarationList(initializer) &&
+            initializer.getDeclarations().some((decl) => bindingNames(decl.getNameNode()).includes(name)));
+    }
+    if (Node.isCatchClause(node)) {
+        const decl = node.getVariableDeclaration();
+        return decl !== undefined && bindingNames(decl.getNameNode()).includes(name);
+    }
+    return false;
 }
 function getDirectStatements(node) {
     const block = node.asKind(SyntaxKind.Block);

package/dist/engine/feature-ast/parse.d.ts

@@ -28,3 +28,4 @@ export declare function parseFeatureFile(filePath: string): ParseResult;
  * instance and avoids re-IO per parse).
  */
 export declare function parseSourceFile(sourceFile: SourceFile): ParseResult;
+export declare function relativePosixPath(fromDirectory: string, filePath: string): string;

package/dist/engine/feature-ast/parse.js

@@ -68,16 +68,31 @@ export function parseSourceFile(sourceFile) {
     const errors = [];
     walkSetupCallback(setupCallback.getBody(), registrarParamName, sourceFile, patterns, errors);
     walkAiStepCalls(setupCallback.getBody(), registrarParamName, sourceFile, patterns, errors);
-    // Tie-break on filePath so cross-file registrar wrappers don't interleave by
-    // foreign line numbers alone.
+    // Tie-break on the path relative to the entry file's directory so cross-file
+    // registrar wrappers don't interleave by foreign line numbers alone, without
+    // the order depending on where the repo is checked out (worktrees).
+    const parseRoot = sourceFile.getDirectoryPath();
     patterns.sort((a, b) => {
-        const fileCmp = a.source.file.localeCompare(b.source.file);
+        const fileCmp = relativePosixPath(parseRoot, a.source.file).localeCompare(relativePosixPath(parseRoot, b.source.file));
         if (fileCmp !== 0)
             return fileCmp;
         return a.source.start.line - b.source.start.line;
     });
     return { featureName, patterns, errors };
 }
+// node:path is avoided: the Designer runs this against an in-memory file
+// system outside Node. ts-morph paths are always posix-style.
+export function relativePosixPath(fromDirectory, filePath) {
+    const fromSegments = fromDirectory.split("/").filter(Boolean);
+    const fileSegments = filePath.split("/").filter(Boolean);
+    let common = 0;
+    while (common < fromSegments.length &&
+        common < fileSegments.length - 1 &&
+        fromSegments[common] === fileSegments[common]) {
+        common += 1;
+    }
+    return [...fromSegments.slice(common).map(() => ".."), ...fileSegments.slice(common)].join("/");
+}
 // =============================================================================
 // Internal — locate defineFeature + setup callback
 // =============================================================================

package/dist/engine/feature-ast/patch.js

@@ -33,7 +33,7 @@
 // roadmap C-Notes for the canonical-comment-attach Pattern that would
 // preserve prefixed `// kumiko-comment:` markers across roundtrips.
 import { SyntaxKind, } from "ts-morph";
-import { readNameLiteral, readNameOrRef, resolveSameFileObjectLiteral, } from "./extractors/shared.js";
+import { readNameLiteral, readNameOrRef, readPropertyKey, resolveSameFileObjectLiteral, } from "./extractors/shared.js";
 import { indent, PATTERN_INDENT, renderPattern, renderValue } from "./render.js";
 /**
  * Apply a sequence of changes to the source file in-place. The list is
@@ -202,33 +202,22 @@ const HEADER_KEY_FLAGS_BY_HANDLER_KIND = {
     queryHandler: QUERY_HANDLER_HEADER_KEY_FLAGS,
     streamHandler: STREAM_HANDLER_HEADER_KEY_FLAGS,
 };
-function propertyName(prop) {
-    const assign = prop.asKind(SyntaxKind.PropertyAssignment);
-    if (assign)
-        return readNameLiteral(assign.getNameNode()) ?? assign.getNameNode().getText();
-    const shorthand = prop.asKind(SyntaxKind.ShorthandPropertyAssignment);
-    if (shorthand)
-        return shorthand.getName();
-    return undefined;
+function lastProperty(obj) {
+    return obj.getProperties().at(-1);
 }
-// Append after the literal's last property, skipping any property this
-// same change is about to unset — avoids interleaving the two edits' spans.
-function lastRemainingProperty(obj, unsetKeys) {
-    const props = obj.getProperties();
-    for (let i = props.length - 1; i >= 0; i--) {
-        const prop = props[i];
-        if (prop === undefined)
-            continue;
-        const name = propertyName(prop);
-        if (name !== undefined && unsetKeys.has(name))
-            continue;
-        return prop;
-    }
-    return undefined;
+// ts-morph's getProperty(name) keeps the quotes of string-literal keys, so `"description": x` would never match `description`.
+function findPropertyByKey(obj, key) {
+    return obj.getProperties().find((prop) => {
+        const assign = prop.asKind(SyntaxKind.PropertyAssignment);
+        if (assign)
+            return readPropertyKey(assign) === key;
+        return prop.asKind(SyntaxKind.ShorthandPropertyAssignment)?.getName() === key;
+    });
 }
-function buildSetEdit(obj, key, value, unsetKeys) {
+// Replaces the value of an already-present key; undefined when the key is missing.
+function buildInPlaceSetEdit(obj, key, value) {
     const sourceFile = obj.getSourceFile();
-    const existing = obj.getProperty(key);
+    const existing = findPropertyByKey(obj, key);
     const assign = existing?.asKind(SyntaxKind.PropertyAssignment);
     if (assign) {
         const init = assign.getInitializer();
@@ -248,28 +237,28 @@ function buildSetEdit(obj, key, value, unsetKeys) {
             text: `${key}: ${renderValue(value, col - 1)}`,
         };
     }
-    const last = lastRemainingProperty(obj, unsetKeys);
+    return undefined;
+}
+// All missing keys go into ONE edit: separate edits would share the same
+// anchor position and depend on apply order and trailing-comma luck.
+function buildAppendEdit(obj, entries) {
+    const sourceFile = obj.getSourceFile();
+    const last = lastProperty(obj);
     const fullText = sourceFile.getFullText();
     const isSingleLineLiteral = !obj.getText().includes("\n");
     if (!last) {
-        // Empty (or fully-unset) literal — insert right after the opening brace.
+        // Empty literal — insert right after the opening brace.
         const openBrace = obj.getFirstChildByKindOrThrow(SyntaxKind.OpenBraceToken);
-        return {
-            start: openBrace.getEnd(),
-            end: openBrace.getEnd(),
-            text: ` ${key}: ${renderValue(value, 0)} `,
-        };
+        const joined = entries.map(([key, value]) => `${key}: ${renderValue(value, 0)}`).join(", ");
+        return { start: openBrace.getEnd(), end: openBrace.getEnd(), text: ` ${joined} ` };
     }
     if (isSingleLineLiteral) {
         let pos = last.getEnd();
         const hasComma = fullText[pos] === ",";
         if (hasComma)
             pos++;
-        return {
-            start: pos,
-            end: pos,
-            text: `${hasComma ? "" : ","} ${key}: ${renderValue(value, 0)}`,
-        };
+        const joined = entries.map(([key, value]) => `${key}: ${renderValue(value, 0)}`).join(", ");
+        return { start: pos, end: pos, text: `${hasComma ? "" : ","} ${joined}` };
     }
     const col = sourceFile.getLineAndColumnAtPos(last.getStart()).column;
     const indentStr = " ".repeat(col - 1);
@@ -285,13 +274,12 @@ function buildSetEdit(obj, key, value, unsetKeys) {
         // appending here would land after it. Narrower than replace; bail.
         throw new Error("updatePattern: cannot append a header field — the handler literal's last property shares a line with other code; use replace");
     }
+    const appended = entries
+        .map(([key, value]) => `\n${indentStr}${key}: ${renderValue(value, col - 1)},`)
+        .join("");
     // Reconstruct the comma here (not inserted after the value) so it lands
     // right after the value, never inside a trailing `//` comment.
-    return {
-        start: valueEnd,
-        end: lineEndPos,
-        text: `,${restOfLine}\n${indentStr}${key}: ${renderValue(value, col - 1)},`,
-    };
+    return { start: valueEnd, end: lineEndPos, text: `,${restOfLine}${appended}` };
 }
 // Whole-line delete: property was alone on its line (with its indentation
 // and trailing newline) — used when nothing else shares that line.
@@ -322,7 +310,7 @@ function buildInlineUnsetEdit(text, propStart, afterPos, hasTrailingComma) {
     return { start, end, text: "" };
 }
 function buildUnsetEdit(obj, key) {
-    const prop = obj.getProperty(key);
+    const prop = findPropertyByKey(obj, key);
     if (!prop)
         return undefined; // no-op: nothing to remove, unset is idempotent
     const sourceFile = obj.getSourceFile();
@@ -346,12 +334,7 @@ function buildUnsetEdit(obj, key) {
         return buildWholeLineUnsetEdit(sourceFile, lineStartPos, afterPos);
     return buildInlineUnsetEdit(text, propStart, afterPos, hasTrailingComma);
 }
-/**
- * Apply a `HandlerHeaderUpdate` to the header fields named in `set`/`unset`
- * only, via targeted text edits — `schemaSource`, `handlerBody`, comments,
- * and every unnamed field stay byte-identical (narrower than replacePattern).
- */
-export function updatePattern(sourceFile, change) {
+function resolveUpdatableHandlerLiteral(sourceFile, change) {
     const call = findCallForId(sourceFile, change.id);
     if (!call) {
         throw new Error(`updatePattern: no call found for ${describeId(change.id)}`);
@@ -371,6 +354,15 @@ export function updatePattern(sourceFile, change) {
     if (obj.getProperties().some((prop) => prop.isKind(SyntaxKind.SpreadAssignment))) {
         throw new Error("updatePattern: cannot update a handler literal containing a spread; use replace");
     }
+    return obj;
+}
+/**
+ * Apply a `HandlerHeaderUpdate` to the header fields named in `set`/`unset`
+ * only, via targeted text edits — `schemaSource`, `handlerBody`, comments,
+ * and every unnamed field stay byte-identical (narrower than replacePattern).
+ */
+export function updatePattern(sourceFile, change) {
+    const obj = resolveUpdatableHandlerLiteral(sourceFile, change);
     const headerFlags = HEADER_KEY_FLAGS_BY_HANDLER_KIND[change.id.kind];
     const setEntries = Object.entries(change.set).filter(([, v]) => v !== undefined);
     for (const [key] of setEntries) {
@@ -396,20 +388,47 @@ export function updatePattern(sourceFile, change) {
     // Dedupe: two identical `unset` entries would otherwise produce two
     // overlapping deletes, the second eating text past the first's shrink.
     const unsetKeys = new Set(unsetKeyList);
-    const edits = [
-        ...setEntries.map(([key, value]) => buildSetEdit(obj, key, value, unsetKeys)),
-        ...[...unsetKeys]
+    const originalText = sourceFile.getFullText();
+    try {
+        // Unsets run first and the set edits are built against the re-parsed
+        // result: an append anchor and an inline unset can otherwise share the
+        // same comma and overlap.
+        applyEditsDescending(sourceFile, [...unsetKeys]
             .map((key) => buildUnsetEdit(obj, key))
-            .filter((edit) => edit !== undefined),
-    ];
-    // Apply from the highest offset down so an earlier edit's positions,
-    // captured above against the pre-edit text, stay valid.
-    edits
-        .slice()
-        .sort((a, b) => b.start - a.start)
-        .forEach((edit) => {
+            .filter((edit) => edit !== undefined));
+        const settable = unsetKeys.size > 0 ? resolveUpdatableHandlerLiteral(sourceFile, change) : obj;
+        const inPlaceEdits = [];
+        const missingEntries = [];
+        for (const [key, value] of setEntries) {
+            const edit = buildInPlaceSetEdit(settable, key, value);
+            if (edit)
+                inPlaceEdits.push(edit);
+            else
+                missingEntries.push([key, value]);
+        }
+        applyEditsDescending(sourceFile, [
+            ...inPlaceEdits,
+            ...(missingEntries.length > 0 ? [buildAppendEdit(settable, missingEntries)] : []),
+        ]);
+    }
+    catch (error) {
+        sourceFile.replaceWithText(originalText);
+        throw error;
+    }
+}
+// Apply from the highest offset down so an earlier edit's positions,
+// captured against the pre-edit text, stay valid.
+function applyEditsDescending(sourceFile, edits) {
+    const sorted = edits.slice().sort((a, b) => b.start - a.start);
+    for (let i = 1; i < sorted.length; i++) {
+        const previous = sorted[i - 1];
+        const current = sorted[i];
+        if (previous && current && current.end > previous.start) {
+            throw new Error("updatePattern: internal error, text edits overlap");
+        }
+    }
+    for (const edit of sorted)
         sourceFile.replaceText([edit.start, edit.end], edit.text);
-    });
 }
 // =============================================================================
 // Lookup

package/dist/engine/feature-ast/patcher.d.ts

@@ -50,6 +50,7 @@ export type AddStreamHandlerArgs = {
     readonly handlerSource: string;
     readonly access?: AccessRule;
     readonly rateLimit?: RateLimitOption;
+    readonly escapeHatch?: EscapeHatchDeclaration;
 };
 export type AddHookArgs = {
     readonly type: LifecycleHookType | "validation";