@warmhub/sdk-ts 0.51.0 → 0.52.1

package/dist/{chunk-ZTDMTDJ6.js → chunk-OPTB23HY.js}

@@ -50,6 +50,19 @@ function splitLocalPath(name) {
   if (idx === -1) return null;
   return { shapePrefix: name.slice(0, idx), bareName: name.slice(idx + 1) };
 }
+function inferOperationKind(op) {
+  if (op.kind === "shape" || op.kind === "thing" || op.kind === "assertion" || op.kind === "collection") {
+    return op.kind;
+  }
+  if (op.about !== void 0) {
+    return "assertion";
+  }
+  if (typeof op.type === "string" && op.type.length > 0 && Array.isArray(op.members)) {
+    return "collection";
+  }
+  const segments = op.name ? op.name.split("/").filter(Boolean) : [];
+  return segments.length >= 3 ? "assertion" : "thing";
+}
 
 // ../rules/src/component-cli-signing.ts
 var CLI_INSTALL_REPO_HEADER = "X-WarmHub-Install-Repo";
@@ -170,6 +183,114 @@ var REPO_AUTH_SCOPES = [
 
 // ../rules/src/component-manifest-contract.ts
 new Set(REPO_AUTH_SCOPES);
+
+// ../rules/src/field-name-safety.ts
+var ESCAPE_DISPLAY_MAX_CHARS = 120;
+var DANGEROUS_FORMAT_CODEPOINTS = /* @__PURE__ */ new Set([
+  8203,
+  // zero width space
+  8204,
+  // zero width non-joiner
+  8205,
+  // zero width joiner
+  8288,
+  // word joiner
+  8294,
+  // left-to-right isolate
+  8295,
+  // right-to-left isolate
+  8296,
+  // first strong isolate
+  8297,
+  // pop directional isolate
+  8234,
+  // left-to-right embedding
+  8235,
+  // right-to-left embedding
+  8236,
+  // pop directional formatting
+  8237,
+  // left-to-right override
+  8238,
+  // right-to-left override
+  8232,
+  // line separator
+  8233
+  // paragraph separator
+]);
+function isControlCodePoint(codePoint) {
+  return codePoint <= 31 || codePoint === 127 || codePoint >= 128 && codePoint <= 159;
+}
+function escapeCodePoint(codePoint) {
+  return codePoint <= 65535 ? `\\u${codePoint.toString(16).padStart(4, "0")}` : `\\u{${codePoint.toString(16)}}`;
+}
+function needsEscape(value) {
+  for (const char of value) {
+    const codePoint = char.codePointAt(0);
+    if (codePoint === void 0) continue;
+    if (isControlCodePoint(codePoint)) return true;
+    if (DANGEROUS_FORMAT_CODEPOINTS.has(codePoint)) return true;
+    if (codePoint === 34) return true;
+  }
+  return false;
+}
+function clip(value) {
+  return value.length <= ESCAPE_DISPLAY_MAX_CHARS ? value : `${value.slice(0, ESCAPE_DISPLAY_MAX_CHARS)}...<truncated>`;
+}
+function escapeFieldName(value) {
+  if (!needsEscape(value)) return value;
+  const jsonEscaped = JSON.stringify(value).slice(1, -1);
+  let output = "";
+  for (const char of jsonEscaped) {
+    const codePoint = char.codePointAt(0);
+    if (codePoint === void 0) continue;
+    output += isControlCodePoint(codePoint) || DANGEROUS_FORMAT_CODEPOINTS.has(codePoint) ? escapeCodePoint(codePoint) : char;
+  }
+  return output;
+}
+function escapeFieldNameForDisplay(value) {
+  return clip(escapeFieldName(value));
+}
+function escapeFieldNameForIdentity(value) {
+  return escapeFieldName(value);
+}
+function isUnsafeFieldName(name) {
+  if (name.length === 0) return { unsafe: true, reason: "empty field name" };
+  if (name !== name.trim()) {
+    return { unsafe: true, reason: "leading or trailing whitespace" };
+  }
+  for (const char of name) {
+    const codePoint = char.codePointAt(0);
+    if (codePoint === void 0) continue;
+    if (isControlCodePoint(codePoint)) {
+      return {
+        unsafe: true,
+        reason: `control character (U+${codePoint.toString(16).padStart(4, "0").toUpperCase()})`
+      };
+    }
+    if (DANGEROUS_FORMAT_CODEPOINTS.has(codePoint)) {
+      return {
+        unsafe: true,
+        reason: `format or separator character (U+${codePoint.toString(16).padStart(4, "0").toUpperCase()})`
+      };
+    }
+  }
+  return { unsafe: false };
+}
+function stripOptionalMarker(key) {
+  return key.endsWith("?") ? key.slice(0, -1) : key;
+}
+function joinFieldPath(...segments) {
+  return joinFieldPathWithEscaper(escapeFieldNameForDisplay, segments);
+}
+function joinFieldIdentityPath(...segments) {
+  return joinFieldPathWithEscaper(escapeFieldNameForIdentity, segments);
+}
+function joinFieldPathWithEscaper(escapeSegment, segments) {
+  return segments.map(
+    (segment) => typeof segment === "number" ? `[${segment}]` : escapeSegment(segment)
+  ).join(".").replace(/\.\[/g, "[");
+}
 var PLATFORM_STATUS_STATUSES = [
   {
     key: "available",
@@ -565,12 +686,6 @@ function tokenHygiene(operations, errors) {
     }
   }
 }
-function inferKindFromName(name) {
-  const parts = name.split("/").filter(Boolean);
-  if (parts.length >= 3) return "assertion";
-  if (parts.length === 2) return "thing";
-  return "thing";
-}
 function illegalOpSequences(operations, errors, checkAddAdd) {
   const opHistory = /* @__PURE__ */ new Map();
   for (let i = 0; i < operations.length; i++) {
@@ -579,7 +694,7 @@ function illegalOpSequences(operations, errors, checkAddAdd) {
     const name = getOpName(op);
     if (!name) continue;
     if (hasAnyTokens(name)) continue;
-    const kind = op.kind ?? (name ? inferKindFromName(name) : "thing");
+    const kind = inferOperationKind({ ...op, name });
     const qualName = kind === "shape" ? `shape:${name}` : `thing:${name}`;
     const history = opHistory.get(qualName) ?? [];
     history.push({ operation: op.operation, index: i });
@@ -745,6 +860,12 @@ function basePrimitiveTypeFromSpec(fieldType) {
 // ../rules/src/shape-validation.ts
 var MAX_CONTENT_FIELD_BYTES = 64 * 1024;
 var MAX_INDEXABLE_SCALAR_FIELDS_PER_SHAPE = 256;
+var UNSUPPORTED_REGEX_SYNTAX_REASON = "uses unsupported regex syntax";
+var EXCESSIVE_BACKTRACKING_REGEX_REASON = "uses unsupported regex syntax that can cause excessive backtracking";
+var MAX_FIXED_WIDTH_ALTERNATIVE_TOKENS = MAX_CONTENT_FIELD_BYTES;
+var MAX_REGEX_SCAN_GROUP_DEPTH = 64;
+var MAX_SAFE_OVERLAPPING_GROUP_REPEATS = 8;
+var MAX_SAFE_TOP_LEVEL_ALTERNATIVES = 128;
 var CONTENT_FIELD_LIMIT_ERROR = `WarmHub content fields are limited to ${MAX_CONTENT_FIELD_BYTES} bytes. WarmHub is not a document store; store large documents in S3, Box, Drive, or another document system and reference them from WarmHub instead.`;
 var textEncoder = new TextEncoder();
 function utf8ByteLength(value) {
@@ -760,6 +881,801 @@ function assertContentFieldWithinLimit(path, value, errors) {
   const message = contentFieldLimitError(path, value);
   if (message) errors.push(message);
 }
+function regexTokenSet(chars, negated = false) {
+  return { chars: new Set(chars), negated };
+}
+function regexQuantifierAt(pattern, index) {
+  const char = pattern[index];
+  if (char === "*" || char === "+") {
+    return {
+      kind: "unbounded",
+      endIndex: index,
+      minZero: char === "*",
+      variableLength: true,
+      max: void 0
+    };
+  }
+  if (char === "?") {
+    return {
+      kind: "bounded",
+      endIndex: index,
+      minZero: true,
+      variableLength: true,
+      max: 1
+    };
+  }
+  if (char !== "{") {
+    return {
+      kind: "none",
+      endIndex: index,
+      minZero: false,
+      variableLength: false,
+      max: void 0
+    };
+  }
+  const closeIndex = pattern.indexOf("}", index + 1);
+  if (closeIndex === -1) {
+    return {
+      kind: "none",
+      endIndex: index,
+      minZero: false,
+      variableLength: false,
+      max: void 0
+    };
+  }
+  const body = pattern.slice(index + 1, closeIndex);
+  if (!/^\d+(?:,\d*)?$/.test(body)) {
+    return {
+      kind: "none",
+      endIndex: index,
+      minZero: false,
+      variableLength: false,
+      max: void 0
+    };
+  }
+  const [minText, maxText] = body.split(",", 2);
+  const min = Number(minText);
+  const max = maxText === void 0 || maxText === "" ? min : Number(maxText);
+  return {
+    kind: body.endsWith(",") ? "unbounded" : "bounded",
+    endIndex: closeIndex,
+    minZero: min === 0,
+    variableLength: body.includes(",") && min !== max,
+    max: body.endsWith(",") ? void 0 : max
+  };
+}
+function skipCharacterClass(pattern, index) {
+  for (let i = index + 1; i < pattern.length; i++) {
+    if (pattern[i] === "\\") {
+      i++;
+      continue;
+    }
+    if (pattern[i] === "]") return i;
+  }
+  return pattern.length - 1;
+}
+function splitTopLevelAlternatives(pattern, startIndex, endIndex) {
+  const alternatives = [];
+  let depth = 0;
+  let partStart = startIndex;
+  for (let i = startIndex; i < endIndex; i++) {
+    const char = pattern[i];
+    if (char === "\\") {
+      i++;
+      continue;
+    }
+    if (char === "[") {
+      i = skipCharacterClass(pattern, i);
+      continue;
+    }
+    if (char === "(") {
+      depth++;
+      continue;
+    }
+    if (char === ")" && depth > 0) {
+      depth--;
+      continue;
+    }
+    if (char === "|" && depth === 0) {
+      alternatives.push(pattern.slice(partStart, i));
+      partStart = i + 1;
+    }
+  }
+  alternatives.push(pattern.slice(partStart, endIndex));
+  return alternatives;
+}
+function asciiRange(start, end) {
+  const startCode = start.charCodeAt(0);
+  const endCode = end.charCodeAt(0);
+  if (start.length !== 1 || end.length !== 1 || startCode > endCode) {
+    return void 0;
+  }
+  const chars = /* @__PURE__ */ new Set();
+  for (let code = startCode; code <= endCode; code++) {
+    chars.add(String.fromCharCode(code));
+  }
+  return chars;
+}
+var ASCII_WHITESPACE_CHARS = /* @__PURE__ */ new Set(["	", "\n", "\v", "\f", "\r", " "]);
+var JS_DOT_EXCLUDED_CHARS = /* @__PURE__ */ new Set(["\n", "\r", "\u2028", "\u2029"]);
+function escapedAtomChars(value, index, inCharacterClass = false) {
+  const next = value[index + 1];
+  if (!next) return void 0;
+  if (next === "0" && !/^[0-9]$/.test(value[index + 2] ?? "")) {
+    return { tokenSet: regexTokenSet(["\0"]), endIndex: index + 1 };
+  }
+  if (next === "b" && inCharacterClass) {
+    return { tokenSet: regexTokenSet(["\b"]), endIndex: index + 1 };
+  }
+  if (next === "x") {
+    const hex = value.slice(index + 2, index + 4);
+    if (/^[0-9A-Fa-f]{2}$/.test(hex)) {
+      return {
+        tokenSet: regexTokenSet([
+          String.fromCharCode(Number.parseInt(hex, 16))
+        ]),
+        endIndex: index + 3
+      };
+    }
+    return void 0;
+  }
+  if (next === "u") {
+    const hex = value.slice(index + 2, index + 6);
+    if (/^[0-9A-Fa-f]{4}$/.test(hex)) {
+      return {
+        tokenSet: regexTokenSet([
+          String.fromCharCode(Number.parseInt(hex, 16))
+        ]),
+        endIndex: index + 5
+      };
+    }
+    return void 0;
+  }
+  if (next === "d")
+    return {
+      tokenSet: regexTokenSet(asciiRange("0", "9") ?? []),
+      endIndex: index + 1
+    };
+  if (next === "D")
+    return {
+      tokenSet: regexTokenSet(asciiRange("0", "9") ?? [], true),
+      endIndex: index + 1
+    };
+  if (next === "w") {
+    return {
+      tokenSet: regexTokenSet([
+        ...asciiRange("0", "9") ?? [],
+        ...asciiRange("A", "Z") ?? [],
+        ...asciiRange("a", "z") ?? [],
+        "_"
+      ]),
+      endIndex: index + 1
+    };
+  }
+  if (next === "W") {
+    return {
+      tokenSet: regexTokenSet(
+        [
+          ...asciiRange("0", "9") ?? [],
+          ...asciiRange("A", "Z") ?? [],
+          ...asciiRange("a", "z") ?? [],
+          "_"
+        ],
+        true
+      ),
+      endIndex: index + 1
+    };
+  }
+  if (next === "s") {
+    return {
+      tokenSet: regexTokenSet(ASCII_WHITESPACE_CHARS),
+      endIndex: index + 1
+    };
+  }
+  if (next === "S") {
+    return {
+      tokenSet: regexTokenSet(ASCII_WHITESPACE_CHARS, true),
+      endIndex: index + 1
+    };
+  }
+  if (next === "n")
+    return { tokenSet: regexTokenSet(["\n"]), endIndex: index + 1 };
+  if (next === "r")
+    return { tokenSet: regexTokenSet(["\r"]), endIndex: index + 1 };
+  if (next === "t")
+    return { tokenSet: regexTokenSet(["	"]), endIndex: index + 1 };
+  if (next === "f")
+    return { tokenSet: regexTokenSet(["\f"]), endIndex: index + 1 };
+  if (next === "v")
+    return { tokenSet: regexTokenSet(["\v"]), endIndex: index + 1 };
+  if (/^[^A-Za-z0-9]$/.test(next)) {
+    return { tokenSet: regexTokenSet([next]), endIndex: index + 1 };
+  }
+  return void 0;
+}
+function characterClassAtomChars(value, index) {
+  const negated = value[index + 1] === "^";
+  const chars = /* @__PURE__ */ new Set();
+  let previousLiteral;
+  for (let i = index + (negated ? 2 : 1); i < value.length; i++) {
+    if (value[i] === "]") {
+      return { tokenSet: regexTokenSet(chars, negated), endIndex: i };
+    }
+    if (value[i] === "-" && previousLiteral && value[i + 1] !== "]") {
+      const rangeEnd = value[i + 1] === "\\" ? escapedAtomChars(value, i + 1, true) : { tokenSet: regexTokenSet([value[i + 1]]), endIndex: i + 1 };
+      if (!rangeEnd || rangeEnd.tokenSet.negated || rangeEnd.tokenSet.chars.size !== 1) {
+        return void 0;
+      }
+      const [endLiteral] = rangeEnd.tokenSet.chars;
+      const range = asciiRange(previousLiteral, endLiteral);
+      if (!range) return void 0;
+      chars.delete(previousLiteral);
+      for (const char of range) chars.add(char);
+      previousLiteral = endLiteral;
+      i = rangeEnd.endIndex;
+      continue;
+    }
+    const atom = value[i] === "\\" ? escapedAtomChars(value, i, true) : { tokenSet: regexTokenSet([value[i]]), endIndex: i };
+    if (!atom || atom.tokenSet.negated) return void 0;
+    const [literal] = atom.tokenSet.chars;
+    for (const char of atom.tokenSet.chars) chars.add(char);
+    previousLiteral = atom.tokenSet.chars.size === 1 ? literal : void 0;
+    i = atom.endIndex;
+  }
+  return void 0;
+}
+function exactRepeatAt(value, index) {
+  if (value[index] !== "{") return { count: 1, endIndex: index - 1 };
+  const quantifier = regexQuantifierAt(value, index);
+  if (quantifier.kind !== "bounded" || quantifier.variableLength || quantifier.max === void 0 || !Number.isSafeInteger(quantifier.max) || quantifier.max > MAX_FIXED_WIDTH_ALTERNATIVE_TOKENS) {
+    return void 0;
+  }
+  return { count: quantifier.max, endIndex: quantifier.endIndex };
+}
+function wholeWrapperGroupContent(value) {
+  if (value[0] !== "(") return void 0;
+  let startIndex = 1;
+  if (value[1] === "?") {
+    if (value[2] === ":") {
+      startIndex = 3;
+    } else if (value[2] === "<") {
+      const nameEndIndex = value.indexOf(">", 3);
+      if (value[3] === "=" || value[3] === "!" || nameEndIndex === -1) {
+        return void 0;
+      }
+      startIndex = nameEndIndex + 1;
+    } else {
+      return void 0;
+    }
+  }
+  let depth = 0;
+  for (let i = 0; i < value.length; i++) {
+    const char = value[i];
+    if (char === "\\") {
+      i++;
+      continue;
+    }
+    if (char === "[") {
+      i = skipCharacterClass(value, i);
+      continue;
+    }
+    if (char === "(") {
+      depth++;
+      continue;
+    }
+    if (char === ")" && depth > 0) {
+      depth--;
+      if (depth === 0) {
+        return i === value.length - 1 ? { startIndex, endIndex: i } : void 0;
+      }
+    }
+  }
+  return void 0;
+}
+function fixedWidthAlternativeTokens(value) {
+  const wrapper = wholeWrapperGroupContent(value);
+  if (wrapper) {
+    return fixedWidthAlternativeTokens(
+      value.slice(wrapper.startIndex, wrapper.endIndex)
+    );
+  }
+  const parts = [];
+  let length = 0;
+  for (let i = 0; i < value.length; i++) {
+    const char = value[i];
+    if (char === "^" || char === "$") continue;
+    if ("*+?|(){}".includes(char)) return void 0;
+    const atom = char === "\\" ? escapedAtomChars(value, i) : char === "[" ? characterClassAtomChars(value, i) : char === "." ? {
+      tokenSet: regexTokenSet(JS_DOT_EXCLUDED_CHARS, true),
+      endIndex: i
+    } : { tokenSet: regexTokenSet([char]), endIndex: i };
+    if (!atom || atom.tokenSet.chars.size === 0) return void 0;
+    const repeat = exactRepeatAt(value, atom.endIndex + 1);
+    if (!repeat || repeat.count === 0) return void 0;
+    parts.push({ tokenSet: atom.tokenSet, count: repeat.count });
+    length += repeat.count;
+    i = repeat.endIndex;
+  }
+  return length > 0 ? { parts, length } : void 0;
+}
+function hasExcessiveExactRepeat(value) {
+  for (let i = 0; i < value.length; i++) {
+    const char = value[i];
+    if (char === "\\") {
+      i++;
+      continue;
+    }
+    if (char === "[") {
+      i = skipCharacterClass(value, i);
+      continue;
+    }
+    if (char !== "{") continue;
+    const quantifier = regexQuantifierAt(value, i);
+    if (quantifier.kind === "bounded" && !quantifier.variableLength && quantifier.max !== void 0 && quantifier.max > MAX_FIXED_WIDTH_ALTERNATIVE_TOKENS) {
+      return true;
+    }
+  }
+  return false;
+}
+function regexAtomTokenAt(value, index) {
+  const char = value[index];
+  if (char === "\\") return escapedAtomChars(value, index);
+  if (char === "[") return characterClassAtomChars(value, index);
+  if (".*+?|(){}".includes(char)) return void 0;
+  return { tokenSet: regexTokenSet([char]), endIndex: index };
+}
+function tokenSetsOverlap(left, right) {
+  if (!left.negated && !right.negated) {
+    for (const char of left.chars) {
+      if (right.chars.has(char)) return true;
+    }
+    return false;
+  }
+  if (left.negated && right.negated) return true;
+  const positive = left.negated ? right : left;
+  const negated = left.negated ? left : right;
+  for (const char of positive.chars) {
+    if (!negated.chars.has(char)) return true;
+  }
+  return false;
+}
+function quantifierCanRepeat(quantifier) {
+  return quantifier.kind === "unbounded" || quantifier.variableLength;
+}
+function repeatableBoundaryFor(tokenSet, quantifier) {
+  return {
+    tokenSet,
+    max: quantifier.kind === "bounded" ? quantifier.max : void 0
+  };
+}
+function overlappingRepeatablesCanBacktrack(left, right) {
+  if (!tokenSetsOverlap(left.tokenSet, right.tokenSet)) return false;
+  if (left.max === void 0 || right.max === void 0) return true;
+  return left.max * right.max > MAX_SAFE_OVERLAPPING_GROUP_REPEATS;
+}
+function recordRegexToken(group, tokenSet, quantifier) {
+  if (!group.firstTokenSet) {
+    group.firstTokenSet = tokenSet;
+  } else {
+    group.hasMultipleTokenAtoms = true;
+  }
+  if (quantifierCanRepeat(quantifier)) {
+    const boundary = repeatableBoundaryFor(tokenSet, quantifier);
+    if (group.lastRepeatableTokenSets.some(
+      (lastBoundary) => overlappingRepeatablesCanBacktrack(lastBoundary, boundary)
+    )) {
+      return EXCESSIVE_BACKTRACKING_REGEX_REASON;
+    }
+    group.lastRepeatableTokenSets = quantifier.minZero ? [...group.lastRepeatableTokenSets, boundary] : [boundary];
+  } else if (!quantifier.minZero) {
+    group.lastRepeatableTokenSets = [];
+  }
+  if (!quantifier.minZero) {
+    group.branchCanMatchEmpty = false;
+  }
+  return void 0;
+}
+function recordRegexRepeatableBoundary(group, boundary) {
+  if (group.lastRepeatableTokenSets.some(
+    (lastBoundary) => overlappingRepeatablesCanBacktrack(lastBoundary, boundary)
+  )) {
+    return EXCESSIVE_BACKTRACKING_REGEX_REASON;
+  }
+  group.lastRepeatableTokenSets = [boundary];
+  return void 0;
+}
+function tokenSequenceCanPrefixOverlap(left, right) {
+  let leftPartIndex = 0;
+  let rightPartIndex = 0;
+  let leftPartOffset = 0;
+  let rightPartOffset = 0;
+  let comparedLength = 0;
+  const length = Math.min(left.length, right.length);
+  while (comparedLength < length) {
+    const leftPart = left.parts[leftPartIndex];
+    const rightPart = right.parts[rightPartIndex];
+    if (!leftPart || !rightPart) return false;
+    if (!tokenSetsOverlap(leftPart.tokenSet, rightPart.tokenSet)) return false;
+    const step = Math.min(
+      leftPart.count - leftPartOffset,
+      rightPart.count - rightPartOffset,
+      length - comparedLength
+    );
+    comparedLength += step;
+    leftPartOffset += step;
+    rightPartOffset += step;
+    if (leftPartOffset === leftPart.count) {
+      leftPartIndex++;
+      leftPartOffset = 0;
+    }
+    if (rightPartOffset === rightPart.count) {
+      rightPartIndex++;
+      rightPartOffset = 0;
+    }
+  }
+  return true;
+}
+function firstFixedWidthTokenSet(tokens) {
+  return tokens.parts[0]?.tokenSet;
+}
+function firstRequiredAlternativeTokenSet(value) {
+  const atoms = [];
+  if (!appendRegexSequenceAtoms(value, 0, value.length, atoms)) return void 0;
+  const first = atoms[0];
+  if (!first || first.quantifier.minZero) return void 0;
+  return first.tokenSet;
+}
+function regexAlternativeSafety(value) {
+  const tokens = fixedWidthAlternativeTokens(value);
+  if (tokens) {
+    const firstTokenSet2 = firstFixedWidthTokenSet(tokens);
+    return firstTokenSet2 ? { firstTokenSet: firstTokenSet2, tokens } : void 0;
+  }
+  if (hasExcessiveExactRepeat(value)) return void 0;
+  if (!hasRequiredNonOverlappingDelimiter(value, 0, value.length)) {
+    return void 0;
+  }
+  const firstTokenSet = firstRequiredAlternativeTokenSet(value);
+  return firstTokenSet ? { firstTokenSet, tokens: void 0 } : void 0;
+}
+function hasSafeDelimitedTopLevelAlternation(pattern, startIndex, endIndex) {
+  const alternatives = splitTopLevelAlternatives(pattern, startIndex, endIndex);
+  if (alternatives.length < 2) return false;
+  if (alternatives.length > MAX_SAFE_TOP_LEVEL_ALTERNATIVES) return false;
+  const firstTokenSets = [];
+  for (const alternative of alternatives) {
+    if (hasExcessiveExactRepeat(alternative)) return false;
+    if (!hasRequiredNonOverlappingDelimiter(alternative, 0, alternative.length)) {
+      return false;
+    }
+    const firstTokenSet = firstRequiredAlternativeTokenSet(alternative);
+    if (!firstTokenSet) return false;
+    if (firstTokenSets.some((seen) => tokenSetsOverlap(seen, firstTokenSet))) {
+      return false;
+    }
+    firstTokenSets.push(firstTokenSet);
+  }
+  return true;
+}
+function regexGroupContentAt(pattern, index) {
+  if (pattern[index] !== "(") return void 0;
+  let contentStart = index + 1;
+  if (pattern[index + 1] === "?") {
+    const next = pattern[index + 2];
+    if (next === ":") {
+      contentStart = index + 3;
+    } else if (next === "<") {
+      const nameEndIndex = pattern.indexOf(">", index + 3);
+      if (pattern[index + 3] === "=" || pattern[index + 3] === "!" || nameEndIndex === -1) {
+        return void 0;
+      }
+      contentStart = nameEndIndex + 1;
+    } else {
+      return void 0;
+    }
+  }
+  let depth = 0;
+  for (let i = index; i < pattern.length; i++) {
+    const char = pattern[i];
+    if (char === "\\") {
+      i++;
+      continue;
+    }
+    if (char === "[") {
+      i = skipCharacterClass(pattern, i);
+      continue;
+    }
+    if (char === "(") {
+      depth++;
+      continue;
+    }
+    if (char === ")" && depth > 0) {
+      depth--;
+      if (depth === 0) return { contentStart, endIndex: i };
+    }
+  }
+  return void 0;
+}
+function appendRegexSequenceAtoms(pattern, startIndex, endIndex, atoms) {
+  for (let i = startIndex; i < endIndex; i++) {
+    const char = pattern[i];
+    if (char === "^" || char === "$") continue;
+    if (char === "(") {
+      const group = regexGroupContentAt(pattern, i);
+      if (!group) return false;
+      const quantifier2 = regexQuantifierAt(pattern, group.endIndex + 1);
+      if (quantifier2.kind !== "none") return false;
+      const alternatives = splitTopLevelAlternatives(
+        pattern,
+        group.contentStart,
+        group.endIndex
+      );
+      if (alternatives.length > 1) {
+        const fixedAlternatives = alternatives.map(fixedWidthAlternativeTokens);
+        if (fixedAlternatives.some((tokens) => tokens === void 0)) {
+          return false;
+        }
+        i = group.endIndex;
+        continue;
+      }
+      if (!appendRegexSequenceAtoms(
+        pattern,
+        group.contentStart,
+        group.endIndex,
+        atoms
+      )) {
+        return false;
+      }
+      i = group.endIndex;
+      continue;
+    }
+    const atom = regexAtomTokenAt(pattern, i);
+    if (!atom) return false;
+    const quantifier = regexQuantifierAt(pattern, atom.endIndex + 1);
+    atoms.push({ tokenSet: atom.tokenSet, quantifier });
+    i = quantifier.kind === "none" ? atom.endIndex : quantifier.endIndex;
+  }
+  return true;
+}
+function hasRequiredNonOverlappingDelimiter(pattern, startIndex, endIndex) {
+  const atoms = [];
+  if (!appendRegexSequenceAtoms(pattern, startIndex, endIndex, atoms)) {
+    return false;
+  }
+  const hasRequiredDelimiterAt = (index) => {
+    const delimiter = atoms[index];
+    if (!delimiter || delimiter.quantifier.minZero || delimiter.quantifier.kind === "unbounded" || delimiter.quantifier.variableLength) {
+      return false;
+    }
+    for (let i = 0; i < atoms.length; i++) {
+      if (i === index) continue;
+      const atom = atoms[i];
+      if ((atom.quantifier.kind === "unbounded" || atom.quantifier.variableLength) && tokenSetsOverlap(delimiter.tokenSet, atom.tokenSet)) {
+        return false;
+      }
+    }
+    return true;
+  };
+  const hasRequiredDisjointTokenFlow = atoms.length > 1 && atoms.every((atom) => !atom.quantifier.minZero) && !tokenSetsOverlap(atoms[0].tokenSet, atoms[atoms.length - 1].tokenSet) && atoms.slice(1).every(
+    (atom, index) => !tokenSetsOverlap(atoms[index].tokenSet, atom.tokenSet)
+  );
+  return atoms.length > 0 && (hasRequiredDelimiterAt(0) || hasRequiredDelimiterAt(atoms.length - 1) || hasRequiredDisjointTokenFlow);
+}
+function hasUnsafeTopLevelAlternation(pattern, startIndex, endIndex) {
+  const alternatives = splitTopLevelAlternatives(pattern, startIndex, endIndex);
+  if (alternatives.length < 2) return false;
+  if (alternatives.length > MAX_SAFE_TOP_LEVEL_ALTERNATIVES) return true;
+  const alternativesSafety = alternatives.map(regexAlternativeSafety);
+  if (alternativesSafety.some((safety) => safety === void 0)) return true;
+  for (let i = 0; i < alternativesSafety.length; i++) {
+    const left = alternativesSafety[i];
+    if (left === void 0) return true;
+    for (let j = i + 1; j < alternativesSafety.length; j++) {
+      const right = alternativesSafety[j];
+      if (right === void 0) return true;
+      if (left.tokens && right.tokens) {
+        if (tokenSequenceCanPrefixOverlap(left.tokens, right.tokens)) {
+          return true;
+        }
+        continue;
+      }
+      if (tokenSetsOverlap(left.firstTokenSet, right.firstTokenSet)) return true;
+    }
+  }
+  return false;
+}
+function createRegexScanGroup(contentStart) {
+  return {
+    contentStart,
+    branchCanMatchEmpty: true,
+    hasAlternation: false,
+    hasNullableBranch: false,
+    hasUnboundedQuantifier: false,
+    hasUnsafeAlternation: false,
+    hasVariableLengthQuantifier: false,
+    firstTokenSet: void 0,
+    hasMultipleTokenAtoms: false,
+    lastRepeatableTokenSets: []
+  };
+}
+function unsafeRegexPatternReason(pattern) {
+  const groups = [createRegexScanGroup(0)];
+  for (let i = 0; i < pattern.length; i++) {
+    const char = pattern[i];
+    const current = groups[groups.length - 1];
+    if (char === "\\") {
+      const next = pattern[i + 1];
+      if (next !== void 0 && next >= "1" && next <= "9") {
+        return UNSUPPORTED_REGEX_SYNTAX_REASON;
+      }
+      if (next === "k" && pattern[i + 2] === "<") {
+        return UNSUPPORTED_REGEX_SYNTAX_REASON;
+      }
+      const atom = escapedAtomChars(pattern, i);
+      if (!atom && next !== "b" && next !== "B") {
+        return UNSUPPORTED_REGEX_SYNTAX_REASON;
+      }
+      const atomEndIndex = atom?.endIndex ?? i + 1;
+      const quantifier2 = regexQuantifierAt(pattern, atomEndIndex + 1);
+      if (quantifier2.kind === "unbounded") {
+        current.hasUnboundedQuantifier = true;
+      }
+      if (quantifier2.variableLength) {
+        current.hasVariableLengthQuantifier = true;
+      }
+      if (atom) {
+        const unsafeReason = recordRegexToken(
+          current,
+          atom.tokenSet,
+          quantifier2
+        );
+        if (unsafeReason) return unsafeReason;
+      }
+      i = quantifier2.kind === "none" ? atomEndIndex : quantifier2.endIndex;
+      continue;
+    }
+    if (char === "[") {
+      const classEndIndex = skipCharacterClass(pattern, i);
+      if (pattern[classEndIndex] !== "]") return void 0;
+      const atom = characterClassAtomChars(pattern, i);
+      if (!atom) return UNSUPPORTED_REGEX_SYNTAX_REASON;
+      const quantifier2 = regexQuantifierAt(pattern, classEndIndex + 1);
+      if (quantifier2.kind === "unbounded") {
+        current.hasUnboundedQuantifier = true;
+      }
+      if (quantifier2.variableLength) {
+        current.hasVariableLengthQuantifier = true;
+      }
+      const unsafeReason = recordRegexToken(current, atom.tokenSet, quantifier2);
+      if (unsafeReason) return unsafeReason;
+      i = quantifier2.kind === "none" ? classEndIndex : quantifier2.endIndex;
+      continue;
+    }
+    if (char === "|") {
+      current.hasNullableBranch ||= current.branchCanMatchEmpty;
+      current.hasAlternation = true;
+      current.branchCanMatchEmpty = true;
+      current.hasMultipleTokenAtoms = true;
+      current.lastRepeatableTokenSets = [];
+      continue;
+    }
+    if (char === "(") {
+      let contentStart = i + 1;
+      if (pattern[i + 1] === "?") {
+        const next = pattern[i + 2];
+        if (next === ":") {
+          i += 2;
+        } else if (next === "<") {
+          const nameEndIndex = pattern.indexOf(">", i + 3);
+          if (pattern[i + 3] === "=" || pattern[i + 3] === "!" || nameEndIndex === -1) {
+            return UNSUPPORTED_REGEX_SYNTAX_REASON;
+          }
+          i = nameEndIndex;
+        } else {
+          return UNSUPPORTED_REGEX_SYNTAX_REASON;
+        }
+        contentStart = i + 1;
+      }
+      if (groups.length >= MAX_REGEX_SCAN_GROUP_DEPTH) {
+        return EXCESSIVE_BACKTRACKING_REGEX_REASON;
+      }
+      groups.push(createRegexScanGroup(contentStart));
+      continue;
+    }
+    if (char === ")" && groups.length > 1) {
+      const group = groups.pop();
+      if (group) {
+        const groupHasUnsafeAlternation = group.hasUnsafeAlternation || group.hasAlternation && hasUnsafeTopLevelAlternation(pattern, group.contentStart, i);
+        const groupCanMatchEmpty = group.hasNullableBranch || group.branchCanMatchEmpty;
+        const quantifier2 = regexQuantifierAt(pattern, i + 1);
+        const hasSafeDelimiter = hasRequiredNonOverlappingDelimiter(pattern, group.contentStart, i) || hasSafeDelimitedTopLevelAlternation(pattern, group.contentStart, i);
+        const dangerousRepeatedGroup = group.hasUnboundedQuantifier && !hasSafeDelimiter || groupHasUnsafeAlternation && !hasSafeDelimiter || group.hasVariableLengthQuantifier && !hasSafeDelimiter || groupCanMatchEmpty;
+        const boundedRepeatMax = quantifier2.kind === "bounded" ? quantifier2.max ?? 0 : 0;
+        const quantifierCanRepeatGroup = quantifier2.kind === "unbounded" || quantifier2.variableLength || quantifier2.kind === "bounded" && boundedRepeatMax > 1 && (groupHasUnsafeAlternation && !hasSafeDelimiter && boundedRepeatMax >= MAX_SAFE_OVERLAPPING_GROUP_REPEATS || group.hasUnboundedQuantifier || group.hasVariableLengthQuantifier || groupCanMatchEmpty);
+        if (dangerousRepeatedGroup && quantifierCanRepeatGroup) {
+          return EXCESSIVE_BACKTRACKING_REGEX_REASON;
+        }
+        const parent = groups[groups.length - 1];
+        const singleTokenSet = group.hasMultipleTokenAtoms ? void 0 : group.firstTokenSet;
+        if (singleTokenSet) {
+          const groupQuantifier = group.hasUnboundedQuantifier || group.hasVariableLengthQuantifier ? {
+            kind: "unbounded",
+            minZero: quantifier2.minZero || groupCanMatchEmpty,
+            variableLength: true,
+            max: void 0
+          } : quantifier2;
+          const unsafeReason = recordRegexToken(
+            parent,
+            singleTokenSet,
+            groupQuantifier
+          );
+          if (unsafeReason) return unsafeReason;
+        } else {
+          parent.hasMultipleTokenAtoms = true;
+          if (group.lastRepeatableTokenSets.length > 0) {
+            if (hasSafeDelimiter) {
+              parent.lastRepeatableTokenSets = group.lastRepeatableTokenSets;
+            } else {
+              for (const boundary of group.lastRepeatableTokenSets) {
+                const unsafeReason = recordRegexRepeatableBoundary(
+                  parent,
+                  boundary
+                );
+                if (unsafeReason) return unsafeReason;
+              }
+            }
+          } else if (!groupCanMatchEmpty && !quantifier2.minZero) {
+            parent.lastRepeatableTokenSets = [];
+          }
+          if (!groupCanMatchEmpty && !quantifier2.minZero) {
+            parent.branchCanMatchEmpty = false;
+          }
+        }
+        parent.hasUnboundedQuantifier ||= group.hasUnboundedQuantifier;
+        parent.hasUnsafeAlternation ||= groupHasUnsafeAlternation;
+        parent.hasVariableLengthQuantifier ||= group.hasVariableLengthQuantifier || quantifier2.variableLength;
+        if (quantifier2.kind === "unbounded") {
+          parent.hasUnboundedQuantifier = true;
+        }
+        if (quantifier2.kind !== "none") {
+          i = quantifier2.endIndex;
+        }
+      }
+      continue;
+    }
+    const quantifier = regexQuantifierAt(pattern, i);
+    if (quantifier.kind !== "none") {
+      if (quantifier.kind === "unbounded") {
+        current.hasUnboundedQuantifier = true;
+      }
+      if (quantifier.variableLength) {
+        current.hasVariableLengthQuantifier = true;
+      }
+      i = quantifier.endIndex;
+      continue;
+    }
+    if (!"^$".includes(char)) {
+      const atom = char === "." ? { tokenSet: regexTokenSet(JS_DOT_EXCLUDED_CHARS, true) } : { tokenSet: regexTokenSet([char]) };
+      const nextQuantifier = regexQuantifierAt(pattern, i + 1);
+      if (nextQuantifier.kind === "unbounded") {
+        current.hasUnboundedQuantifier = true;
+      }
+      if (nextQuantifier.variableLength) {
+        current.hasVariableLengthQuantifier = true;
+      }
+      const unsafeReason = recordRegexToken(
+        current,
+        atom.tokenSet,
+        nextQuantifier
+      );
+      if (unsafeReason) return unsafeReason;
+      if (nextQuantifier.kind !== "none") {
+        i = nextQuantifier.endIndex;
+      }
+    }
+  }
+  return void 0;
+}
 function normalizeOptionalTypeSpec(spec) {
   if (typeof spec === "string" && spec.endsWith("?")) {
     return { spec: spec.slice(0, -1), optionalByType: true };
@@ -772,7 +1688,15 @@ function normalizeOptionalTypeSpec(spec) {
   }
   return { spec, optionalByType: false };
 }
-function validateTypedFieldObject(path, spec, errors) {
+function validationContext(options = {}) {
+  return {
+    allowUnsafeFieldNamePaths: new Set(options.allowUnsafeFieldNamePaths ?? [])
+  };
+}
+function isAllowedLegacyUnsafeFieldPath(context, path) {
+  return context.allowUnsafeFieldNamePaths.has(path);
+}
+function validateTypedFieldObject(path, identityPath, spec, errors, context) {
   const typeValue = spec.type;
   if (typeof typeValue !== "string") {
     errors.push(
@@ -782,7 +1706,7 @@ function validateTypedFieldObject(path, spec, errors) {
   }
   if (!VALID_PRIMITIVE_TYPES.has(typeValue)) {
     errors.push(
-      `Invalid type at "${path}.type": "${typeValue}" (expected number|string|boolean|wref|array, optionally with ? suffix)`
+      `Invalid type at "${path}.type": "${escapeFieldNameForDisplay(typeValue)}" (expected number|string|boolean|wref|array, optionally with ? suffix)`
     );
     return;
   }
@@ -794,33 +1718,34 @@ function validateTypedFieldObject(path, spec, errors) {
   const baseType = typeValue.endsWith("?") ? typeValue.slice(0, -1) : typeValue;
   for (const key of Object.keys(spec)) {
     if (key === "type" || key === "description") continue;
+    const safeKey = escapeFieldNameForDisplay(key);
     if (baseType === "string") {
       if (!STRING_CONSTRAINT_KEYS.has(key)) {
         errors.push(
-          `Constraint "${key}" at "${path}" is not valid for type "string"`
+          `Constraint "${safeKey}" at "${path}" is not valid for type "string"`
         );
       }
     } else if (baseType === "number") {
       if (!NUMBER_CONSTRAINT_KEYS.has(key)) {
         errors.push(
-          `Constraint "${key}" at "${path}" is not valid for type "number"`
+          `Constraint "${safeKey}" at "${path}" is not valid for type "number"`
         );
       }
     } else if (baseType === "wref") {
       if (!WREF_CONSTRAINT_KEYS.has(key)) {
         errors.push(
-          `Constraint "${key}" at "${path}" is not valid for type "wref"`
+          `Constraint "${safeKey}" at "${path}" is not valid for type "wref"`
         );
       }
     } else if (baseType === "array") {
       if (!ARRAY_CONSTRAINT_KEYS.has(key)) {
         errors.push(
-          `Constraint "${key}" at "${path}" is not valid for type "array"`
+          `Constraint "${safeKey}" at "${path}" is not valid for type "array"`
         );
       }
     } else {
       errors.push(
-        `Constraint "${key}" at "${path}" is not valid for type "${baseType}"`
+        `Constraint "${safeKey}" at "${path}" is not valid for type "${baseType}"`
       );
     }
   }
@@ -856,6 +1781,10 @@ function validateTypedFieldObject(path, spec, errors) {
     } catch {
       errors.push(`"pattern" at "${path}" is not a valid regular expression`);
     }
+    const unsafeReason = unsafeRegexPatternReason(spec.pattern);
+    if (unsafeReason) {
+      errors.push(`"pattern" at "${path}" ${unsafeReason}`);
+    }
   }
   if ("enum" in spec) {
     if (!Array.isArray(spec.enum) || spec.enum.length === 0 || !spec.enum.every((v) => typeof v === "string")) {
@@ -906,15 +1835,21 @@ function validateTypedFieldObject(path, spec, errors) {
         `Typed array at "${path}" must have an "items" key specifying the element type`
       );
     } else {
-      validateTypeSpec(`${path}.items`, spec.items, errors);
+      validateTypeSpec(
+        `${path}.items`,
+        `${identityPath}.items`,
+        spec.items,
+        errors,
+        context
+      );
     }
   }
 }
-function validateTypeSpec(path, spec, errors) {
+function validateTypeSpec(path, identityPath, spec, errors, context) {
   if (typeof spec === "string") {
     if (!VALID_PRIMITIVE_TYPES.has(spec)) {
       errors.push(
-        `Invalid type at "${path}": "${spec}" (expected number|string|boolean|wref|array, optionally with ? suffix)`
+        `Invalid type at "${path}": "${escapeFieldNameForDisplay(spec)}" (expected number|string|boolean|wref|array, optionally with ? suffix)`
       );
     }
     return;
@@ -926,12 +1861,12 @@ function validateTypeSpec(path, spec, errors) {
       );
       return;
     }
-    validateTypeSpec(`${path}[]`, spec[0], errors);
+    validateTypeSpec(`${path}[]`, `${identityPath}[]`, spec[0], errors, context);
     return;
   }
   if (isPlainObject(spec)) {
     if (isTypeSpecObject(spec)) {
-      validateTypedFieldObject(path, spec, errors);
+      validateTypedFieldObject(path, identityPath, spec, errors, context);
       return;
     }
     if ("type" in spec && typeof spec.type === "string" && VALID_PRIMITIVE_TYPES.has(spec.type) && Object.keys(spec).every((k) => VALID_TYPESPEC_KEYS.has(k))) {
@@ -949,7 +1884,7 @@ function validateTypeSpec(path, spec, errors) {
         if (hasNonTypeSpecValues) {
           for (const key of crossTypeKeys) {
             errors.push(
-              `Constraint "${key}" at "${path}" is not valid for type "${baseType}"`
+              `Constraint "${escapeFieldNameForDisplay(key)}" at "${path}" is not valid for type "${baseType}"`
             );
           }
           return;
@@ -995,13 +1930,21 @@ function validateTypeSpec(path, spec, errors) {
       });
       if (hasWrongValueTypes) {
         errors.push(
-          `Object at "${path}" looks like a typed field object (type: "${spec.type}") but has constraint values with invalid types. Check that constraint values match their expected types (e.g., minLength must be a number, not a string).`
+          `Object at "${path}" looks like a typed field object (type: "${escapeFieldNameForDisplay(String(spec.type))}") but has constraint values with invalid types. Check that constraint values match their expected types (e.g., minLength must be a number, not a string).`
         );
         return;
       }
     }
     for (const [key, value] of Object.entries(spec)) {
-      validateTypeSpec(`${path}.${key}`, value, errors);
+      const bareKey = stripOptionalMarker(key);
+      const verdict = isUnsafeFieldName(bareKey);
+      const fieldPath = joinFieldPath(path, key);
+      const fieldIdentityPath = joinFieldIdentityPath(identityPath, key);
+      if (verdict.unsafe && !isAllowedLegacyUnsafeFieldPath(context, fieldIdentityPath)) {
+        errors.push(`Invalid field name at "${fieldPath}": ${verdict.reason}`);
+        continue;
+      }
+      validateTypeSpec(fieldPath, fieldIdentityPath, value, errors, context);
     }
     return;
   }
@@ -1035,14 +1978,22 @@ function isNestedFieldsRecord(value) {
   }
   return true;
 }
-function validateFieldsRecord(fields, prefix, errors) {
+function validateFieldsRecord(fields, prefix, errors, context, identityPrefix = prefix) {
   const seenDisplayByFolded = /* @__PURE__ */ new Map();
   for (const [key, value] of Object.entries(fields)) {
+    const bareKey = stripOptionalMarker(key);
+    const verdict = isUnsafeFieldName(bareKey);
+    const fieldPath = joinFieldPath(prefix, key);
+    const fieldIdentityPath = joinFieldIdentityPath(identityPrefix, key);
+    if (verdict.unsafe && !isAllowedLegacyUnsafeFieldPath(context, fieldIdentityPath)) {
+      errors.push(`Invalid field name at "${fieldPath}": ${verdict.reason}`);
+      continue;
+    }
     const folded = foldFieldName(key);
     const prior = seenDisplayByFolded.get(folded);
     if (prior !== void 0) {
       errors.push(
-        `${prefix}.${key}: duplicate field name. Shape already declares "${prior}" (case-insensitive match).`
+        `${joinFieldPath(prefix, key)}: duplicate field name. Shape already declares "${escapeFieldNameForDisplay(prior)}" (case-insensitive match).`
       );
       continue;
     }
@@ -1050,15 +2001,66 @@ function validateFieldsRecord(fields, prefix, errors) {
     if (isNestedFieldsRecord(value)) {
       validateFieldsRecord(
         value,
-        `${prefix}.${key}`,
-        errors
+        fieldPath,
+        errors,
+        context,
+        fieldIdentityPath
       );
     } else {
-      validateTypeSpec(`${prefix}.${key}`, value, errors);
+      validateTypeSpec(fieldPath, fieldIdentityPath, value, errors, context);
     }
   }
 }
-function validateShapeDefinition(data) {
+function collectUnsafeFieldNamePathsInTypeSpec(path, spec, paths) {
+  if (Array.isArray(spec)) {
+    if (spec.length === 1)
+      collectUnsafeFieldNamePathsInTypeSpec(`${path}[]`, spec[0], paths);
+    return;
+  }
+  if (isTypeSpecObject(spec)) {
+    const normalized = normalizeOptionalTypeSpec(spec).spec;
+    if (isTypeSpecObject(normalized) && typeof normalized.type === "string" && normalized.type === "array" && "items" in normalized) {
+      collectUnsafeFieldNamePathsInTypeSpec(
+        `${path}.items`,
+        normalized.items,
+        paths
+      );
+    }
+    return;
+  }
+  if (!isNestedFieldsRecord(spec)) return;
+  collectUnsafeFieldNamePathsInFieldsRecord(spec, path, paths);
+}
+function collectUnsafeFieldNamePathsInFieldsRecord(fields, prefix, paths) {
+  for (const [key, value] of Object.entries(fields)) {
+    const fieldPath = joinFieldIdentityPath(prefix, key);
+    if (isUnsafeFieldName(stripOptionalMarker(key)).unsafe) {
+      paths.push(fieldPath);
+    }
+    if (isNestedFieldsRecord(value)) {
+      collectUnsafeFieldNamePathsInFieldsRecord(value, fieldPath, paths);
+    } else {
+      collectUnsafeFieldNamePathsInTypeSpec(fieldPath, value, paths);
+    }
+  }
+}
+function collectUnsafeShapeFieldNamePaths(data) {
+  if (typeof data !== "object" || data === null || Array.isArray(data)) {
+    return [];
+  }
+  const fields = data.fields;
+  if (typeof fields !== "object" || fields === null || Array.isArray(fields)) {
+    return [];
+  }
+  const paths = [];
+  collectUnsafeFieldNamePathsInFieldsRecord(
+    fields,
+    "fields",
+    paths
+  );
+  return paths;
+}
+function validateShapeDefinition(data, options = {}) {
   if (typeof data !== "object" || data === null || Array.isArray(data)) {
     return { valid: false, errors: ["Shape definition must be a plain object"] };
   }
@@ -1066,7 +2068,9 @@ function validateShapeDefinition(data) {
   const errors = [];
   for (const key of Object.keys(obj)) {
     if (!ALLOWED_SHAPE_KEYS.has(key)) {
-      errors.push(`Unsupported shape definition key "${key}"`);
+      errors.push(
+        `Unsupported shape definition key "${escapeFieldNameForDisplay(key)}"`
+      );
     }
   }
   if (!("fields" in obj)) {
@@ -1082,7 +2086,13 @@ function validateShapeDefinition(data) {
       errors: ['"fields" must be a plain object mapping field names to types']
     };
   }
-  validateFieldsRecord(fields, "fields", errors);
+  const context = validationContext(options);
+  validateFieldsRecord(
+    fields,
+    "fields",
+    errors,
+    context
+  );
   const indexableFieldPaths = collectIndexableShapeFieldPaths(
     fields
   );
@@ -1099,7 +2109,7 @@ function validateShapeDefinition(data) {
   }
   for (const fieldPath of duplicateIndexableFieldPaths) {
     errors.push(
-      `Shape declares ambiguous indexable field path "${fieldPath}"; dotted field names, optional-key suffixes, and case-insensitive folded paths must not collide with another indexable path`
+      `Shape declares ambiguous indexable field path "${escapeFieldNameForDisplay(fieldPath)}"; dotted field names, optional-key suffixes, and case-insensitive folded paths must not collide with another indexable path`
     );
   }
   if (indexableFieldCount > MAX_INDEXABLE_SCALAR_FIELDS_PER_SHAPE) {
@@ -1117,36 +2127,7 @@ function validateShapeDefinition(data) {
   return { valid: true };
 }
 function validateAgainstShape(data, shapeFields) {
-  const errors = [];
-  if (typeof data !== "object" || data === null || Array.isArray(data)) {
-    return { valid: false, errors: ["Data must be a plain object"] };
-  }
-  for (const [fieldSpec, rawTypeDef] of Object.entries(shapeFields)) {
-    const isOptionalByKey = fieldSpec.endsWith("?");
-    const fieldName = isOptionalByKey ? fieldSpec.slice(0, -1) : fieldSpec;
-    const normalized = normalizeOptionalTypeSpec(rawTypeDef);
-    const isOptional = isOptionalByKey || normalized.optionalByType;
-    const value = data[fieldName];
-    if (value === void 0 || value === null) {
-      if (!isOptional) {
-        errors.push(`Missing required field: "${fieldName}"`);
-      }
-      continue;
-    }
-    validateField(fieldName, value, normalized.spec, errors);
-  }
-  validatePersistedStringFieldLimits(data, shapeFields, errors);
-  const warnings = buildUndeclaredFieldsWarning(data, shapeFields);
-  if (errors.length > 0) {
-    return warnings ? { valid: false, errors, warnings } : { valid: false, errors };
-  }
-  return warnings ? { valid: true, warnings } : { valid: true };
-}
-function buildUndeclaredFieldsWarning(data, shapeFields) {
-  return buildUndeclaredFieldsWarningFromDeclaredSet(
-    data,
-    declaredFieldNames(shapeFields)
-  );
+  return compileShapeValidator(shapeFields)(data);
 }
 function declaredFieldNames(shapeFields) {
   const declared = /* @__PURE__ */ new Set();
@@ -1176,6 +2157,32 @@ function buildUndeclaredFieldsWarningFromDeclaredSet(data, declared) {
   return { undeclaredFields };
 }
 var MAX_UNDECLARED_FIELDS_REPORTED = 500;
+function compileShapeValidator(shapeFields) {
+  const compiledFields = compileObjectFields(shapeFields);
+  const declared = declaredFieldNames(shapeFields);
+  return (data) => {
+    const errors = [];
+    if (typeof data !== "object" || data === null || Array.isArray(data)) {
+      return { valid: false, errors: ["Data must be a plain object"] };
+    }
+    for (const field of compiledFields) {
+      const value = data[field.fieldName];
+      if (value === void 0 || value === null) {
+        if (!field.isOptional) {
+          errors.push(`Missing required field: "${field.displayName}"`);
+        }
+        continue;
+      }
+      field.validate(field.displayName, value, errors);
+    }
+    validatePersistedStringFieldLimits(data, shapeFields, errors);
+    const warnings = buildUndeclaredFieldsWarningFromDeclaredSet(data, declared);
+    if (errors.length > 0) {
+      return warnings ? { valid: false, errors, warnings } : { valid: false, errors };
+    }
+    return warnings ? { valid: true, warnings } : { valid: true };
+  };
+}
 function validatePersistedStringFieldLimits(value, typeDef, errors, path) {
   const normalized = normalizeOptionalTypeSpec(typeDef).spec;
   if (typeof value === "string") {
@@ -1206,31 +2213,176 @@ function validatePersistedStringFieldLimits(value, typeDef, errors, path) {
       nestedValue,
       fields?.get(key),
       errors,
-      path ? `${path}.${key}` : key
+      path ? joinFieldPath(path, key) : escapeFieldNameForDisplay(key)
     );
   }
 }
-function isDeclaredStringType(typeDef) {
-  if (typeDef === "string") return true;
-  return isTypeSpecObject(typeDef) && typeDef.type === "string";
-}
-function isDeclaredWrefType(typeDef) {
-  if (typeDef === "wref") return true;
-  return isTypeSpecObject(typeDef) && typeDef.type === "wref";
-}
-function arrayElementType(typeDef) {
-  if (Array.isArray(typeDef)) return typeDef[0];
-  if (isTypeSpecObject(typeDef) && typeDef.type === "array")
-    return typeDef.items;
-  return void 0;
+function isDeclaredStringType(typeDef) {
+  if (typeDef === "string") return true;
+  return isTypeSpecObject(typeDef) && typeDef.type === "string";
+}
+function isDeclaredWrefType(typeDef) {
+  if (typeDef === "wref") return true;
+  return isTypeSpecObject(typeDef) && typeDef.type === "wref";
+}
+function arrayElementType(typeDef) {
+  if (Array.isArray(typeDef)) return typeDef[0];
+  if (isTypeSpecObject(typeDef) && typeDef.type === "array")
+    return typeDef.items;
+  return void 0;
+}
+function nestedObjectFields(typeDef) {
+  if (!isPlainObject(typeDef) || isTypeSpecObject(typeDef)) return void 0;
+  const fields = /* @__PURE__ */ new Map();
+  for (const [key, value] of Object.entries(typeDef)) {
+    fields.set(key.endsWith("?") ? key.slice(0, -1) : key, value);
+  }
+  return fields;
+}
+function compileObjectFields(shapeFields) {
+  return Object.entries(shapeFields).map(([fieldSpec, rawTypeDef]) => {
+    const isOptionalByKey = fieldSpec.endsWith("?");
+    const fieldName = isOptionalByKey ? fieldSpec.slice(0, -1) : fieldSpec;
+    const normalized = normalizeOptionalTypeSpec(rawTypeDef);
+    return {
+      fieldName,
+      displayName: escapeFieldNameForDisplay(fieldName),
+      isOptional: isOptionalByKey || normalized.optionalByType,
+      validate: compileTypeValidator(normalized.spec)
+    };
+  });
+}
+function compileTypeValidator(typeDef) {
+  if (typeof typeDef === "string") {
+    return (path, value, errors) => validatePrimitiveField(path, value, typeDef, errors);
+  }
+  if (Array.isArray(typeDef)) {
+    const elementValidator = typeDef.length > 0 ? compileTypeValidator(normalizeOptionalTypeSpec(typeDef[0]).spec) : void 0;
+    return (path, value, errors) => {
+      if (!Array.isArray(value)) {
+        errors.push(`Field "${path}" expected array, got ${typeof value}`);
+      } else if (elementValidator) {
+        for (let i = 0; i < value.length; i++) {
+          elementValidator(`${path}[${i}]`, value[i], errors);
+        }
+      }
+    };
+  }
+  if (isTypeSpecObject(typeDef)) {
+    const baseType = typeDef.type.endsWith("?") ? typeDef.type.slice(0, -1) : typeDef.type;
+    if (baseType === "array") {
+      const elementValidator = "items" in typeDef && typeDef.items != null ? compileTypeValidator(normalizeOptionalTypeSpec(typeDef.items).spec) : void 0;
+      return (path, value, errors) => {
+        if (!Array.isArray(value)) {
+          errors.push(`Field "${path}" expected array, got ${typeof value}`);
+          return;
+        }
+        if (typeof typeDef.minItems === "number" && value.length < typeDef.minItems) {
+          errors.push(
+            `Field "${path}" has ${value.length} items, minimum is ${typeDef.minItems}`
+          );
+        }
+        if (typeof typeDef.maxItems === "number" && value.length > typeDef.maxItems) {
+          errors.push(
+            `Field "${path}" has ${value.length} items, maximum is ${typeDef.maxItems}`
+          );
+        }
+        if (elementValidator) {
+          for (let i = 0; i < value.length; i++) {
+            elementValidator(`${path}[${i}]`, value[i], errors);
+          }
+        }
+      };
+    }
+    const validateConstraintsCompiled = compileConstraintsValidator(typeDef);
+    return (path, value, errors) => {
+      validatePrimitiveField(path, value, typeDef.type, errors);
+      validateConstraintsCompiled(path, value, errors);
+    };
+  }
+  if (isPlainObject(typeDef)) {
+    const compiledFields = compileObjectFields(typeDef);
+    return (path, value, errors) => {
+      if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        errors.push(`Field "${path}" expected object, got ${typeof value}`);
+        return;
+      }
+      const objValue = value;
+      for (const field of compiledFields) {
+        const subValue = objValue[field.fieldName];
+        const subPath = joinFieldPath(path, field.fieldName);
+        if (subValue === void 0 || subValue === null) {
+          if (!field.isOptional) {
+            errors.push(`Missing required field: "${subPath}"`);
+          }
+          continue;
+        }
+        field.validate(subPath, subValue, errors);
+      }
+    };
+  }
+  return () => {
+  };
+}
+function compileConstraintsValidator(spec) {
+  const pattern = typeof spec.pattern === "string" ? spec.pattern : void 0;
+  const patternConstraint = pattern === void 0 ? void 0 : compilePatternConstraint(pattern);
+  return (path, value, errors) => {
+    if (typeof value === "string") {
+      if (typeof spec.minLength === "number" && value.length < spec.minLength) {
+        errors.push(
+          `Field "${path}" length ${value.length} is below minimum ${spec.minLength}`
+        );
+      }
+      if (typeof spec.maxLength === "number" && value.length > spec.maxLength) {
+        errors.push(
+          `Field "${path}" length ${value.length} exceeds maximum ${spec.maxLength}`
+        );
+      }
+      if (pattern !== void 0) {
+        const safePattern = escapeFieldNameForDisplay(pattern);
+        if (patternConstraint?.kind === "unsupported") {
+          errors.push(
+            `Field "${path}" has unsupported pattern "${safePattern}"`
+          );
+        } else if (patternConstraint?.kind === "invalid") {
+          errors.push(
+            `Field "${path}" has invalid pattern "${safePattern}" \u2014 skipping regex check`
+          );
+        } else if (patternConstraint?.kind === "compiled" && !patternConstraint.regex.test(value)) {
+          errors.push(`Field "${path}" does not match pattern "${safePattern}"`);
+        }
+      }
+      if (Array.isArray(spec.enum) && !spec.enum.includes(value)) {
+        errors.push(
+          `Field "${path}" value "${escapeFieldNameForDisplay(String(value))}" is not in allowed values: ${spec.enum.map((entry) => escapeFieldNameForDisplay(String(entry))).join(", ")}`
+        );
+      }
+    }
+    if (typeof value === "number") {
+      if (typeof spec.minimum === "number" && value < spec.minimum) {
+        errors.push(
+          `Field "${path}" value ${value} is below minimum ${spec.minimum}`
+        );
+      }
+      if (typeof spec.maximum === "number" && value > spec.maximum) {
+        errors.push(
+          `Field "${path}" value ${value} exceeds maximum ${spec.maximum}`
+        );
+      }
+      if (spec.integer === true && !Number.isInteger(value)) {
+        errors.push(`Field "${path}" must be an integer, got ${value}`);
+      }
+    }
+  };
 }
-function nestedObjectFields(typeDef) {
-  if (!isPlainObject(typeDef) || isTypeSpecObject(typeDef)) return void 0;
-  const fields = /* @__PURE__ */ new Map();
-  for (const [key, value] of Object.entries(typeDef)) {
-    fields.set(key.endsWith("?") ? key.slice(0, -1) : key, value);
+function compilePatternConstraint(pattern) {
+  if (unsafeRegexPatternReason(pattern)) return { kind: "unsupported" };
+  try {
+    return { kind: "compiled", regex: new RegExp(pattern) };
+  } catch {
+    return { kind: "invalid" };
   }
-  return fields;
 }
 function validatePrimitiveField(path, value, typeDef, errors) {
   switch (typeDef) {
@@ -1263,172 +2415,6 @@ function validatePrimitiveField(path, value, typeDef, errors) {
       break;
   }
 }
-function validateNestedObjectField(path, value, typeDef, errors) {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    errors.push(`Field "${path}" expected object, got ${typeof value}`);
-    return;
-  }
-  const objValue = value;
-  for (const [subKey, rawSubType] of Object.entries(typeDef)) {
-    const isOptionalByKey = subKey.endsWith("?");
-    const fieldName = isOptionalByKey ? subKey.slice(0, -1) : subKey;
-    const normalized = normalizeOptionalTypeSpec(rawSubType);
-    const isOptional = isOptionalByKey || normalized.optionalByType;
-    const subValue = objValue[fieldName];
-    if (subValue === void 0 || subValue === null) {
-      if (!isOptional) {
-        errors.push(`Missing required field: "${path}.${fieldName}"`);
-      }
-      continue;
-    }
-    validateField(`${path}.${fieldName}`, subValue, normalized.spec, errors);
-  }
-}
-function validateField(path, value, typeDef, errors) {
-  if (typeof typeDef === "string") {
-    validatePrimitiveField(path, value, typeDef, errors);
-    return;
-  }
-  if (Array.isArray(typeDef)) {
-    if (!Array.isArray(value)) {
-      errors.push(`Field "${path}" expected array, got ${typeof value}`);
-    } else if (typeDef.length > 0) {
-      const rawElementType = typeDef[0];
-      const { spec: elementType } = normalizeOptionalTypeSpec(rawElementType);
-      for (let i = 0; i < value.length; i++) {
-        validateField(`${path}[${i}]`, value[i], elementType, errors);
-      }
-    }
-    return;
-  }
-  if (isTypeSpecObject(typeDef)) {
-    if (typeof typeDef.type === "string") {
-      const baseType = typeDef.type.endsWith("?") ? typeDef.type.slice(0, -1) : typeDef.type;
-      if (baseType === "array") {
-        validateTypedArrayField(path, value, typeDef, errors);
-      } else {
-        validatePrimitiveField(path, value, typeDef.type, errors);
-        validateConstraints(path, value, typeDef, errors);
-      }
-    } else {
-      errors.push(
-        `Field "${path}" has malformed type spec: "type" must be a string`
-      );
-    }
-    return;
-  }
-  if (isPlainObject(typeDef)) {
-    validateNestedObjectField(path, value, typeDef, errors);
-  }
-}
-function validateTypedArrayField(path, value, spec, errors) {
-  if (!Array.isArray(value)) {
-    errors.push(`Field "${path}" expected array, got ${typeof value}`);
-    return;
-  }
-  if (typeof spec.minItems === "number" && value.length < spec.minItems) {
-    errors.push(
-      `Field "${path}" has ${value.length} items, minimum is ${spec.minItems}`
-    );
-  }
-  if (typeof spec.maxItems === "number" && value.length > spec.maxItems) {
-    errors.push(
-      `Field "${path}" has ${value.length} items, maximum is ${spec.maxItems}`
-    );
-  }
-  if ("items" in spec && spec.items != null) {
-    const { spec: elementType } = normalizeOptionalTypeSpec(spec.items);
-    if (typeof elementType === "string" || Array.isArray(elementType) || isPlainObject(elementType)) {
-      for (let i = 0; i < value.length; i++) {
-        validateField(`${path}[${i}]`, value[i], elementType, errors);
-      }
-    }
-  }
-}
-function validateConstraints(path, value, spec, errors) {
-  if (typeof value === "string") {
-    if (typeof spec.minLength === "number" && value.length < spec.minLength) {
-      errors.push(
-        `Field "${path}" length ${value.length} is below minimum ${spec.minLength}`
-      );
-    }
-    if (typeof spec.maxLength === "number" && value.length > spec.maxLength) {
-      errors.push(
-        `Field "${path}" length ${value.length} exceeds maximum ${spec.maxLength}`
-      );
-    }
-    if (typeof spec.pattern === "string") {
-      try {
-        if (!new RegExp(spec.pattern).test(value)) {
-          errors.push(
-            `Field "${path}" does not match pattern "${spec.pattern}"`
-          );
-        }
-      } catch {
-        errors.push(
-          `Field "${path}" has invalid pattern "${spec.pattern}" \u2014 skipping regex check`
-        );
-      }
-    }
-    if (Array.isArray(spec.enum) && !spec.enum.includes(value)) {
-      errors.push(
-        `Field "${path}" value "${value}" is not in allowed values: ${spec.enum.join(", ")}`
-      );
-    }
-  }
-  if (typeof value === "number") {
-    if (typeof spec.minimum === "number" && value < spec.minimum) {
-      errors.push(
-        `Field "${path}" value ${value} is below minimum ${spec.minimum}`
-      );
-    }
-    if (typeof spec.maximum === "number" && value > spec.maximum) {
-      errors.push(
-        `Field "${path}" value ${value} exceeds maximum ${spec.maximum}`
-      );
-    }
-    if (spec.integer === true && !Number.isInteger(value)) {
-      errors.push(`Field "${path}" must be an integer, got ${value}`);
-    }
-  }
-}
-
-// ../rules/src/system-components/identity.ts
-var IDENTITY_COMPONENT_ID = "com.warmhub.identity";
-var IDENTITY_FIELDS = {
-  // Required. Conventionally equal to the thing's name (the wref tail) —
-  // Identity things are addressed as Identity/<external_id>. Kept as a
-  // field for explicit schema visibility and to leave room for callers
-  // that read the body without resolving the wref. v1 enforces this only
-  // by convention; a commit-time validator can be added when a consumer
-  // needs hard guarantees.
-  external_id: "string",
-  display_name: "string"
-  // Deferred fields, added as additive shape revisions when their consumer
-  // ticket lands: email, avatar_url, profile, kind. Each consumer (#2548,
-  // #2549, #2550) is the trigger for adding the corresponding optional field.
-};
-var IDENTITY_MANIFEST = {
-  component: {
-    id: IDENTITY_COMPONENT_ID,
-    name: "identity",
-    version: "1.0.0"
-  },
-  shapes: [{ name: "Identity", fields: IDENTITY_FIELDS }],
-  credentials: [],
-  subscriptions: [],
-  seeds: [],
-  health: { requires: { shapes: ["Identity"] } },
-  teardown: {},
-  runtimeAccess: { reads: [], writes: [] }
-};
-var IDENTITY_COMPONENT = {
-  componentId: IDENTITY_COMPONENT_ID,
-  name: IDENTITY_MANIFEST.component.name,
-  version: IDENTITY_MANIFEST.component.version,
-  manifest: IDENTITY_MANIFEST,
-  shapes: [{ name: "Identity", fields: IDENTITY_FIELDS }]
-};
 
 // ../rules/src/system-components/system.ts
 var SYSTEM_COMPONENT_ID = "com.warmhub.system";
@@ -1483,8 +2469,7 @@ var SYSTEM_COMPONENT = {
 
 // ../rules/src/system-components/index.ts
 var SYSTEM_COMPONENTS = [
-  SYSTEM_COMPONENT,
-  IDENTITY_COMPONENT
+  SYSTEM_COMPONENT
 ];
 new Set(
   SYSTEM_COMPONENTS.filter((entry) => entry.installInfra === true).flatMap(
@@ -1492,6 +2477,16 @@ new Set(
   )
 );
 
+// src/shape-preflight.ts
+function shapeDefinitionPreflightError(name, data, verb) {
+  const result = validateShapeDefinition(
+    data,
+    verb === "revise" ? { allowUnsafeFieldNamePaths: collectUnsafeShapeFieldNamePaths(data) } : void 0
+  );
+  if (result.valid) return null;
+  return `Invalid shape definition for "${name}": ${result.errors.join("; ")}`;
+}
+
 // src/operation-normalize.ts
 function toBackendStreamOperation(operation) {
   if (operation.expectedVersion !== void 0 && operation.operation !== "revise") {
@@ -1513,7 +2508,7 @@ function toBackendStreamOperation(operation) {
     if (!name) {
       throw new Error("revise operation requires a target");
     }
-    const kind2 = operation.kind ?? inferKind(name, operation);
+    const kind2 = inferOperationKind({ kind: operation.kind, name });
     if (Object.hasOwn(operation, "active")) {
       throw new Error(
         `${kind2} revise operation no longer supports 'active' \u2014 use retract('${name}') instead`
@@ -1546,8 +2541,13 @@ function toBackendStreamOperation(operation) {
       ...operation.leaseId ? { leaseId: operation.leaseId } : {}
     };
   }
-  const kind = operation.kind ?? inferKind(operation.name, operation);
+  const kind = inferOperationKind(operation);
   const skipExisting = "skipExisting" in operation ? operation.skipExisting : void 0;
+  if (kind !== "collection" && ("type" in operation && operation.type !== void 0 || "members" in operation && operation.members !== void 0)) {
+    throw new Error(
+      `add operation '${operation.name ?? ""}' has collection fields but resolved kind '${kind}' \u2014 collection adds require both 'type' and 'members', or set kind: 'collection'`
+    );
+  }
   if (kind === "collection") {
     if (!("members" in operation) || !operation.members) {
       throw new Error("collection add operation requires 'members'");
@@ -1591,21 +2591,6 @@ function toBackendStreamOperation(operation) {
     ...skipExisting === true ? { skipExisting } : {}
   };
 }
-function inferKind(name, operation) {
-  if (operation.kind) {
-    return operation.kind;
-  }
-  if ("about" in operation && operation.about !== void 0) {
-    return "assertion";
-  }
-  if ("type" in operation && operation.type !== void 0 || "members" in operation && operation.members !== void 0) {
-    return "collection";
-  }
-  if (!name) {
-    return "shape";
-  }
-  return name.includes("/") ? "thing" : "shape";
-}
 
 // src/stream-submit.ts
 var DEFAULT_STREAM_CHUNK_SIZE = DEFAULT_STREAM_APPEND_CHUNK_SIZE;
@@ -2467,34 +3452,22 @@ function inferShapeForAdd(op) {
   }
   return void 0;
 }
-function inferKindFromName2(name) {
-  const parts = name.split("/").filter(Boolean);
-  if (parts.length >= 3) return "assertion";
-  if (parts.length === 2) return "thing";
-  return "thing";
-}
 function asNonEmptyString(value) {
   if (typeof value !== "string") return void 0;
   const trimmed = value.trim();
   return trimmed.length > 0 ? trimmed : void 0;
 }
 function normalizeAddKind(op) {
-  if (op.kind === "shape" || op.kind === "thing" || op.kind === "assertion" || op.kind === "collection") {
-    return op.kind;
-  }
-  if (op.type && Array.isArray(op.members)) {
-    return "collection";
-  }
-  if (op.about !== void 0 || op.aboutWref !== void 0) {
-    return "assertion";
-  }
-  return op.name ? inferKindFromName2(op.name) : "thing";
+  return inferOperationKind({
+    kind: op.kind,
+    name: op.name,
+    about: op.about ?? op.aboutWref,
+    type: op.type,
+    members: op.members
+  });
 }
 function normalizeReviseKind(op, name) {
-  if (op.kind === "shape" || op.kind === "thing" || op.kind === "assertion" || op.kind === "collection") {
-    return op.kind;
-  }
-  return inferKindFromName2(name);
+  return inferOperationKind({ kind: op.kind, name });
 }
 function toBackendOp(op) {
   if (op.operation === "retract") {
@@ -2605,13 +3578,13 @@ function preflightCheckCommon(verb, kind, name, data) {
       );
     }
   }
-  if (kind === "shape" && data !== void 0) {
-    const result = validateShapeDefinition(data);
-    if (!result.valid) {
-      errors.push(
-        `Invalid shape definition for "${name}": ${result.errors.join("; ")}`
-      );
-    }
+  if (kind === "shape" && (verb === "ADD" || verb === "REVISE") && data !== void 0) {
+    const preflight = shapeDefinitionPreflightError(
+      name,
+      data,
+      verb === "REVISE" ? "revise" : "add"
+    );
+    if (preflight) errors.push(preflight);
   }
   return errors;
 }
@@ -2620,6 +3593,18 @@ function preflightCheckAdd(op, kind) {
   if (op.name) {
     messages.push(...preflightCheckCommon("ADD", kind, op.name, op.data));
   }
+  if (kind === "assertion" && op.about === void 0 && op.aboutWref === void 0 && // Token-bearing names defer to validate() so the more specific token
+  // diagnostics surface instead of this eager check.
+  !(op.name && hasAnyTokens(op.name))) {
+    messages.push(
+      `ADD assertion '${op.name}' missing required 'about' \u2014 for hierarchical thing names set kind: 'thing' explicitly`
+    );
+  }
+  if (kind !== "collection" && (op.type !== void 0 || op.members !== void 0)) {
+    messages.push(
+      `ADD '${op.name}' has collection fields but inferred kind '${kind}' \u2014 collection adds require both 'type' and 'members', or set kind: 'collection'`
+    );
+  }
   for (const diagnostic of preflightOpDiagnostics(toPreflightOp(op, kind), 0)) {
     messages.push(diagnostic.message);
   }
@@ -2667,11 +3652,12 @@ function validateWarmHubClientOptions(options) {
     throw new TypeError(`Unknown WarmHubClient option "${key}"${hint}`);
   }
 }
-var SDK_VERSION = "0.51.0" ;
+var SDK_VERSION = "0.52.1" ;
 var DEFAULT_API_URL = "https://api.warmhub.ai";
 var UNBATCHED_TRPC_PATHS = /* @__PURE__ */ new Set([
   "repo.shapeInstanceCounts",
-  "thing.getMany"
+  "thing.getMany",
+  "thing.headVersions"
 ]);
 var DEFAULT_THING_GET_MANY_CHUNK_SIZE = 500;
 var MAX_THING_GET_MANY_CHUNK_SIZE = 500;
@@ -3165,27 +4151,13 @@ var WarmHubClient = class _WarmHubClient {
         throw toWarmHubError(error);
       }
     },
-    /**
-     * Install an allowlisted bundled system component into a repository.
-     */
-    installSystem: async (orgName, repoName, componentId) => {
-      try {
-        return await this.trpc.component.installSystem.mutate({
-          orgName,
-          repoName,
-          componentId
-        });
-      } catch (error) {
-        throw toWarmHubError(error);
-      }
-    },
     /**
      * Registered-component identity and install-pipeline operations.
      *
-     * This sub-surface drives the backend-mediated install flow that powers `wh component install <org/name>`. It manages registered component identities (`register`, `unregister`, `list`, `view`, `update`) and the install pipeline (`resolve` mints an install id, `downloadSource` fetches the source archive through the backend, `setupCall` dispatches the optional setup callback). Use these when building a custom installer; most callers should run the CLI instead.
+     * This sub-surface drives the backend-mediated install flow that powers `wh component install <org/name>`. It manages registered component identities (`register`, `unregister`, `list`, `view`, `update`) and the install pipeline (`resolve` returns the latest published manifest plus an install id, `setupCall` dispatches the optional setup callback). Use these when building a custom installer; most callers should run the CLI instead.
      */
     registry: {
-      register: async (orgName, componentName, input = {}) => {
+      register: async (orgName, componentName, input) => {
         try {
           return await this.trpc.component.registry.register.mutate({
             orgName,
@@ -3246,26 +4218,6 @@ var WarmHubClient = class _WarmHubClient {
           }
         );
       },
-      downloadSource: async (orgName, componentName, input) => {
-        const response = await this.requestResponse(
-          `/api/component-registry/${encodeURIComponent(orgName)}/${encodeURIComponent(componentName)}/source`,
-          {
-            method: "POST",
-            headers: {
-              "content-type": "application/json"
-            },
-            body: JSON.stringify(input)
-          }
-        );
-        return {
-          archive: new Uint8Array(await response.arrayBuffer()),
-          sourceUrl: response.headers.get("x-warmhub-source-url") ?? "",
-          sourceRef: response.headers.get("x-warmhub-source-ref") ?? void 0,
-          resolvedSha: response.headers.get("x-warmhub-resolved-sha") ?? void 0,
-          componentRef: response.headers.get("x-warmhub-component-ref") ?? `${orgName}/${componentName}`,
-          contentType: response.headers.get("content-type") || "application/octet-stream"
-        };
-      },
       setupCall: async (orgName, componentName, input) => {
         return await this.requestJson(
           `/api/component-registry/${encodeURIComponent(orgName)}/${encodeURIComponent(componentName)}/setup-call`,
@@ -4051,6 +5003,15 @@ var WarmHubClient = class _WarmHubClient {
      * @param opts.description Optional human-readable shape description.
      */
     create: async (orgName, repoName, shapeName, fields, opts) => {
+      const preflight = shapeDefinitionPreflightError(
+        shapeName,
+        {
+          fields,
+          ...opts?.description !== void 0 ? { description: opts.description } : {}
+        },
+        "add"
+      );
+      if (preflight) throw new WarmHubError("VALIDATION_ERROR", preflight);
       try {
         return await this.trpc.shape.create.mutate({
           orgName,
@@ -4073,6 +5034,15 @@ var WarmHubClient = class _WarmHubClient {
      * @param opts.description Optional human-readable description for the revised shape.
      */
     revise: async (orgName, repoName, shapeName, newFields, opts) => {
+      const preflight = shapeDefinitionPreflightError(
+        shapeName,
+        {
+          fields: newFields,
+          ...opts?.description !== void 0 ? { description: opts.description } : {}
+        },
+        "revise"
+      );
+      if (preflight) throw new WarmHubError("VALIDATION_ERROR", preflight);
       try {
         return await this.trpc.shape.revise.mutate({
           orgName,
@@ -4137,15 +5107,15 @@ var WarmHubClient = class _WarmHubClient {
     }
   };
   /**
-   * Webhook and cron subscription management surface scoped to a repository.
+   * Webhook subscription management surface scoped to a repository.
    *
    * @see https://docs.warmhub.ai/sdk/component-identity/#subscriptions
    */
   subscription = {
     /**
-     * Create a webhook or cron subscription.
+     * Create a webhook subscription.
      *
-     * Both subscription kinds require a delivery URL. Webhook subscriptions can also forward events from another repository, allow trace reentry, bind fallback delivery, and opt into success notifications. Component identity is set at creation time and follows the same authority rules as commit writes.
+     * Webhook subscriptions require a delivery URL and can forward events from another repository, allow trace reentry, bind fallback delivery, and opt into success notifications. Component identity is set at creation time and follows the same authority rules as commit writes.
      *
      * Webhook subscriptions must specify a shape filter via `shapeName` or `filterJson.shape`, except [shape-lifecycle subscriptions](/subscriptions/creating/#shape-lifecycle-subscriptions) which omit both and rely on a `{ kind: 'shape', ... }` filter.
      */
@@ -4174,6 +5144,27 @@ var WarmHubClient = class _WarmHubClient {
         throw toWarmHubError(error);
       }
     },
+    /**
+     * Reveal the raw webhook URL(s) for a subscription.
+     *
+     * Reads return only `webhookOrigin`/`fallbackWebhookOrigin` (scheme://host);
+     * the raw URL path is a bearer secret. This break-glass call returns the
+     * raw URL(s) and is audit-logged server-side. Requires `repo:configure`.
+     * Because it returns the secret, a name-scoped principal (e.g. a component
+     * setup token) may reveal only the subscriptions it is scoped to — a
+     * stricter contract than the redacted `get`/`list`, which are unscoped.
+     */
+    reveal: async (orgName, repoName, name) => {
+      try {
+        return await this.trpc.subscription.reveal.query({
+          orgName,
+          repoName,
+          name
+        });
+      } catch (error) {
+        throw toWarmHubError(error);
+      }
+    },
     /**
      * List subscriptions attached to a repository.
      */
@@ -4189,9 +5180,9 @@ var WarmHubClient = class _WarmHubClient {
       }
     },
     /**
-     * Update an existing webhook or cron subscription.
+     * Update an existing webhook subscription.
      *
-     * Use `null` for nullable fields such as fallback webhook URL when you need to clear an existing value.
+     * Use `null` for nullable fields such as fallback webhook URL when you need to clear an existing value. Legacy cron subscriptions cannot be updated — delete them instead.
      */
     update: async (input) => {
       try {
@@ -4652,6 +5643,62 @@ var WarmHubClient = class _WarmHubClient {
         throw toWarmHubError(error);
       }
     },
+    /**
+     * Batched lightweight per-thing change probe — returns
+     * `{ wref, durableId, version, active, versionCreatedAt }` per wref with NO
+     * payload. Use it to check whether locally-cached copies are still fresh
+     * without pulling `data`: a value is stale if `durableId` differs (the wref
+     * now points to a different thing), `version`/`active` differ (the same
+     * thing changed/was retracted), or the wref appears in `missing`.
+     *
+     * Auto-chunks above the backend's 500-wref transport cap; preserves
+     * duplicate requested wrefs and reports inaccessible/unknown refs in
+     * `missing` rather than throwing per item.
+     *
+     * @param opts.chunkSize Maximum wrefs per backend request. Defaults to 500 and is clamped to the backend cap.
+     * @param opts.chunkConcurrency Maximum concurrent chunk requests. Defaults to 1 and is clamped to 8.
+     */
+    headVersions: async (orgName, repoName, wrefs, opts) => {
+      try {
+        if (wrefs.length === 0) {
+          return { requested: 0, items: [], missing: [] };
+        }
+        const chunkSize = normalizePositiveIntegerOption(
+          opts?.chunkSize,
+          DEFAULT_THING_GET_MANY_CHUNK_SIZE,
+          MAX_THING_GET_MANY_CHUNK_SIZE
+        );
+        const chunkConcurrency = normalizePositiveIntegerOption(
+          opts?.chunkConcurrency,
+          DEFAULT_THING_GET_MANY_CHUNK_CONCURRENCY,
+          MAX_THING_GET_MANY_CHUNK_CONCURRENCY
+        );
+        const fetchChunk = async (chunkWrefs) => {
+          return await this.trpc.thing.headVersions.query({
+            orgName,
+            repoName,
+            wrefs: chunkWrefs
+          });
+        };
+        if (wrefs.length <= chunkSize) {
+          return await fetchChunk(wrefs);
+        }
+        const chunks = chunkArray(wrefs, chunkSize);
+        const chunkResults = [];
+        for (let start = 0; start < chunks.length; start += chunkConcurrency) {
+          const batch = chunks.slice(start, start + chunkConcurrency);
+          const batchResults = await Promise.all(batch.map(fetchChunk));
+          chunkResults.push(...batchResults);
+        }
+        return {
+          requested: wrefs.length,
+          items: chunkResults.flatMap((result) => result.items),
+          missing: chunkResults.flatMap((result) => result.missing)
+        };
+      } catch (error) {
+        throw toWarmHubError(error);
+      }
+    },
     /**
      * Return version history and timeline metadata for repository records.
      *
@@ -5558,5 +6605,5 @@ function isAbortError(error) {
 }
 
 export { AllStreamOperationsFailedError, CLI_INSTALL_REPO_HEADER, CLI_SIGNATURE_HEADER, CLI_TIMESTAMP_HEADER, CONTENT_FIELD_LIMIT_ERROR, CliCallVerificationError, DEFAULT_API_URL, DEFAULT_STREAM_CHUNK_SIZE, MAX_CONTENT_FIELD_BYTES, MAX_STREAM_APPEND_OPERATION_COUNT2 as MAX_STREAM_APPEND_OPERATION_COUNT, OperationBuilder, PartialStreamSubmissionError, SDK_VERSION, WarmHubClient, WarmHubError, connectionErrorMessage, contentFieldLimitError, countStreamAppendResultStatuses, isConnectionError, isRetryable, isWarmHubError, normalizeWref, resolveFunctionLogMode, sanitizeErrorMessage, sdkVersionIsBelowMinimum, streamAppendResultStatus, submitOperationsViaStream, toWarmHubError, validateAgainstShape, verifyCliCall };
-//# sourceMappingURL=chunk-ZTDMTDJ6.js.map
-//# sourceMappingURL=chunk-ZTDMTDJ6.js.map
+//# sourceMappingURL=chunk-OPTB23HY.js.map
+//# sourceMappingURL=chunk-OPTB23HY.js.map