@warmhub/cli 0.116.0 → 0.118.0

package/dist/wh.js

@@ -18071,6 +18071,8 @@ function manifestShapeData(shape) {
   const data = { fields: shape.fields };
   if (shape.description !== undefined)
     data.description = shape.description;
+  if (shape.composes !== undefined)
+    data.composes = shape.composes;
   return data;
 }
 function shapeDataEquals(left, right) {
@@ -18576,8 +18578,9 @@ function optionalStringArray(obj, field, path, errors) {
     return;
   }
   for (let i = 0;i < obj[field].length; i++) {
-    if (typeof obj[field][i] !== "string") {
-      errors.push(`${path}.${field}[${i}] must be a string`);
+    const entry = obj[field][i];
+    if (typeof entry !== "string" || entry.length === 0) {
+      errors.push(`${path}.${field}[${i}] must be a non-empty string`);
     }
   }
 }
@@ -18602,6 +18605,7 @@ var ALLOWED_SHAPE_KEYS = new Set([
   "name",
   "description",
   "fields",
+  "composes",
   "provisioning"
 ]);
 var VALID_PROVISIONING_VALUES = new Set(["manifest", "setup"]);
@@ -18648,6 +18652,9 @@ function validateShape(shape, i, errors) {
   if (!isObject(shape.fields)) {
     errors.push(`${path}.fields must be an object`);
   }
+  if ("composes" in shape) {
+    optionalStringArray(shape, "composes", path, errors);
+  }
   validateProvisioning(shape, path, errors);
 }
 function validateCredential(cred, i, errors) {
@@ -34441,6 +34448,30 @@ var BASE_PRIMITIVE_TYPES = [
   "wref",
   "array"
 ];
+var WREF_BINDING_MODES = ["identity", "versioned", "either"];
+var WREF_BINDING_MODES_DIAGNOSTIC = `${WREF_BINDING_MODES.slice(0, -1).join(", ")}, or ${WREF_BINDING_MODES.at(-1)}`;
+var WREF_BINDING_MODE_SET = new Set(WREF_BINDING_MODES);
+function isWrefBindingMode(value) {
+  return typeof value === "string" && WREF_BINDING_MODE_SET.has(value);
+}
+function wrefBindingConstraintError(path, spec) {
+  if (!("binding" in spec) || !("type" in spec))
+    return null;
+  if (typeof spec.type !== "string" || !VALID_PRIMITIVE_TYPES.has(spec.type)) {
+    return null;
+  }
+  if (typeof spec.binding === "string" && VALID_PRIMITIVE_TYPES.has(spec.binding)) {
+    return null;
+  }
+  const type = spec.type.endsWith("?") ? spec.type.slice(0, -1) : spec.type;
+  if (type !== "wref") {
+    return `Constraint "binding" at "${path}" is only valid for type "wref"`;
+  }
+  if (!isWrefBindingMode(spec.binding)) {
+    return `"binding" at "${path}" must be ${WREF_BINDING_MODES_DIAGNOSTIC}`;
+  }
+  return null;
+}
 var BASE_PRIMITIVE_TYPE_SET = new Set(BASE_PRIMITIVE_TYPES);
 var VALID_PRIMITIVE_TYPES = new Set([
   ...BASE_PRIMITIVE_TYPES,
@@ -34456,7 +34487,7 @@ var STRING_CONSTRAINT_KEYS = new Set([
   "enum"
 ]);
 var NUMBER_CONSTRAINT_KEYS = new Set(["minimum", "maximum", "integer"]);
-var WREF_CONSTRAINT_KEYS = new Set(["shape"]);
+var WREF_CONSTRAINT_KEYS = new Set(["shape", "binding"]);
 var ARRAY_CONSTRAINT_KEYS = new Set(["items", "minItems", "maxItems"]);
 var COMMON_TYPESPEC_KEYS = new Set(["type", "description"]);
 var VALID_TYPESPEC_KEYS = new Set([
@@ -34502,6 +34533,8 @@ function isTypeSpecObject(value) {
     return false;
   if ("shape" in value && typeof value.shape !== "string")
     return false;
+  if ("binding" in value && !isWrefBindingMode(value.binding))
+    return false;
   if ("shape" in value && typeof value.shape === "string" && VALID_PRIMITIVE_TYPES.has(value.shape)) {
     if (baseType !== "wref")
       return false;
@@ -34572,7 +34605,8 @@ function formatTypeSpecDisplay(spec) {
   const typeName = isOptional ? baseType.slice(0, -1) : baseType;
   const suffix = isOptional ? "?" : "";
   if (typeName === "wref" && typeof spec.shape === "string") {
-    return `wref${suffix}<${spec.shape}>`;
+    const typed = `wref${suffix}<${spec.shape}>`;
+    return isWrefBindingMode(spec.binding) ? `${typed} (binding: ${spec.binding})` : typed;
   }
   if (typeName === "array" && "items" in spec) {
     const elementDisplay = displayFieldType(spec.items);
@@ -41201,6 +41235,11 @@ function validateTypeSpec(path, identityPath, spec, errors3, context) {
     return;
   }
   if (isPlainObject2(spec)) {
+    const bindingError = wrefBindingConstraintError(path, spec);
+    if (bindingError) {
+      errors3.push(bindingError);
+      return;
+    }
     if (isTypeSpecObject(spec)) {
       validateTypedFieldObject(path, identityPath, spec, errors3, context);
       return;
@@ -41398,7 +41437,7 @@ function validationContext(options = {}) {
 function isAllowedLegacyUnsafeFieldPath2(context, path) {
   return context.allowUnsafeFieldNamePaths.has(path);
 }
-var ALLOWED_SHAPE_KEYS2 = new Set(["fields", "description"]);
+var ALLOWED_SHAPE_KEYS2 = new Set(["fields", "description", "composes"]);
 function collectIndexableShapeFieldPaths(fields, prefix = "") {
   const paths = [];
   for (const [key, value] of Object.entries(fields)) {
@@ -41546,6 +41585,11 @@ function validateShapeDefinition(data, options = {}) {
   if ("description" in obj && typeof obj.description !== "string") {
     errors3.push('"description" must be a string');
   }
+  if ("composes" in obj) {
+    if (!Array.isArray(obj.composes) || !obj.composes.every((value) => typeof value === "string" && value.length > 0)) {
+      errors3.push('"composes" must be an array of non-empty Shape wrefs');
+    }
+  }
   validatePersistedContentLimits(obj, [], errors3);
   if (errors3.length > 0) {
     return { valid: false, errors: errors3 };
@@ -41596,10 +41640,17 @@ var SYSTEM_COMPONENT = {
   name: SYSTEM_MANIFEST.component.name,
   version: SYSTEM_MANIFEST.component.version,
   manifest: SYSTEM_MANIFEST,
-  installInfra: true,
   shapes: [
-    { name: "ComponentInstall", fields: COMPONENT_INSTALL_FIELDS },
-    { name: "ComponentConfig", fields: COMPONENT_CONFIG_FIELDS }
+    {
+      name: "ComponentInstall",
+      fields: COMPONENT_INSTALL_FIELDS,
+      installInfra: true
+    },
+    {
+      name: "ComponentConfig",
+      fields: COMPONENT_CONFIG_FIELDS,
+      installInfra: true
+    }
   ]
 };
 
@@ -41607,7 +41658,7 @@ var SYSTEM_COMPONENT = {
 var SYSTEM_COMPONENTS = [
   SYSTEM_COMPONENT
 ];
-var SYSTEM_INFRA_SHAPE_NAMES = new Set(SYSTEM_COMPONENTS.filter((entry) => entry.installInfra === true).flatMap((entry) => entry.shapes.map((s) => s.name)));
+var SYSTEM_INFRA_SHAPE_NAMES = new Set(SYSTEM_COMPONENTS.flatMap((entry) => entry.shapes.filter((shape) => shape.installInfra === true).map((shape) => shape.name)));
 function findSystemComponent(componentId) {
   return SYSTEM_COMPONENTS.find((entry) => entry.componentId === componentId);
 }
@@ -45261,7 +45312,7 @@ function createStreamingSubmissionHandle(input, deps) {
 // ../../packages/sdk-ts/package.json
 var package_default = {
   name: "@warmhub/sdk-ts",
-  version: "0.114.0",
+  version: "0.116.0",
   private: false,
   type: "module",
   description: "The TypeScript SDK for WarmHub — create repos, commit and query data, and compound knowledge with your AI agents.",
@@ -46674,6 +46725,30 @@ class WarmHubClient {
         } catch (error51) {
           throw toWarmHubError(error51);
         }
+      },
+      pin: async (orgName, repoName, shape, fieldPath) => {
+        try {
+          return await this.trpc.repo.index.pin.mutate({
+            orgName,
+            repoName,
+            shape,
+            fieldPath
+          });
+        } catch (error51) {
+          throw toWarmHubError(error51);
+        }
+      },
+      unpin: async (orgName, repoName, shape, fieldPath) => {
+        try {
+          return await this.trpc.repo.index.unpin.mutate({
+            orgName,
+            repoName,
+            shape,
+            fieldPath
+          });
+        } catch (error51) {
+          throw toWarmHubError(error51);
+        }
       }
     }
   };
@@ -46707,7 +46782,8 @@ class WarmHubClient {
     create: async (orgName, repoName, shapeName, fields, opts) => {
       const preflight = shapeDefinitionPreflightError(shapeName, {
         fields,
-        ...opts.description !== undefined ? { description: opts.description } : {}
+        ...opts.description !== undefined ? { description: opts.description } : {},
+        ...opts.composes !== undefined ? { composes: opts.composes } : {}
       }, "add");
       if (preflight)
         throw new WarmHubError("VALIDATION_ERROR", preflight);
@@ -46718,7 +46794,8 @@ class WarmHubClient {
           shapeName,
           fields,
           eventRequestId: opts.eventRequestId,
-          description: opts.description
+          description: opts.description,
+          composes: opts.composes
         });
       } catch (error51) {
         throw toWarmHubError(error51);
@@ -46727,7 +46804,8 @@ class WarmHubClient {
     revise: async (orgName, repoName, shapeName, newFields, opts) => {
       const preflight = shapeDefinitionPreflightError(shapeName, {
         fields: newFields,
-        ...opts.description !== undefined ? { description: opts.description } : {}
+        ...opts.description !== undefined ? { description: opts.description } : {},
+        ...opts.composes !== undefined ? { composes: opts.composes } : {}
       }, "revise");
       if (preflight)
         throw new WarmHubError("VALIDATION_ERROR", preflight);
@@ -46738,7 +46816,8 @@ class WarmHubClient {
           shapeName,
           newFields,
           eventRequestId: opts.eventRequestId,
-          description: opts.description
+          description: opts.description,
+          composes: opts.composes
         });
       } catch (error51) {
         throw toWarmHubError(error51);
@@ -47208,6 +47287,8 @@ class WarmHubClient {
           orgName,
           repoName,
           shape: opts?.shape,
+          declaredShape: opts?.declaredShape,
+          includeValidatedShapes: opts?.includeValidatedShapes,
           kind: narrowKind(opts?.kind),
           match: opts?.match,
           dataMode: opts?.dataMode,
@@ -47371,6 +47452,7 @@ class WarmHubClient {
           repoName,
           wref: opts.wref,
           shape: opts.shape,
+          declaredShape: opts.declaredShape,
           about: opts.about,
           includeRetracted: opts.includeRetracted,
           resolveCollections: opts.resolveCollections,
@@ -47447,6 +47529,8 @@ class WarmHubClient {
           orgName,
           repoName,
           shape: opts?.shape,
+          declaredShape: opts?.declaredShape,
+          includeValidatedShapes: opts?.includeValidatedShapes,
           about: opts?.about,
           affirmedAbout: opts?.affirmedAbout,
           kind: narrowKind(opts?.kind),
@@ -47522,6 +47606,7 @@ class WarmHubClient {
           orgName,
           repoName,
           shape: opts?.shape,
+          declaredShape: opts?.declaredShape,
           about: opts?.about,
           affirmedAbout: opts?.affirmedAbout,
           kind: narrowKind(opts?.kind),
@@ -47546,6 +47631,7 @@ class WarmHubClient {
           wref,
           direction: opts?.direction,
           fieldPath: opts?.fieldPath,
+          binding: opts?.binding,
           limit: opts?.limit,
           cursor: opts?.cursor
         });
@@ -47565,6 +47651,8 @@ class WarmHubClient {
     thingHead: async (orgName, repoName, opts, onUpdate) => {
       return this.watchRepoQuery(orgName, repoName, opts?.signal, () => this.thing.head(orgName, repoName, {
         shape: opts?.shape,
+        declaredShape: opts?.declaredShape,
+        includeValidatedShapes: opts?.includeValidatedShapes,
         kind: opts?.kind,
         match: opts?.match,
         dataMode: opts?.dataMode,
@@ -47577,6 +47665,11 @@ class WarmHubClient {
     thingHistory: async (orgName, repoName, opts, onUpdate) => {
       return this.watchRepoQuery(orgName, repoName, opts.signal, () => this.thing.history(orgName, repoName, {
         wref: opts.wref,
+        shape: opts.shape,
+        declaredShape: opts.declaredShape,
+        about: opts.about,
+        resolveCollections: opts.resolveCollections,
+        match: opts.match,
         limit: opts.limit,
         cursor: opts.cursor,
         includeRetracted: opts.includeRetracted
@@ -48440,6 +48533,12 @@ function generateSuggestions(code, message, context, errorCode) {
     }
   }
   if (code === "FIELD_NOT_INDEXABLE") {
+    if (message.includes("field-not-declared")) {
+      suggestions.push({
+        action: "Declare the field path for indexing, then retry",
+        command: "wh repo index pin <Shape> <field.path>"
+      });
+    }
     suggestions.push({
       action: "Inspect indexed field state for the repo",
       command: "wh repo describe --indexed-fields"
@@ -50679,6 +50778,8 @@ async function checkCompatibility(ctx, domainPath, canonicalVerb, args) {
     if (clientFlags.length > 0)
       capabilities = await probeCapabilities(ctx);
   }
+  if (capabilities)
+    ctx.capabilities = capabilities;
   if (clientFlags.length === 0 || !capabilities)
     return;
   const echoed = capabilities.honoredClientFlags;
@@ -52116,6 +52217,9 @@ function renderWarningLine(out, c, chars, op) {
     return;
   renderUndeclaredFieldsWarning(out, c, chars, op.name, warnings);
   renderCoalescedWrefsWarning(out, c, chars, warnings);
+  for (const entry of warnings.ignoredVersionPins ?? []) {
+    out(`    ${c.yellow}${chars.warn}${c.reset} ignored version pin ${escapeInlineTerminalText(entry.fieldPath)}: ${c.dim}${escapeInlineTerminalText(entry.wref)}${c.reset} (field binding is ${escapeInlineTerminalText(entry.binding)}; the reference follows the Thing)`);
+  }
   for (const warning of warnings.deprecations ?? []) {
     out(`    ${c.yellow}${chars.warn}${c.reset} ${escapeInlineTerminalText(warning.shape)} deprecated (de-emphasis milestone ${escapeInlineTerminalText(warning.removalMilestone)}): ${escapeInlineTerminalText(warning.message)}`);
   }
@@ -52236,7 +52340,7 @@ function emitPartialPageHint(ctx, count, _nextCursor, _limit) {
 }
 
 // ../../packages/warmhub-cli/src/domains/commit-output-contract-id.ts
-var COMMIT_SUBMIT_OUTPUT_SCHEMA_ID = "wh.commit.submit.result/v0.3";
+var COMMIT_SUBMIT_OUTPUT_SCHEMA_ID = "wh.commit.submit.result/v0.4";
 function identifyCommitSubmitOutput(value) {
   if ("schema" in value) {
     if (value.schema === COMMIT_SUBMIT_OUTPUT_SCHEMA_ID) {
@@ -52953,6 +53057,9 @@ var handleCreate2 = async (ctx, { flags, args }) => {
 };
 
 // ../../packages/warmhub-cli/src/domains/thing/render.ts
+function singularShapeName(result) {
+  return result.shapeName ?? result.shape;
+}
 function renderHead(out, c, chars, result, org, repo, shape, kind) {
   const items = result.items ?? [];
   const decorations = getResponseDecorations(result);
@@ -52968,6 +53075,12 @@ function renderHead(out, c, chars, result, org, repo, shape, kind) {
     const kl = kindLabel(c, effectiveKind(item.kind ?? "thing", shapeName));
     const retractedTag = item.active === false ? `  ${c.red}[RETRACTED]${c.reset}` : "";
     out(`  ${wref}  ${kl}${retractedTag}`);
+    if (item.declaredShapes?.length) {
+      out(`    ${c.dim}declares:${c.reset} ${refList(c, item.declaredShapes, decorations)}`);
+    }
+    if (item.validatedShapes?.length) {
+      out(`    ${c.dim}validates:${c.reset} ${refList(c, item.validatedShapes, decorations)}`);
+    }
     if (item.kind === "assertion" && item.aboutWref) {
       out(`    ${c.dim}about:${c.reset} ${refDisplay(c, item.aboutWref, decorations)}`);
     }
@@ -52991,19 +53104,26 @@ function renderHead(out, c, chars, result, org, repo, shape, kind) {
 function renderThing(out, c, result) {
   const decorations = getResponseDecorations(result);
   const wref = result.wref ?? result.name ?? "(unknown)";
-  const shapeName = result.shapeName ?? result.shape;
+  const shapeName = singularShapeName(result);
   const displayKind = effectiveKind(result.kind ?? "thing", shapeName);
   const retractedTag = result.active === false ? `  ${c.red}[RETRACTED]${c.reset}` : "";
   out(`${pinnedWref(c, wref, result.version)}  ${kindLabel(c, displayKind)}${retractedTag}`);
   out(`  ${c.dim}wref:${c.reset}      ${escapeTerminalTextForDisplay(wref)}`);
   out(`  ${c.dim}version:${c.reset}   ${result.version ?? "-"}`);
   out(`  ${c.dim}active:${c.reset}    ${String(result.active)}`);
+  if (result.declaredShapes?.length) {
+    out(`  ${c.dim}declares:${c.reset}  ${refList(c, result.declaredShapes, decorations)}`);
+  }
+  if (result.validatedShapes?.length) {
+    out(`  ${c.dim}validates:${c.reset} ${refList(c, result.validatedShapes, decorations)}`);
+  }
   if (result.committerWref) {
     out(`  ${c.dim}by:${c.reset}        ${refDisplay(c, result.committerWref, decorations)}`);
   }
   const aboutWref = result.aboutWref ?? result.about;
-  if (aboutWref) {
-    out(`  ${c.dim}about:${c.reset}     ${decoratedRef(c, String(aboutWref), decorations) ?? escapeTerminalTextForDisplay(String(aboutWref))}`);
+  const aboutText = typeof aboutWref === "string" ? aboutWref : JSON.stringify(aboutWref);
+  if (aboutText) {
+    out(`  ${c.dim}about:${c.reset}     ${decoratedRef(c, aboutText, decorations) ?? escapeTerminalTextForDisplay(aboutText)}`);
   }
   if (result.affirmedWrefs?.length) {
     out(`  ${c.dim}affirms:${c.reset}   ${refList(c, result.affirmedWrefs, decorations)}`);
@@ -53074,9 +53194,9 @@ function renderGraphValue(out, c, value, indent, decorations) {
   }
   renderGraphNode(out, c, value, indent, decorations);
 }
-function renderGraphNode(out, c, result, indent = "", decorations = undefined) {
+function renderGraphNode(out, c, result, indent = "", decorations) {
   const wref = result.wref ?? result.name ?? "(unknown)";
-  const shapeName = result.shapeName ?? result.shape;
+  const shapeName = singularShapeName(result);
   const displayKind = effectiveKind(result.kind ?? "thing", shapeName);
   out(`${indent}${pinnedWref(c, wref, result.version)}  ${kindLabel(c, displayKind)}`);
   if (result.about) {
@@ -53144,6 +53264,12 @@ function renderHistory(out, c, result) {
     const createdOn = ver.metadata?.createdOn;
     const thingCreatedStr = createdOn ? `  ${c.dim}born:${formatTime(createdOn, now)}${c.reset}` : "";
     out(`  ${wrefStr}  ${op}  ${c.dim}${time3}${c.reset}${by}${thingCreatedStr}`);
+    if (ver.declaredShapes?.length) {
+      out(`    ${c.dim}declares:${c.reset} ${refList(c, ver.declaredShapes, decorations)}`);
+    }
+    if (ver.validatedShapes?.length) {
+      out(`    ${c.dim}validates:${c.reset} ${refList(c, ver.validatedShapes, decorations)}`);
+    }
     const affirmed = ver.affirmedWrefs;
     if (Array.isArray(affirmed) && affirmed.length > 0) {
       out(`    ${c.dim}affirms:${c.reset} ${refList(c, affirmed.map(String), decorations)}`);
@@ -53164,7 +53290,8 @@ function renderRefs(out, c, result, wref, direction) {
     const refWref = refDisplay(c, item.wref, decorations, item.version);
     const kl = kindLabel(c, effectiveKind(item.kind ?? "thing", item.shapeName));
     const field = `${c.dim}via ${c.reset}${escapeTerminalTextForDisplay(item.fieldPath ?? "(unknown)")}`;
-    out(`  ${refWref}  ${kl}  ${field}`);
+    const binding = item.binding ? `  ${c.dim}${item.binding}${c.reset}` : "";
+    out(`  ${refWref}  ${kl}  ${field}${binding}`);
   }
   out(`${c.dim}${items.length} ref(s)${c.reset}`);
 }
@@ -53240,6 +53367,9 @@ var handleThingGraph = async (ctx, { flags, args }) => {
 // ../../packages/warmhub-cli/src/domains/thing/history.ts
 var historyFlags = {
   shape: flag.string({ description: "Filter by shape" }),
+  "declared-shape": flag.string({
+    description: "Filter by directly declared shape"
+  }),
   limit: flag.number({
     description: "Maximum versions per page (default: 50, max: 500)"
   }),
@@ -53257,6 +53387,7 @@ var handleHistory = async (ctx, { flags, args }) => {
   const wref = args[0];
   const { org, repo } = wref !== undefined && looksLikeDurableId(wref) ? parseOrgRepoOptional(getRepoRef(ctx), ctx.config) : parseOrgRepo(getRepoRef(ctx), ctx.config);
   const shape = flags.shape;
+  const declaredShape = flags["declared-shape"];
   const about = flags.about;
   const limit = flags.limit;
   const cursor = flags.cursor;
@@ -53274,6 +53405,7 @@ var handleHistory = async (ctx, { flags, args }) => {
   const historyOpts = {
     wref,
     shape,
+    declaredShape,
     about,
     includeRetracted,
     resolveCollections,
@@ -53300,23 +53432,28 @@ var handleHistory = async (ctx, { flags, args }) => {
     });
     return;
   }
-  const result = all ? await fetchAllHistoryPages(ctx, org, repo, {
+  const fetched = all ? await fetchAllHistoryPages(ctx, org, repo, {
     wref,
     shape,
+    declaredShape,
     about,
     includeRetracted,
     resolveCollections,
     limit: pageLimit,
     cursor
-  }) : await ctx.client.thing.history(org, repo, {
-    wref,
-    shape,
-    about,
-    includeRetracted,
-    resolveCollections,
-    limit: boundedLimit,
-    cursor
-  });
+  }) : {
+    result: await ctx.client.thing.history(org, repo, {
+      wref,
+      shape,
+      declaredShape,
+      about,
+      includeRetracted,
+      resolveCollections,
+      limit: boundedLimit,
+      cursor
+    })
+  };
+  const { result, refusal } = fetched;
   if (!all && result.nextCursor) {
     emitPartialPageHint(ctx, (result.versions ?? []).length, result.nextCursor, boundedLimit);
   }
@@ -53325,34 +53462,48 @@ var handleHistory = async (ctx, { flags, args }) => {
     nextCursor: result.nextCursor ?? null,
     decorations: getResponseDecorations(result)
   }, () => renderHistory(ctx.out, ctx.colors, result));
+  if (refusal) {
+    ctx.err(`history stopped after ${(result.versions ?? []).length} version(s): the backend refused further refill (${refusal.code}). Narrow the filter to continue.`);
+    throw refusal;
+  }
 };
 async function fetchAllHistoryPages(ctx, org, repo, opts) {
   const versions2 = [];
   let decorations;
   let thing;
-  for await (const page of paginatePages2({
-    initialCursor: opts.cursor,
-    fetchPage: (cursor) => ctx.client.thing.history(org, repo, {
-      wref: opts.wref,
-      shape: opts.shape,
-      about: opts.about,
-      includeRetracted: opts.includeRetracted,
-      resolveCollections: opts.resolveCollections,
-      limit: opts.limit,
-      cursor
-    }),
-    title: "Thing history"
-  })) {
-    if (!thing && page.thing)
-      thing = page.thing;
-    versions2.push(...page.versions ?? []);
-    decorations = mergeDecorations(decorations, getResponseDecorations(page));
+  let refusal;
+  try {
+    for await (const page of paginatePages2({
+      initialCursor: opts.cursor,
+      fetchPage: (cursor) => ctx.client.thing.history(org, repo, {
+        wref: opts.wref,
+        shape: opts.shape,
+        declaredShape: opts.declaredShape,
+        about: opts.about,
+        includeRetracted: opts.includeRetracted,
+        resolveCollections: opts.resolveCollections,
+        limit: opts.limit,
+        cursor
+      }),
+      title: "Thing history"
+    })) {
+      if (!thing && page.thing)
+        thing = page.thing;
+      versions2.push(...page.versions ?? []);
+      decorations = mergeDecorations(decorations, getResponseDecorations(page));
+    }
+  } catch (error51) {
+    if (!(isWarmHubError(error51) && error51.code === "QUERY_TOO_EXPENSIVE")) {
+      throw error51;
+    }
+    refusal = error51;
   }
-  return withDecorations({
+  const result = withDecorations({
     ...thing === undefined ? {} : { thing },
     versions: versions2,
     nextCursor: undefined
   }, decorations);
+  return refusal ? { result, refusal } : { result };
 }
 
 // ../../packages/warmhub-cli/src/domains/thing/lease.ts
@@ -53496,6 +53647,12 @@ function coerceValue(s) {
 // ../../packages/warmhub-cli/src/domains/thing/list.ts
 var headFlags = {
   shape: flag.string({ description: "Filter by shape" }),
+  "declared-shape": flag.string({
+    description: "Filter by directly declared shape"
+  }),
+  "include-validated-shapes": flag.boolean({
+    description: "Include the full certified shape closure"
+  }),
   kind: flag.string({ description: "Filter by kind" }),
   limit: flag.number({
     description: "Max items per page (default: 50, max: 500)"
@@ -53524,6 +53681,8 @@ var headFlags = {
 var handleHead = async (ctx, { flags, args }) => {
   const { org, repo } = parseOrgRepo(getRepoRef(ctx) ?? args[0], ctx.config);
   const shape = flags.shape;
+  const declaredShape = flags["declared-shape"];
+  const includeValidatedShapes = flags["include-validated-shapes"];
   const kind = validateKind(flags.kind);
   const limit = flags.limit;
   const cursor = flags.cursor;
@@ -53538,6 +53697,9 @@ var handleHead = async (ctx, { flags, args }) => {
     usageError("--since-repo-seq cannot be used with --live.", "wh thing list --since-repo-seq 42 --all --format json");
   }
   if (count) {
+    if (includeValidatedShapes) {
+      usageError("--include-validated-shapes cannot be used with --count.", "wh thing list --declared-shape Player --count");
+    }
     if (cursor || all || limit || ctx.liveMode) {
       usageError("Usage: wh thing list --count [--shape SHAPE] [--kind KIND] [--match PATTERN] [--since-repo-seq N]", "wh thing list --shape Player --count --since-repo-seq 42");
     }
@@ -53546,12 +53708,13 @@ var handleHead = async (ctx, { flags, args }) => {
     validateComponentFilters(componentRef2, strictExclude2, "wh thing list --component acme/veritas");
     return handleCount(ctx, org, repo, {
       shape,
+      declaredShape,
       kind,
       match,
       includeRetracted,
       componentRef: componentRef2,
       excludeComponents: strictExclude2,
-      excludeInfraShapes: !strictExclude2 && !shape,
+      excludeInfraShapes: !strictExclude2 && !shape && !declaredShape,
       where: where.length > 0 ? where : undefined,
       ...sinceRepoSeq === undefined ? {} : { sinceRepoSeq }
     });
@@ -53565,13 +53728,15 @@ var handleHead = async (ctx, { flags, args }) => {
   const boundedLimit = Math.min(limit ?? DEFAULT_PAGE_LIMIT, MAX_PAGE_LIMIT);
   const pageLimit = all ? Math.min(limit ?? AUTO_PAGE_LIMIT, MAX_PAGE_LIMIT) : boundedLimit;
   const componentRef = flags.component;
-  const hasShape = !!shape;
+  const hasShape = !!shape || !!declaredShape;
   const strictExclude = !!flags["exclude-components"];
   validateComponentFilters(componentRef, strictExclude, "wh thing list --component acme/veritas");
   const excludeComponents = strictExclude;
   const excludeInfraShapes = !strictExclude && !hasShape;
   const headOpts = {
     shape,
+    declaredShape,
+    includeValidatedShapes,
     kind,
     match,
     includeRetracted,
@@ -53608,6 +53773,8 @@ var handleHead = async (ctx, { flags, args }) => {
   const streamJsonl = all && ctx.format === "jsonl";
   const result = all ? await fetchAllHeadPages(ctx, org, repo, {
     shape,
+    declaredShape,
+    includeValidatedShapes,
     kind,
     match,
     includeRetracted,
@@ -53623,6 +53790,8 @@ var handleHead = async (ctx, { flags, args }) => {
     return await ctx.flushOut?.() ?? true;
   } : undefined) : await ctx.client.thing.head(org, repo, {
     shape,
+    declaredShape,
+    includeValidatedShapes,
     kind,
     match,
     includeRetracted,
@@ -53652,6 +53821,8 @@ async function fetchAllHeadPages(ctx, org, repo, opts, onPage) {
     initialCursor: opts.cursor,
     fetchPage: (cursor) => ctx.client.thing.head(org, repo, {
       shape: opts.shape,
+      declaredShape: opts.declaredShape,
+      includeValidatedShapes: opts.includeValidatedShapes,
       kind: opts.kind,
       match: opts.match,
       includeRetracted: opts.includeRetracted,
@@ -53672,6 +53843,12 @@ async function fetchAllHeadPages(ctx, org, repo, opts, onPage) {
 // ../../packages/warmhub-cli/src/domains/thing/query.ts
 var queryFlags = {
   shape: flag.string({ description: "Filter by shape" }),
+  "declared-shape": flag.string({
+    description: "Filter by directly declared shape"
+  }),
+  "include-validated-shapes": flag.boolean({
+    description: "Include the full certified shape closure"
+  }),
   kind: flag.string({ description: "Filter by kind" }),
   about: flag.string({ description: "Filter by about wref" }),
   "affirmed-about": flag.string({
@@ -53710,6 +53887,8 @@ var queryFlags = {
 var handleQuery = async (ctx, { flags }) => {
   const { org, repo } = parseOrgRepo(getRepoRef(ctx), ctx.config);
   const shape = flags.shape;
+  const declaredShape = flags["declared-shape"];
+  const includeValidatedShapes = flags["include-validated-shapes"];
   const about = flags.about;
   const affirmedAbout = flags["affirmed-about"];
   const kind = validateKind(flags.kind);
@@ -53723,7 +53902,7 @@ var handleQuery = async (ctx, { flags }) => {
   const resolveCollections = flags["resolve-collections"];
   const role = parseCollectionRoleFlag(flags.role, "wh thing query --about Player/alice --resolve-collections --role from");
   const componentRef = flags.component;
-  const hasShape = !!shape;
+  const hasShape = !!shape || !!declaredShape;
   const strictExclude = !!flags["exclude-components"];
   validateComponentFilters(componentRef, strictExclude, "wh thing query --component acme/veritas");
   const excludeComponents = strictExclude;
@@ -53735,11 +53914,15 @@ var handleQuery = async (ctx, { flags }) => {
     usageError("--since-repo-seq cannot be used with --live.", "wh thing query --since-repo-seq 42 --all --format json");
   }
   if (count) {
+    if (includeValidatedShapes) {
+      usageError("--include-validated-shapes cannot be used with --count.", "wh thing query --declared-shape Player --count");
+    }
     if (cursor || all || limit || ctx.liveMode || role) {
       usageError("Usage: wh thing query --count [--shape SHAPE] [--about WREF] [--kind KIND] [--match PATTERN] [--since-repo-seq N]", "wh thing query --kind assertion --about Player/alice --count --since-repo-seq 42");
     }
     return handleCount(ctx, org, repo, {
       shape,
+      declaredShape,
       kind,
       match,
       about,
@@ -53766,6 +53949,8 @@ var handleQuery = async (ctx, { flags }) => {
   const pageLimit = all ? Math.min(limit ?? AUTO_PAGE_LIMIT, MAX_PAGE_LIMIT) : boundedLimit;
   const queryOpts = {
     shape,
+    declaredShape,
+    includeValidatedShapes,
     about,
     affirmedAbout,
     kind,
@@ -53806,6 +53991,8 @@ var handleQuery = async (ctx, { flags }) => {
   const streamJsonl = all && ctx.format === "jsonl";
   const result = all ? await fetchAllQueryPages(ctx, org, repo, {
     shape,
+    declaredShape,
+    includeValidatedShapes,
     about,
     affirmedAbout,
     kind,
@@ -53825,6 +54012,8 @@ var handleQuery = async (ctx, { flags }) => {
     return await ctx.flushOut?.() ?? true;
   } : undefined) : await ctx.client.thing.query(org, repo, {
     shape,
+    declaredShape,
+    includeValidatedShapes,
     about,
     affirmedAbout,
     kind,
@@ -53858,6 +54047,8 @@ async function fetchAllQueryPages(ctx, org, repo, opts, onPage) {
     initialCursor: opts.cursor,
     fetchPage: (cursor) => ctx.client.thing.query(org, repo, {
       shape: opts.shape,
+      declaredShape: opts.declaredShape,
+      includeValidatedShapes: opts.includeValidatedShapes,
       about: opts.about,
       affirmedAbout: opts.affirmedAbout,
       kind: opts.kind,
@@ -53891,6 +54082,12 @@ function renderQueryResults(out, c, result) {
     const kl = kindLabel(c, effectiveKind(item.kind ?? "thing", shapeName));
     const retractedTag = item.active === false ? `  ${c.red}[RETRACTED]${c.reset}` : "";
     out(`  ${wref}  ${kl}${retractedTag}`);
+    if (item.declaredShapes?.length) {
+      out(`    ${c.dim}declares:${c.reset} ${refList(c, item.declaredShapes, decorations)}`);
+    }
+    if (item.validatedShapes?.length) {
+      out(`    ${c.dim}validates:${c.reset} ${refList(c, item.validatedShapes, decorations)}`);
+    }
     if (item.roles?.length) {
       out(`    ${c.dim}roles:${c.reset} ${item.roles.join(", ")}`);
     }
@@ -53914,16 +54111,22 @@ var refsFlags = {
     description: "Show outbound refs (what this target references)"
   }),
   field: flag.string({ description: "Filter by field path (inbound only)" }),
+  binding: flag.string({
+    description: "Keep only edges with this binding: identity (follows the Thing) or versioned (pinned to one version)"
+  }),
   limit: flag.number({
     description: "Max items per page (default: 50, max: 500)"
   }),
   cursor: flag.string({ description: "Opaque pagination cursor" }),
   all: flag.boolean({ description: "Fetch all pages" })
 };
+function isRefsBinding(value) {
+  return value === "identity" || value === "versioned";
+}
 var handleRefs = async (ctx, { flags, args }) => {
   const wref = args[0];
   if (!wref) {
-    usageError("Usage: wh thing refs <wref> [--inbound|--outbound] [--field FIELD] [--limit N]", "wh thing refs Loc/player");
+    usageError("Usage: wh thing refs <wref> [--inbound|--outbound] [--field FIELD] [--binding identity|versioned] [--limit N]", "wh thing refs Loc/player");
   }
   const { org, repo } = looksLikeDurableId(wref) ? parseOrgRepoOptional(getRepoRef(ctx), ctx.config) : parseOrgRepo(getRepoRef(ctx), ctx.config);
   if (flags.inbound && flags.outbound) {
@@ -53933,10 +54136,14 @@ var handleRefs = async (ctx, { flags, args }) => {
   if (direction === "outbound" && flags.field) {
     usageError("--field is only supported for inbound refs", "wh thing refs Loc/player --field target");
   }
+  const binding = flags.binding;
+  if (binding !== undefined && !isRefsBinding(binding)) {
+    usageError("--binding must be identity or versioned", "wh thing refs Loc/player --binding identity");
+  }
   const limit = flags.limit;
   const cursor = flags.cursor;
   const all = flags.all;
-  const refsQueryIsNarrowed = Boolean(flags.field || cursor);
+  const refsQueryIsNarrowed = Boolean(flags.field || binding || cursor);
   if (cursor && !limit) {
     usageError("Usage: wh thing refs <wref> [--limit N] [--cursor TOKEN]", "wh thing refs Loc/player --limit 50 --cursor <token>");
   }
@@ -53945,6 +54152,7 @@ var handleRefs = async (ctx, { flags, args }) => {
   const fetchPage = async (c) => ctx.client.thing.refs(org, repo, wref, {
     direction,
     fieldPath: flags.field,
+    binding,
     limit: pageLimit,
     cursor: c
   });
@@ -57056,7 +57264,7 @@ var createFlags3 = {
 };
 
 // ../../packages/warmhub-cli/src/domains/commit-stream-output-contract-id.ts
-var COMMIT_SUBMIT_STREAM_ROW_SCHEMA_ID = "wh.commit.submit.stream.row/v0.2";
+var COMMIT_SUBMIT_STREAM_ROW_SCHEMA_ID = "wh.commit.submit.stream.row/v0.3";
 function identify(row) {
   if ("schema" in row) {
     throw new Error("Streaming submission row already defines a schema field");
@@ -61720,7 +61928,7 @@ var DOCTOR_DOMAIN = defineDomain({
 var createFlags5 = {
   key: flag.string({ description: "issuer-scoped idempotency key" }),
   coverage: flag.string({
-    description: "inline coverage JSON ({include, exclude?})"
+    description: "inline coverage JSON ({paths, shapes?, shapeless?}; the field axis exists in the grammar but is not servable yet)"
   }),
   view: flag.string({
     description: "View backing coverage instead (View/NAME or View/NAME@vN)"
@@ -61741,7 +61949,7 @@ function repo(ctx) {
   return parseOrgRepo(getRepoRef(ctx), ctx.config);
 }
 var CREATE_USAGE = "Usage: wh grant create <member EMAIL | pat NAME | component ORG/NAME> --key KEY --op OP [--op OP] (--coverage JSON | --view View/NAME[@vN])";
-var CREATE_EXAMPLE = `wh grant create component acme/indexer --key provision --op things:read --coverage '{"include":["Lesson/**"]}'`;
+var CREATE_EXAMPLE = `wh grant create component acme/indexer --key provision --op things:read --coverage '{"paths":{"include":["**"]},"shapes":["THING_DURABLE_ID"]}'`;
 function parseRecipient(kind, name) {
   switch (kind) {
     case "member":
@@ -61755,6 +61963,7 @@ function parseRecipient(kind, name) {
       };
     default:
       usageError("Grant recipient kind must be member, pat, or component.", CREATE_EXAMPLE);
+      throw new Error("usageError must throw");
   }
 }
 function isPatternList(value) {
@@ -61762,12 +61971,24 @@ function isPatternList(value) {
 }
 function parseCoverage(raw) {
   const candidate = parseJsonObject(raw, "--coverage");
-  if (!isPatternList(candidate.include) || candidate.include.length === 0) {
-    usageError("--coverage must be an object with a non-empty include array of patterns ({include, exclude?}).", CREATE_EXAMPLE);
+  const paths = candidate.paths !== null && typeof candidate.paths === "object" && !Array.isArray(candidate.paths) ? candidate.paths : candidate;
+  if (!isPatternList(paths.include) || paths.include.length === 0) {
+    usageError("--coverage must contain a non-empty paths.include array (terminal {paths, shapes?, shapeless?, fields?}); legacy {include, exclude?} is accepted for compatibility.", CREATE_EXAMPLE);
   }
-  if (candidate.exclude !== undefined && !isPatternList(candidate.exclude)) {
+  if (paths.exclude !== undefined && !isPatternList(paths.exclude)) {
     usageError("--coverage exclude must be an array of patterns when present.", CREATE_EXAMPLE);
   }
+  if ("paths" in candidate) {
+    if (candidate.shapes !== undefined && !isPatternList(candidate.shapes)) {
+      usageError("--coverage shapes must be an array of durable Shape ids.", CREATE_EXAMPLE);
+    }
+    if (candidate.fields !== undefined && !isPatternList(candidate.fields)) {
+      usageError("--coverage fields must be an array of field keys.", CREATE_EXAMPLE);
+    }
+    if (candidate.shapeless !== undefined && typeof candidate.shapeless !== "boolean") {
+      usageError("--coverage shapeless must be a boolean.", CREATE_EXAMPLE);
+    }
+  }
   return candidate;
 }
 var handleCreate4 = async (ctx, { args, flags }) => {
@@ -62715,7 +62936,7 @@ var ORG_DOMAIN = defineDomain({
 });
 
 // ../../packages/warmhub-cli/src/domains/prime-content.md
-var prime_content_default = "# WarmHub CLI Context\n> **Context Recovery**: Run `wh prime` after compaction or new session\n\n## Environment\n{{REPO_LINE}}\n\n## Core Concepts\n- **Thing**: A named entity versioned by writes. **Assertion**: A thing that makes a shape-validated claim about another thing.\n- **Shape**: A thing defining data structure; every other thing has one. **Write**: One or more add/revise/retract operations with per-operation results.\n- **wref**: A reference to a thing. Local: `Player` (the shape) or `Player/alice` (a thing with that shape). Cross-repo: `wh:org/repo/Shape` or `wh:org/repo/Shape/name`.\n\n## Versioned Wrefs\n- `Shape` addresses the shape itself; `Shape/name` addresses a thing with that shape. `@vN` pins either.\n- Floating write refs to retracted targets fail; existing pinned versions remain valid.\n- Rename invalidates old spellings, including `@vN`; the new name resolves history.\n- Untyped wrefs accept any thing. `wref<T>` requires the target's shape to be `T`; a shape has no shape, so never satisfies it. `wref?` coalesces only `thing_absent`, never a missing shape.\n\n## Key Workflows\n\n**Write data** (discover shapes → scaffold ops → submit):\n```bash\nwh shape list --repo org/repo                             # list available shapes\nwh shape view ShapeName --repo org/repo                   # inspect fields\nwh shape template ShapeName -o ops.json --repo org/repo   # scaffold write ops (supports --kind assertion)\n# edit ops.json — fill FILL_IN placeholders — then:\nwh commit submit --file ops.json --dry-run --repo org/repo  # preview; remove --dry-run to submit\n# or single assertion (no file needed):\nwh assertion create --shape ShapeName --about Target/name --name my-assertion --data '{\"field\":1}' --repo org/repo\n# Relay failed operation details when present. Never hand-guess ops JSON — use `wh shape template <Shape>`.\n```\n\n**Read data:**\n```bash\nwh thing list --repo org/repo                 # all things at HEAD\nwh thing view Shape/name --repo org/repo      # inspect a thing\nwh thing query --shape MyShape --repo org/repo  # find things by shape\nwh thing about Shape --repo org/repo          # assertions about a shape\nwh assertion list --repo org/repo             # all assertions at HEAD\nwh thing history Shape/name --repo org/repo   # version history\n\n# Batch read — wh thing view is variadic (max 500 wrefs/call):\nwh thing view Player/alice Player/bob               # variadic positionals\nwh thing view --file wrefs.txt --json               # one wref per line\ncat wrefs.txt | wh thing view --format jsonl        # one JSON line per *deduped* requested wref\n```\n\n## Wref Quick Reference\n\nWrites use explicit names and wrefs. Untyped fields, collection members,\nassertion `about`, and committers accept any thing. Create a deterministic\ntarget before referencing it in the same commit.\n\n## Command Reference\n\n**Global flags**: `--repo`, `--format`, `--json`, `--live`\n### thing — Things\n- `wh thing list [--shape] [--kind] [--match] [--include-retracted]` — Current HEAD state\n- `wh thing view [<wref>...] [--file <path>] [--version] [--depth] [--include-retracted] [--data-mode auto|full]` — Thing details. Variadic (max 500). `--version` implies `--include-retracted`. Batch JSON returns `{ requested, items, missing }`; jsonl emits one row per deduped requested wref. Large Set/List bodies summarize by default; use `--data-mode full` for canonical collection JSON.\n- `wh thing history [wref] [--shape] [--about] [--include-retracted]` — Version history\n- `wh thing resolve <wref>` — Resolve a wref to its canonical thing identity\n- `wh thing create <name|Shape/name> (--data|--file) [--shape]` — Create\n- `wh thing revise <name> [--data] [--message] [--committer] [--expected-version]` — Revise (CONFLICT if HEAD≠n)\n- `wh thing retract <wref> -m <message> [--reason] [--kind] [--expected-version]` — Retract\n- `wh thing query [--shape] [--kind] [--about] [--match]` — Query by filters\n- `wh thing search <query> [--shape] [--kind] [--about] [--mode]` — Search text\n- `wh thing rename <Shape/oldName> <newName>` — Rename\n- `wh thing refs <wref> [--inbound] [--outbound] [--field]` — Show field references; use `wh thing about` for assertions about the target thing\n- `wh thing about <wref> [--shape] [--match] [--depth] [--resolve-collections] [--role from|to|ends] [--limit] [--include-retracted]` — Show assertions about the target identity; `--resolve-collections` expands bare/@HEAD/@ALL members, `--role` filters direction; not pinned @vN\n\n- `wh view evaluate VIEW [--limit N] [--cursor TOK] [--all]`\n### commit — Write operations\n- `wh commit submit [--ops|--file|--add|--revise|--retract] [--dry-run] [--skip-existing]` — Submit operations, or evaluate the complete bounded input without durable changes under `--dry-run`. JSONL preview emits one operation row per input plus one summary.\n- `wh shape template <shape> [shape2 ...] [--kind] [--operation add|revise|retract] [-o file]` — Generate sample ops\n\n### assertion — Assertion operations\n- `wh assertion list [--about wref] [--shape] [--match] [--include-retracted]` — Browse assertions\n- `wh assertion view <wref> [--version] [--include-retracted]` — Assertion details\n- `wh assertion create --shape <s> --name <n> --about <wref> [--data] [-m] [--committer]` — Create assertion\n- `wh assertion revise <wref> --data <json> [--message] [--committer]` — Revise assertion\n- `wh assertion retract <wref> -m <message> [--reason] [--committer] [--expected-version]` — Retract assertion\n- `wh assertion history <wref> [--include-retracted]` — Assertion history\n\n### shape — Shape management\n- `wh shape list [--match] [--include-retracted]` — List all shapes\n- `wh shape view <name> [--include-retracted]` — Shape details\n- `wh shape revise <name> (--fields|--file)`\n- `wh shape create <name> (--fields|--file)`\n- `wh shape retract <name> -m <message> [--reason] [--expected-version]` — Retract shape\n- `wh shape history <name> [--include-retracted]` — Shape history\n- `wh shape rename <oldName> <newName>` — Rename shape\n\n### repo — Repository management\n- `wh repo create <org/name> [--display-name] [--description] [--visibility]` — Create repo\n- `wh repo list [org]` — List repos\n- `wh repo view [org/repo]` — Repo details\n\n### org — Organization management\n- `wh org create <name> [--display-name]` — Create a new organization\n- `wh org view <name>` — View organization details (alias: info)\n- `wh org list` — List all organizations\n\n### sub — Subscription management\n- `wh sub create <name> [flags]` — Create a subscription\n- `wh sub view <name>` — View subscription details\n- `wh sub list` — List all subscriptions\n- `wh sub log <name>` — Tail subscription delivery feed\n- `wh sub attempts <runId>` — Show attempt history for a run\n- `wh sub pause <name>` — Pause a subscription\n- `wh sub resume <name>` — Resume a paused subscription\n- `wh sub bind <name> [--credentials]` — Bind a credential set to a subscription for webhook auth\n- `wh sub unbind <name>` — Remove credential binding from a subscription\n- `wh sub delete <name>` — Retire; name reserved\n\n### notifications — Action notification listing\n- `wh notifications [--limit] [--since]` — List repo-scoped action notifications\n\n### credential — Credential set management\n- `wh credential create <name> [--repo org/repo | --org org] [--scope] [--description]` — Create an empty credential set\n- `wh credential list [--repo org/repo | --org org]` — List credential sets accessible from a repo or org\n- `wh credential view <name> [--repo org/repo | --org org]` — View a credential set (key names only, no values)\n- `wh credential delete <name> [--repo org/repo | --org org]` — Delete a credential set and its Vault object\n- `wh credential set <setName> [<keyName>] [--repo org/repo | --org org] [--value]` — Set credential key(s). With `<keyName>`: single-key form (reads value from `--value` or stdin). Without `<keyName>`: batch form (reads JSON object from stdin, e.g. `{\"KEY\":\"val\"}`)\n- `wh credential unset <setName> <keyName> [--repo org/repo | --org org]` — Remove a key from a credential set\n- `wh credential audit <setName> [--repo org/repo | --org org]` — View audit log for a credential set\n- `wh credential revoke <setName> [--repo org/repo | --org org] [--reason]` — Revoke a credential set (blocks new binds and stops bound webhook deliveries)\n\n### component — Component management\n- `wh component validate <path>` — Validate package\n- `wh component install <org/name>` — Install a registered component\n- `wh component register <name> --org <org> --manifest <path> [flags]` — Register component identity\n- `wh component unregister <org/name>` — Remove a registered component identity\n- `wh component registry list --org <org>` — List registered components\n- `wh component registry view <org/name>` — View a registered component\n- `wh component registry update <org/name> [flags]` — Update a registered component\n- `wh component list` — List installed components\n- `wh component update <org/name>` — Update installed component\n- `wh component view <org/name>` — Show component details (alias: show)\n- `wh component doctor <org/name>` — Run component health checks\n- `wh component teardown <org/name>` — Pause component subscriptions\n\n### Getting More Info\n- `wh help` — help overview\n- `wh <domain>` — domain verbs\n- `wh <domain> <verb> --help` — verb flags and examples\n- `wh help --format json` — `CliSpecV2` (`schemaVersion: 2`): global/contextual/root tables and command overrides\n\n## Common Workflows\n\n**Explore a repo:**\n```bash\nwh thing list --repo org/repo             # see all things in HEAD\nwh thing view Shape/name --repo org/repo  # inspect a specific thing\nwh thing history Shape/name --repo org/repo # inspect version history\nwh thing about Shape/name                 # assertions about thing/shape\n```\n\n**Create an assertion** (most common write):\n```bash\n# --about takes an untyped target wref: Shape or Shape/name.\nwh assertion create --shape MyShape --about TargetShape/target-name \\\n  --name my-assertion --data '{\"field_a\":1,\"field_b\":\"value\"}' --repo org/repo\n# Output includes per-operation status; relay failures when present.\n```\n\n**Create via write entrypoint** (alternative, supports batches and streams):\n```bash\nwh commit submit --add my-item --shape MyShape --kind assertion \\\n  --about TargetShape/target-name --data '{\"field_a\":1}' --repo org/repo\n```\n\n**Batch write via file** (generate template → edit → submit):\n```bash\nwh shape template Hypothesis Evidence -o ops.json    # add --kind assertion --about TargetShape/name for assertions\n# edit ops.json — fill FILL_IN placeholders\nwh commit submit --file ops.json -m \"batch update\"   # submit all operations (bare `wh commit` is equivalent)\n# --file format: docs.warmhub.ai/cli-reference/commit-operations\n```\n\n**Bulk write (JSONL stream, >1k ops)** — one chunked stream beats per-record commits (~60× faster):\n```bash\nwh shape template MyShape -o ops.jsonl                          # one op per line (.jsonl)\nID=\"bulk-$(date +%s)\"   # caller id for chunk correlation\nwh commit submit --file ops.jsonl --stream-id \"$ID\" --chunk-size 5000 \\\n  --skip-existing --progress -m \"bulk ingest\" --repo org/repo\n# --chunk-size: ops per append chunk (default 1000, max 10000); chunk≈1 is ~60× slower\n# --skip-existing: skips already-written add ops (drops per-row read-before-write)\n# --stream-id identifies the submission but provides no receipt or resume.\n# After an outcome-unknown append, stop writes and reconcile attempted + unsent\n# work from a later verified checkpoint; never blindly replay revise/retract.\n```\n\n**Create collections:**\n```bash\nwh commit submit --type arc --name route --members Location/a,Location/b --repo org/repo\nwh assertion create --shape Supports --name route-support --about Arc/route --data '{\"confidence\":0.8}' --repo org/repo\n```\n\n**Modify data:**\n```bash\nwh thing revise Shape/name --data '{\"x\":5,\"y\":3}' -m \"update\" --repo org/repo\nwh thing retract Shape/old-item -m \"withdrawn\" --reason \"data feed contaminated\" --repo org/repo\n```\n\n**Query and filter:**\n```bash\nwh thing query --shape MyShape                       # by shape\nwh thing query --kind assertion --about Shape/name   # by kind + target\nwh thing history Shape/name --limit 10               # version history\n```\n\n## Built-in Content shape\n\nWarmHub repos expose three well-known content wrefs:\n- `Content/Readme`  — stored markdown for humans\n- `Content/Agents`  — stored markdown guidance for AI agents\n- `Content/LlmsTxt` — synthesized per-request sitemap (read-only)\n\nFetch via `wh repo content get --kind readme|agents|llms-txt`,\n`client.repo.getReadme/getAgents/getLlmsTxt`, MCP `warmhub_repo_content_get`,\nor raw HTTP `GET /{org}/{repo}/readme.md|agents.md|llms.txt`.\nSee `wh repo describe` → `additionalInformation` for the discovery field.\n\n## Query Discipline\n- Plan the repo, shapes, and wrefs you need before the first query.\n- Gather the needed facts from one repo before switching to another.\n- Do the queries first, then write one complete answer.\n\n## Agent Tips\n- **Always run commands for live data** — this context describes the CLI, not repo contents\n- **Before writing, discover wrefs** — run `wh thing list` or `wh shape list`\n- **Shape field types**: `string`, `number`, `boolean`, `wref`, arrays, optionals, nested objects\n- **Write commands return per-operation results** — relay failures and affected wrefs to the user\n- **Pass data inline** with `--data '{...}'` — do NOT create temp files\n- Add `--json` to any command for machine-readable JSON output\n- **Aliases teach canonical commands** — executing aliases emit a status hint; misleading lifecycle aliases reject and point to `retract`\n- Writes go through `wh commit submit` (or bare `wh commit`) or wrappers (`create`, `revise`, `retract`, `assertion create`). `retract` irreversibly withdraws an identity and creates a history entry.\n- Use `wh doctor` to check environment health\n";
+var prime_content_default = "# WarmHub CLI Context\n> **Context Recovery**: Run `wh prime` after compaction or new session\n\n## Environment\n{{REPO_LINE}}\n\n## Core Concepts\n- **Thing**: A named entity versioned by writes. **Assertion**: A thing that makes a shape-validated claim about another thing.\n- **Shape**: A thing defining data structure; every other thing has one. **Write**: One or more add/revise/retract operations with per-operation results.\n- **wref**: A reference to a thing. Local: `Player` (the shape) or `Player/alice` (a thing with that shape). Cross-repo: `wh:org/repo/Shape` or `wh:org/repo/Shape/name`.\n\n## Versioned Wrefs\n- `Shape` addresses the shape itself; `Shape/name` addresses a thing with that shape. `@vN` pins either.\n- Floating write refs to retracted targets fail; existing pinned versions remain valid.\n- Rename invalidates old spellings, including `@vN`; the new name resolves history.\n- Untyped wrefs accept any thing. `wref<T>` requires the target's shape to be `T`; a shape has no shape, so never satisfies it. `wref?` coalesces only `thing_absent`, never a missing shape.\n- Wref `binding`: `identity` follows the Thing, `versioned` pins.\n\n## Key Workflows\n\n**Write data** (discover shapes → scaffold ops → submit):\n```bash\nwh shape list --repo org/repo                             # list available shapes\nwh shape view ShapeName --repo org/repo                   # inspect fields\nwh shape template ShapeName -o ops.json --repo org/repo   # scaffold write ops (supports --kind assertion)\n# edit ops.json — fill FILL_IN placeholders — then:\nwh commit submit --file ops.json --dry-run --repo org/repo  # preview; remove --dry-run to submit\n# or single assertion (no file needed):\nwh assertion create --shape ShapeName --about Target/name --name my-assertion --data '{\"field\":1}' --repo org/repo\n# Relay failed operation details when present. Never hand-guess ops JSON — use `wh shape template <Shape>`.\n```\n\n**Read data:**\n```bash\nwh thing list --repo org/repo                 # all things at HEAD\nwh thing view Shape/name --repo org/repo      # inspect a thing\nwh thing query --shape MyShape --repo org/repo  # find things by shape\nwh thing about Shape --repo org/repo          # assertions about a shape\nwh assertion list --repo org/repo             # all assertions at HEAD\nwh thing history Shape/name --repo org/repo   # version history\n\n# Batch read — wh thing view is variadic (max 500 wrefs/call):\nwh thing view Player/alice Player/bob               # variadic positionals\nwh thing view --file wrefs.txt --json               # one wref per line\ncat wrefs.txt | wh thing view --format jsonl        # one JSON line per *deduped* requested wref\n```\n\n## Wref Quick Reference\n\nWrites use explicit names and wrefs. Untyped fields, collection members,\nassertion `about`, and committers accept any thing. Create a deterministic\ntarget before referencing it in the same commit.\n\n## Command Reference\n\n**Global flags**: `--repo`, `--format`, `--json`, `--live`\n### thing — Things\n- `wh thing list [--shape] [--kind] [--match] [--include-retracted]` — Current HEAD state\n- `wh thing view [<wref>...] [--file <path>] [--version] [--depth] [--include-retracted] [--data-mode auto|full]` — Thing details. Variadic (max 500). `--version` implies `--include-retracted`. Batch JSON returns `{ requested, items, missing }`; jsonl emits one row per deduped requested wref. Large Set/List bodies summarize by default; use `--data-mode full` for canonical collection JSON.\n- `wh thing history [wref] [--shape] [--about] [--include-retracted]` — Version history\n- `wh thing resolve <wref>` — Resolve a wref to its canonical thing identity\n- `wh thing create <name|Shape/name> (--data|--file) [--shape]` — Create\n- `wh thing revise <name> [--data] [--message] [--committer] [--expected-version]` — Revise (CONFLICT if HEAD≠n)\n- `wh thing retract <wref> -m <message> [--reason] [--kind] [--expected-version]` — Retract\n- `wh thing query [--shape] [--kind] [--about] [--match]` — Query by filters\n- `wh thing search <query> [--shape] [--kind] [--about] [--mode]` — Search text\n- `wh thing rename <Shape/oldName> <newName>` — Rename\n- `wh thing refs <wref> [--inbound] [--outbound] [--field]` — Show field references; use `wh thing about` for assertions about the target thing\n- `wh thing about <wref> [--shape] [--match] [--depth] [--resolve-collections] [--role from|to|ends] [--limit] [--include-retracted]` — Show assertions about the target identity; `--resolve-collections` expands bare/@HEAD/@ALL members, `--role` filters direction; not pinned @vN\n\n- `wh view evaluate VIEW [--limit N] [--cursor TOK] [--all]`\n### commit — Write operations\n- `wh commit submit [--ops|--file|--add|--revise|--retract] [--dry-run] [--skip-existing]` — Submit operations, or evaluate the complete bounded input without durable changes under `--dry-run`. JSONL preview emits one operation row per input plus one summary.\n- `wh shape template <shape> [shape2 ...] [--kind] [--operation add|revise|retract] [-o file]` — Generate sample ops\n\n### assertion — Assertion operations\n- `wh assertion list [--about wref] [--shape] [--match] [--include-retracted]` — Browse assertions\n- `wh assertion view <wref> [--version] [--include-retracted]` — Assertion details\n- `wh assertion create --shape <s> --name <n> --about <wref> [--data] [-m] [--committer]` — Create assertion\n- `wh assertion revise <wref> --data <json> [--message] [--committer]` — Revise assertion\n- `wh assertion retract <wref> -m <message> [--reason] [--committer] [--expected-version]` — Retract assertion\n- `wh assertion history <wref> [--include-retracted]` — Assertion history\n\n### shape — Shape management\n- `wh shape list [--match] [--include-retracted]` — List all shapes\n- `wh shape view <name> [--include-retracted]` — Shape details\n- `wh shape revise <name> (--fields|--file)`\n- `wh shape create <name> (--fields|--file)`\n- `wh shape retract <name> -m <message> [--reason] [--expected-version]` — Retract shape\n- `wh shape history <name> [--include-retracted]` — Shape history\n- `wh shape rename <oldName> <newName>` — Rename shape\n\n### repo — Repository management\n- `wh repo create <org/name> [--display-name] [--description] [--visibility]` — Create repo\n- `wh repo list [org]` — List repos\n- `wh repo view [org/repo]` — Repo details\n\n### org — Organization management\n- `wh org create <name> [--display-name]` — Create a new organization\n- `wh org view <name>` — View organization details (alias: info)\n- `wh org list` — List all organizations\n\n### sub — Subscription management\n- `wh sub create <name> [flags]` — Create a subscription\n- `wh sub view <name>` — View subscription details\n- `wh sub list` — List all subscriptions\n- `wh sub log <name>` — Tail subscription delivery feed\n- `wh sub attempts <runId>` — Show attempt history for a run\n- `wh sub pause <name>` — Pause a subscription\n- `wh sub resume <name>` — Resume a paused subscription\n- `wh sub bind <name> [--credentials]` — Bind a credential set to a subscription for webhook auth\n- `wh sub unbind <name>` — Remove credential binding from a subscription\n- `wh sub delete <name>` — Retire; name reserved\n\n### notifications — Action notification listing\n- `wh notifications [--limit] [--since]` — List repo-scoped action notifications\n\n### credential — Credential set management\n- `wh credential create <name> [--repo org/repo | --org org] [--scope] [--description]` — Create an empty credential set\n- `wh credential list [--repo org/repo | --org org]` — List credential sets accessible from a repo or org\n- `wh credential view <name> [--repo org/repo | --org org]` — View a credential set (key names only, no values)\n- `wh credential delete <name> [--repo org/repo | --org org]` — Delete a credential set and its Vault object\n- `wh credential set <setName> [<keyName>] [--repo org/repo | --org org] [--value]` — Set credential key(s). With `<keyName>`: single-key form (reads value from `--value` or stdin). Without `<keyName>`: batch form (reads JSON object from stdin, e.g. `{\"KEY\":\"val\"}`)\n- `wh credential unset <setName> <keyName> [--repo org/repo | --org org]` — Remove a key from a credential set\n- `wh credential audit <setName> [--repo org/repo | --org org]` — View audit log for a credential set\n- `wh credential revoke <setName> [--repo org/repo | --org org] [--reason]` — Revoke a credential set (blocks new binds and stops bound webhook deliveries)\n\n### component — Component management\n- `wh component validate <path>` — Validate package\n- `wh component install <org/name>` — Install a registered component\n- `wh component register <name> --org <org> --manifest <path> [flags]` — Register component identity\n- `wh component unregister <org/name>` — Remove a registered component identity\n- `wh component registry list --org <org>` — List registered components\n- `wh component registry view <org/name>` — View a registered component\n- `wh component registry update <org/name> [flags]` — Update a registered component\n- `wh component list` — List installed components\n- `wh component update <org/name>` — Update installed component\n- `wh component view <org/name>` — Show component details (alias: show)\n- `wh component doctor <org/name>` — Run component health checks\n- `wh component teardown <org/name>` — Pause component subscriptions\n\n### Getting More Info\n- `wh help` — help overview\n- `wh <domain>` — domain verbs\n- `wh <domain> <verb> --help` — verb flags and examples\n- `wh help --format json` — `CliSpecV2` (`schemaVersion: 2`): global/contextual/root tables and command overrides\n\n## Common Workflows\n\n**Explore a repo:**\n```bash\nwh thing list --repo org/repo             # see all things in HEAD\nwh thing view Shape/name --repo org/repo  # inspect a specific thing\nwh thing history Shape/name --repo org/repo # inspect version history\nwh thing about Shape/name                 # assertions about thing/shape\n```\n\n**Create an assertion** (most common write):\n```bash\n# --about takes an untyped target wref: Shape or Shape/name.\nwh assertion create --shape MyShape --about TargetShape/target-name \\\n  --name my-assertion --data '{\"field_a\":1,\"field_b\":\"value\"}' --repo org/repo\n# Output includes per-operation status; relay failures when present.\n```\n\n**Create via write entrypoint** (alternative, supports batches and streams):\n```bash\nwh commit submit --add my-item --shape MyShape --kind assertion \\\n  --about TargetShape/target-name --data '{\"field_a\":1}' --repo org/repo\n```\n\n**Batch write via file** (generate template → edit → submit):\n```bash\nwh shape template Hypothesis Evidence -o ops.json    # add --kind assertion --about TargetShape/name for assertions\n# edit ops.json — fill FILL_IN placeholders\nwh commit submit --file ops.json -m \"batch update\"   # submit all operations (bare `wh commit` is equivalent)\n# --file format: docs.warmhub.ai/cli-reference/commit-operations\n```\n\n**Bulk write (JSONL stream, >1k ops)** — one chunked stream beats per-record commits (~60× faster):\n```bash\nwh shape template MyShape -o ops.jsonl                          # one op per line (.jsonl)\nID=\"bulk-$(date +%s)\"   # caller id for chunk correlation\nwh commit submit --file ops.jsonl --stream-id \"$ID\" --chunk-size 5000 \\\n  --skip-existing --progress -m \"bulk ingest\" --repo org/repo\n# --chunk-size: ops per append chunk (default 1000, max 10000); chunk≈1 is ~60× slower\n# --skip-existing: skips already-written add ops (drops per-row read-before-write)\n# --stream-id identifies the submission but provides no receipt or resume.\n# After an outcome-unknown append, stop writes and reconcile attempted + unsent\n# work from a later verified checkpoint; never blindly replay revise/retract.\n```\n\n**Create collections:**\n```bash\nwh commit submit --type arc --name route --members Location/a,Location/b --repo org/repo\nwh assertion create --shape Supports --name route-support --about Arc/route --data '{\"confidence\":0.8}' --repo org/repo\n```\n\n**Modify data:**\n```bash\nwh thing revise Shape/name --data '{\"x\":5,\"y\":3}' -m \"update\" --repo org/repo\nwh thing retract Shape/old-item -m \"withdrawn\" --reason \"data feed contaminated\" --repo org/repo\n```\n\n**Query and filter:**\n```bash\nwh thing query --shape MyShape                       # by shape\nwh thing query --kind assertion --about Shape/name   # by kind + target\nwh thing history Shape/name --limit 10               # version history\n```\n\n## Built-in Content shape\n\nWarmHub repos expose three well-known content wrefs:\n- `Content/Readme`  — stored markdown for humans\n- `Content/Agents`  — stored markdown guidance for AI agents\n- `Content/LlmsTxt` — synthesized per-request sitemap (read-only)\n\nFetch via `wh repo content get --kind readme|agents|llms-txt`,\n`client.repo.getReadme/getAgents/getLlmsTxt`, MCP `warmhub_repo_content_get`,\nor raw HTTP `GET /{org}/{repo}/readme.md|agents.md|llms.txt`.\nSee `wh repo describe` → `additionalInformation` for the discovery field.\n\n## Query Discipline\n- Plan the repo, shapes, and wrefs you need before the first query.\n- Gather the needed facts from one repo before switching to another.\n- Do the queries first, then write one complete answer.\n\n## Agent Tips\n- **Always run commands for live data** — this context describes the CLI, not repo contents\n- **Before writing, discover wrefs** — run `wh thing list` or `wh shape list`\n- **Shape field types**: `string`, `number`, `boolean`, `wref`, arrays, optionals, nested objects\n- **Write commands return per-operation results** — relay failures and affected wrefs to the user\n- **Pass data inline** with `--data '{...}'` — do NOT create temp files\n- Add `--json` to any command for machine-readable JSON output\n- **Aliases teach canonical commands** — executing aliases emit a status hint; misleading lifecycle aliases reject and point to `retract`\n- Writes go through `wh commit submit` (or bare `wh commit`) or wrappers (`create`, `revise`, `retract`, `assertion create`). `retract` irreversibly withdraws an identity and creates a history entry.\n- Use `wh doctor` to check environment health\n";
 
 // ../../packages/warmhub-cli/src/domains/prime.ts
 function buildMarkdown(config2) {
@@ -63101,6 +63322,8 @@ class StreamingByteReader {
         return;
     }
     const head = this.#queue[0];
+    if (!head)
+      return;
     const available = head.byteLength - this.#queueOffset;
     const length = Math.min(limit, available);
     const result = head.subarray(this.#queueOffset, this.#queueOffset + length);
@@ -63116,7 +63339,10 @@ class StreamingByteReader {
     if (bytes.byteLength === 0)
       return;
     if (this.#queueOffset > 0) {
-      const current = this.#queue[0].subarray(this.#queueOffset);
+      const head = this.#queue[0];
+      if (!head)
+        throw new Error("archive reader queue is inconsistent");
+      const current = head.subarray(this.#queueOffset);
       this.#queue[0] = current;
       this.#queueOffset = 0;
     }
@@ -64833,6 +65059,70 @@ var VERIFY_VERB = {
   handler: handleVerify2
 };
 
+// ../../packages/warmhub-cli/src/domains/repo/index-pin.ts
+var PIN_USAGE = "Usage: wh repo index pin <Shape> <field.path> [org/repo]";
+var PIN_EXAMPLE = "wh repo index pin Person address.city acme/world";
+var UNPIN_USAGE = "Usage: wh repo index unpin <Shape> <field.path> [org/repo]";
+var UNPIN_EXAMPLE = "wh repo index unpin Person address.city acme/world";
+function parseIndexArgs(args, usage, example) {
+  const [shape, fieldPath, repoRef] = args;
+  if (!shape || !fieldPath) {
+    usageError(usage, example);
+  }
+  return { shape, fieldPath, repoRef };
+}
+function renderPinResult(ctx, verb, result) {
+  const c = ctx.colors;
+  ctx.out(`${c.green}${verb}${c.reset} ${c.cyan}${escapeTerminalTextForDisplay(result.fieldPath)}${c.reset} via ${escapeTerminalTextForDisplay(result.declaredByShape)}`);
+  if (result.carryingShapes.length === 0) {
+    ctx.out(`  ${c.dim}no shape in this repo carries the path${c.reset}`);
+    return;
+  }
+  const maxShape = result.carryingShapes.reduce((m, s) => Math.max(m, s.shape.length), 0);
+  for (const carrying of result.carryingShapes) {
+    ctx.out(`  ${c.cyan}${escapeTerminalTextForDisplay(carrying.shape.padEnd(maxShape))}${c.reset}  ${escapeTerminalTextForDisplay(carrying.markerState)}`);
+  }
+}
+var handlePin = async (ctx, { args }) => {
+  const { shape, fieldPath, repoRef } = parseIndexArgs(args, PIN_USAGE, PIN_EXAMPLE);
+  const { org, repo: repo2 } = parseOrgRepo(getRepoRef(ctx) ?? repoRef, ctx.config);
+  const result = await ctx.client.repo.index.pin(org, repo2, shape, fieldPath);
+  writeOutput(ctx, result, () => renderPinResult(ctx, "Declared", result));
+};
+var handleUnpin = async (ctx, { args }) => {
+  const { shape, fieldPath, repoRef } = parseIndexArgs(args, UNPIN_USAGE, UNPIN_EXAMPLE);
+  const { org, repo: repo2 } = parseOrgRepo(getRepoRef(ctx) ?? repoRef, ctx.config);
+  const result = await ctx.client.repo.index.unpin(org, repo2, shape, fieldPath);
+  writeOutput(ctx, result, () => renderPinResult(ctx, "Withdrew", result));
+};
+var INDEX_SUBDOMAIN = defineDomain({
+  name: "index",
+  summary: "Declare which field paths the typed field index carries",
+  verbs: {
+    pin: {
+      summary: "Declare a field path for indexing",
+      args: "<Shape> <field.path> [org/repo]",
+      notes: [
+        "The declaration is repository-wide: every shape carrying the path is backfilled, not just the one named here.",
+        "The path is resolved through the shape’s effective contract, so a composite may name a property one of its composed shapes owns.",
+        "Read `wh repo describe --indexed-fields` for readiness."
+      ],
+      examples: [PIN_EXAMPLE, "wh repo index pin Person address.city"],
+      handler: handlePin
+    },
+    unpin: {
+      summary: "Withdraw a field path from indexing",
+      args: "<Shape> <field.path> [org/repo]",
+      notes: [
+        "Refuses while a stored View definition references the path, naming the Views.",
+        "Rows are evicted asynchronously; predicates on the path fail immediately."
+      ],
+      examples: [UNPIN_EXAMPLE, "wh repo index unpin Person address.city"],
+      handler: handleUnpin
+    }
+  }
+});
+
 // ../../packages/warmhub-cli/src/domains/repo/lifecycle.ts
 var confirmFlags2 = {
   yes: flag.boolean({ short: "y", description: "Skip confirmation prompt" })
@@ -64950,6 +65240,100 @@ var handleList6 = async (ctx, { flags, args }) => {
   });
 };
 
+// ../../packages/warmhub-cli/src/domains/repo/indexed-fields-view.ts
+function stripShapeThingId(bucket) {
+  return bucket.map(({ shapeThingId: _omit, ...rest }) => rest);
+}
+function toPublicIndexedFields(report) {
+  return {
+    building: stripShapeThingId(report.building),
+    ready: stripShapeThingId(report.ready),
+    failed: stripShapeThingId(report.failed),
+    other: stripShapeThingId(report.other),
+    declarations: report.declarations,
+    consistency: report.consistency
+  };
+}
+function stateColor(c, state) {
+  switch (state) {
+    case "ready":
+      return c.green;
+    case "building":
+      return c.yellow;
+    case "failed":
+      return c.red;
+    default:
+      return c.dim;
+  }
+}
+function renderDeclarations(out, c, view) {
+  const { declarations, consistency } = view;
+  if (declarations.length === 0) {
+    out(`${c.bold}Declared Fields${c.reset}  ${c.dim}none${c.reset}`);
+    out(`  ${c.dim}Declare one with \`wh repo index pin <Shape> <path>\`${c.reset}`);
+  } else {
+    out(`${c.bold}Declared Fields${c.reset} (${declarations.length})`);
+    out("");
+    const maxPath = declarations.reduce((m, d) => Math.max(m, d.fieldPath.length), 0);
+    for (const declaration of declarations) {
+      const pathLabel = escapeTerminalTextForDisplay(declaration.fieldPath.padEnd(maxPath));
+      const readiness = declaration.ready ? "ready" : "not ready";
+      const rc = declaration.ready ? c.green : c.yellow;
+      const carriedBy = declaration.carrying.length > 0 ? declaration.carrying.map((m) => `${m.shapeName} (${m.state})`).join(", ") : "no carrying shape";
+      out(`  ${c.cyan}${pathLabel}${c.reset}  ${rc}${readiness}${c.reset}  ${c.dim}${escapeTerminalTextForDisplay(carriedBy)}${c.reset}`);
+      if (declaration.declaredByShape) {
+        out(`    ${c.dim}pinned via ${escapeTerminalTextForDisplay(declaration.declaredByShape)}${c.reset}`);
+      }
+    }
+  }
+  out("");
+  if (!consistency.consistent) {
+    out(`${c.bold}${c.red}Index consistency${c.reset}`);
+    for (const marker of consistency.undeclaredMarkers) {
+      out(`  ${c.red}undeclared${c.reset}  ${c.cyan}${escapeTerminalTextForDisplay(marker.shapeName)}${c.reset}  ${escapeTerminalTextForDisplay(marker.fieldPath)}`);
+    }
+    out("");
+  }
+}
+function renderMarkers(out, c, view) {
+  const allEntries = [
+    ...view.building,
+    ...view.ready,
+    ...view.failed,
+    ...view.other
+  ];
+  if (allEntries.length === 0) {
+    out(`${c.bold}Indexed Fields${c.reset}  ${c.dim}none${c.reset}`);
+    return;
+  }
+  out(`${c.bold}Indexed Fields${c.reset} (${allEntries.length})`);
+  out("");
+  const maxShape = allEntries.reduce((m, e) => Math.max(m, e.shapeName.length), 0);
+  const maxField = allEntries.reduce((m, e) => Math.max(m, e.fieldPath.length), 0);
+  const maxState = allEntries.reduce((m, e) => Math.max(m, e.state.length), 0);
+  for (const entry of allEntries) {
+    const shapeLabel = escapeTerminalTextForDisplay(entry.shapeName.padEnd(maxShape));
+    const fieldLabel = escapeTerminalTextForDisplay(entry.fieldPath.padEnd(maxField));
+    const stateLabel = escapeTerminalTextForDisplay(entry.state.padEnd(maxState));
+    const sc = stateColor(c, entry.state);
+    let line = `  ${c.cyan}${shapeLabel}${c.reset}  ${c.dim}${fieldLabel}${c.reset}  ${sc}${stateLabel}${c.reset}`;
+    if (entry.state === "building" && entry.backfillTotal != null && entry.backfillTotal > 0) {
+      const pct = Math.round(entry.backfillDone / entry.backfillTotal * 100);
+      line += `  ${c.dim}${entry.backfillDone}/${entry.backfillTotal} (${pct}%)${c.reset}`;
+    } else if (entry.state === "building") {
+      line += `  ${c.dim}${entry.backfillDone} rows${c.reset}`;
+    } else if (entry.state === "failed" && entry.failureReason) {
+      line += `  ${c.dim}${escapeTerminalTextForDisplay(entry.failureReason)}${c.reset}`;
+    }
+    out(line);
+  }
+  out("");
+}
+function renderIndexedFields(out, c, view) {
+  renderDeclarations(out, c, view);
+  renderMarkers(out, c, view);
+}
+
 // ../../packages/warmhub-cli/src/domains/repo/manage.ts
 var repoRenameFlags = {
   "display-name": flag.string({
@@ -65044,15 +65428,7 @@ var handleDescribe = async (ctx, { args, flags }) => {
     ...nameStrings(shapes).map((name) => [name, 0]),
     ...Object.entries(stats.byShape)
   ]);
-  function stripShapeThingId(bucket) {
-    return bucket.map(({ shapeThingId: _omit, ...rest }) => rest);
-  }
-  const indexedFieldsPublic = indexedFields ? {
-    building: stripShapeThingId(indexedFields.building),
-    ready: stripShapeThingId(indexedFields.ready),
-    failed: stripShapeThingId(indexedFields.failed),
-    other: stripShapeThingId(indexedFields.other)
-  } : null;
+  const indexedFieldsPublic = indexedFields ? toPublicIndexedFields(indexedFields) : null;
   const payload = {
     org,
     repo: repo2,
@@ -65128,50 +65504,7 @@ var handleDescribe = async (ctx, { args, flags }) => {
       ctx.out("");
     }
     if (indexedFieldsPublic) {
-      const allEntries = [
-        ...indexedFieldsPublic.building,
-        ...indexedFieldsPublic.ready,
-        ...indexedFieldsPublic.failed,
-        ...indexedFieldsPublic.other
-      ];
-      if (allEntries.length === 0) {
-        ctx.out(`${c.bold}Indexed Fields${c.reset}  ${c.dim}none${c.reset}`);
-      } else {
-        ctx.out(`${c.bold}Indexed Fields${c.reset} (${allEntries.length})`);
-        ctx.out("");
-        const stateColor = (state) => {
-          switch (state) {
-            case "ready":
-              return c.green;
-            case "building":
-              return c.yellow;
-            case "failed":
-              return c.red;
-            default:
-              return c.dim;
-          }
-        };
-        const maxShape = allEntries.reduce((m, e) => Math.max(m, e.shapeName.length), 0);
-        const maxField = allEntries.reduce((m, e) => Math.max(m, e.fieldPath.length), 0);
-        const maxState = allEntries.reduce((m, e) => Math.max(m, e.state.length), 0);
-        for (const entry of allEntries) {
-          const shapeLabel = escapeTerminalTextForDisplay(entry.shapeName.padEnd(maxShape));
-          const fieldLabel = escapeTerminalTextForDisplay(entry.fieldPath.padEnd(maxField));
-          const stateLabel = escapeTerminalTextForDisplay(entry.state.padEnd(maxState));
-          const sc = stateColor(entry.state);
-          let line = `  ${c.cyan}${shapeLabel}${c.reset}  ${c.dim}${fieldLabel}${c.reset}  ${sc}${stateLabel}${c.reset}`;
-          if (entry.state === "building" && entry.backfillTotal != null && entry.backfillTotal > 0) {
-            const pct = Math.round(entry.backfillDone / entry.backfillTotal * 100);
-            line += `  ${c.dim}${entry.backfillDone}/${entry.backfillTotal} (${pct}%)${c.reset}`;
-          } else if (entry.state === "building") {
-            line += `  ${c.dim}${entry.backfillDone} rows${c.reset}`;
-          } else if (entry.state === "failed" && entry.failureReason) {
-            line += `  ${c.dim}${escapeTerminalTextForDisplay(entry.failureReason)}${c.reset}`;
-          }
-          ctx.out(line);
-        }
-        ctx.out("");
-      }
+      renderIndexedFields(ctx.out, c, indexedFieldsPublic);
     }
   });
 };
@@ -65369,7 +65702,8 @@ var REPO_DOMAIN = defineDomain({
   },
   subdomains: {
     checkpoint: CHECKPOINT_SUBDOMAIN,
-    content: CONTENT_SUBDOMAIN
+    content: CONTENT_SUBDOMAIN,
+    index: INDEX_SUBDOMAIN
   }
 });
 
@@ -65386,13 +65720,13 @@ var FIELD_CONSTRAINTS_NOTES = [
   "Per-type constraint keys (enforced at commit time):",
   `  string:  ${keyList(STRING_CONSTRAINT_KEYS)}`,
   `  number:  ${keyList(NUMBER_CONSTRAINT_KEYS)}`,
-  `  wref:    ${keyList(WREF_CONSTRAINT_KEYS)} (target shape name; e.g. "shape": "Player")`,
+  `  wref:    ${keyList(WREF_CONSTRAINT_KEYS)} (shape target; binding: ${WREF_BINDING_MODES.join("|")})`,
   `  array:   ${keyList(ARRAY_CONSTRAINT_KEYS)} (items is the element type spec)`,
   "  boolean: (none)",
   "",
   "See docs.warmhub.ai/data-modeling/shapes#field-constraints for full semantics."
 ];
-var FIELDS_FLAG_DESCRIPTION = "Fields JSON; see Notes for per-type constraint keys (enum, pattern, bounds, shape, items)";
+var FIELDS_FLAG_DESCRIPTION = "Fields JSON; see Notes for per-type constraint keys (enum, pattern, bounds, shape, binding, items)";
 
 // ../../packages/warmhub-cli/src/domains/shape/history.ts
 var historyFlags3 = {
@@ -65597,11 +65931,43 @@ var handleView7 = async (ctx, { flags, args }) => {
   });
 };
 
+// ../../packages/warmhub-cli/src/composite-shapes.ts
+var pendingByContext = new WeakMap;
+async function capabilitiesFor(ctx) {
+  if (ctx.capabilities)
+    return ctx.capabilities;
+  let pending = pendingByContext.get(ctx);
+  if (!pending) {
+    pending = (async () => {
+      try {
+        return await ctx.client.diagnostics.capabilities();
+      } catch {
+        return;
+      }
+    })();
+    pendingByContext.set(ctx, pending);
+  }
+  const capabilities = await pending;
+  if (capabilities)
+    ctx.capabilities = capabilities;
+  return capabilities;
+}
+async function assertCompositeShapesEnabled(ctx, option) {
+  const capabilities = await capabilitiesFor(ctx);
+  if (capabilities?.features?.compositeShapes !== false)
+    return;
+  throw new CliError(2 /* UserInput */, "USER_INPUT", `composite Shapes are not enabled on this backend; ${option} is unavailable`, undefined, "Create the Shape without --compose, or ask an operator to enable WARMHUB_COMPOSITE_SHAPES_WRITE. Removing an existing composition with --clear-composition still works.");
+}
+
 // ../../packages/warmhub-cli/src/domains/shape/write.ts
 var fieldsFileFlag = flag.string({
   description: "read fields from a JSON object file (portable alternative to inline --fields)"
 });
 var createFlags8 = {
+  compose: flag.string({
+    description: "Shape HEAD to include (repeat for multiple members)",
+    multiple: true
+  }),
   "event-request-id": operationEventRequestIdFlag,
   fields: flag.string({ description: FIELDS_FLAG_DESCRIPTION }),
   file: fieldsFileFlag,
@@ -65610,6 +65976,13 @@ var createFlags8 = {
   })
 };
 var reviseFlags3 = {
+  "clear-composition": flag.boolean({
+    description: "remove every composed Shape"
+  }),
+  compose: flag.string({
+    description: "replace composed Shape HEADs (repeat for multiple members)",
+    multiple: true
+  }),
   "event-request-id": operationEventRequestIdFlag,
   fields: flag.string({ description: FIELDS_FLAG_DESCRIPTION }),
   file: fieldsFileFlag,
@@ -65702,6 +66075,10 @@ var handleCreate7 = async (ctx, { flags, args }) => {
   const opts = { eventRequestId };
   if (flags.description !== undefined)
     opts.description = flags.description;
+  if (flags.compose !== undefined) {
+    await assertCompositeShapesEnabled(ctx, "--compose");
+    opts.composes = flags.compose;
+  }
   const response = await ctx.client.shape.create(org, repo2, shapeName, fields, opts);
   const result = shapeChangeFromReceipt(response.receipt);
   writeOutput(ctx, response, () => {
@@ -65724,6 +66101,9 @@ var handleRevise3 = async (ctx, { flags, args }) => {
     missingMessage: "Usage: wh shape revise <name> (--fields '<json>' | --file <path>)",
     example: "wh shape revise Location --file fields.json"
   });
+  if (flags.compose !== undefined && flags["clear-composition"]) {
+    usageError("--compose and --clear-composition cannot be used together", "wh shape revise Location --fields '{}' --clear-composition");
+  }
   const { org, repo: repo2 } = parseOrgRepo(getRepoRef(ctx), ctx.config);
   const c = ctx.colors;
   const previousShape = flags["show-diff"] ? await ctx.client.shape.get(org, repo2, shapeName) : undefined;
@@ -65734,6 +66114,12 @@ var handleRevise3 = async (ctx, { flags, args }) => {
   const opts = { eventRequestId };
   if (flags.description !== undefined)
     opts.description = flags.description;
+  if (flags["clear-composition"]) {
+    opts.composes = [];
+  } else if (flags.compose !== undefined) {
+    await assertCompositeShapesEnabled(ctx, "--compose");
+    opts.composes = flags.compose;
+  }
   const response = await ctx.client.shape.revise(org, repo2, shapeName, newFields, opts);
   const result = shapeChangeFromReceipt(response.receipt);
   let diff;
@@ -65841,6 +66227,7 @@ var SHAPE_DOMAIN = defineDomain({
       examples: [
         `wh shape create GameConfig --repo org/repo --fields '{"x":"number"}'`,
         "wh shape create GameConfig --repo org/repo --file fields.json",
+        "wh shape create AnimalSummary --fields '{}' --compose Animal --compose Summary",
         `wh shape create Player --fields '{"name":{"type":"string","minLength":1,"maxLength":40},"role":{"type":"string","enum":["dm","player"]},"level":{"type":"number","minimum":1,"integer":true},"home":{"type":"wref","shape":"Location"},"tags":{"type":"array","items":"string","minItems":1}}'`
       ],
       notes: [...FIELD_CONSTRAINTS_NOTES],
@@ -67965,7 +68352,7 @@ async function dispatch(ctx) {
   await dispatchDomain(ctx, invocation);
 }
 // ../../packages/warmhub-cli/src/manifest/shared-infra.ts
-var SHARED_INFRA_SHAPES = findSystemComponent(SYSTEM_COMPONENT_ID)?.shapes ?? [];
+var SHARED_INFRA_SHAPES = findSystemComponent(SYSTEM_COMPONENT_ID)?.shapes.filter((shape) => shape.installInfra === true) ?? [];
 // ../../packages/warmhub-cli/src/parser/binder.ts
 function effectiveSpecs(specs, options) {
   return specs.map((spec) => {
@@ -69363,7 +69750,7 @@ function resolveLogLevel(flagLevel, env) {
 // package.json
 var package_default3 = {
   name: "@warmhub/cli",
-  version: "0.116.0",
+  version: "0.118.0",
   private: false,
   type: "module",
   description: "The wh CLI for WarmHub — create repos, commit and query data, and compound knowledge with your AI agents.",
@@ -69988,5 +70375,5 @@ process.exitCode = interceptedExitCode === undefined ? await runPreparedCli(laun
   version: package_default3.version
 }) : interceptedExitCode;
 
-//# debugId=49B7F9EF6B29BE1264756E2164756E21
-//# warmhub-cli-build-info {"cliVersion":"0.116.0","sdkVersion":"0.114.0"}
+//# debugId=E526A210005F6CCA64756E2164756E21
+//# warmhub-cli-build-info {"cliVersion":"0.118.0","sdkVersion":"0.116.0"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warmhub/cli",
-  "version": "0.116.0",
+  "version": "0.118.0",
   "private": false,
   "type": "module",
   "description": "The wh CLI for WarmHub — create repos, commit and query data, and compound knowledge with your AI agents.",