@fenglimg/fabric-shared 2.2.0 → 2.3.0-rc.10

package/dist/{chunk-5AKCRBKJ.js → chunk-TV264D7E.js}

@@ -18,6 +18,7 @@ import { z as z2 } from "zod";
 var PERSONAL_SCOPE = "personal";
 var KNOWN_SCOPE_PREFIXES = ["personal", "team", "project", "org"];
 var SCOPE_COORDINATE_PATTERN = /^[a-z0-9_-]+(:[a-z0-9_-]+)*$/u;
+var SCOPE_COORDINATE_HINT = 'scope coordinate must look like "project:fabric-v2", "team", or "personal" \u2014 lowercase [a-z0-9_-] segments joined by ":"';
 var scopeCoordinateSchema = z2.string().min(1).regex(
   SCOPE_COORDINATE_PATTERN,
   "scope coordinate must be ':'-joined lowercase [a-z0-9_-] segments"
@@ -46,21 +47,25 @@ var structuredWarningSchema = z3.object({
 });
 var _knowledgeTypeEnum = z3.enum(["models", "decisions", "guidelines", "pitfalls", "processes"]);
 var _maturityEnum = z3.enum(["draft", "verified", "proven"]);
-var _layerEnum = z3.enum(["personal", "team"]);
 var _ruleDescriptionSchema = z3.object({
   summary: z3.string(),
   intent_clues: z3.array(z3.string()),
-  tech_stack: z3.array(z3.string()),
-  impact: z3.array(z3.string()),
+  // wire-slim (payload): fab_recall projects a LEAN description (summary +
+  // must_read_if + intent_clues + knowledge_type — the selection signal), leaving
+  // tech_stack/impact to be Read on demand via read_path (KT-DEC-0026 lean
+  // contract at the field level). So they are optional on the wire. plan-context
+  // still returns them in full — zod keeps optional-present values, only ABSENT is
+  // now allowed, so no plan-context consumer regresses.
+  tech_stack: z3.array(z3.string()).optional(),
+  impact: z3.array(z3.string()).optional(),
   must_read_if: z3.string(),
-  entities: z3.array(z3.string()).optional(),
   // v2.0: optional knowledge-entry fields. Absent for v1.x rules; present for
-  // entries that declare frontmatter `id/type/maturity/layer`.
+  // entries that declare frontmatter `id/type/maturity`. W4/Track1: the redundant
+  // `knowledge_layer` field was removed — a candidate's layer is derived from its
+  // stable_id prefix (KP-→personal, else team; KT-DEC-0004).
   id: z3.string().optional(),
   knowledge_type: _knowledgeTypeEnum.optional(),
   maturity: _maturityEnum.optional(),
-  knowledge_layer: _layerEnum.optional(),
-  layer_reason: z3.string().optional(),
   created_at: z3.string().optional(),
   // v2.0.0-rc.38 UX-3 (D-MCP fold ③): these three were previously carried ONLY
   // as top-level mirrors on the index item. With the mirrors removed,
@@ -74,7 +79,12 @@ var _ruleDescriptionSchema = z3.object({
   // schema must also carry `related`, else zod strips the graph edges on output
   // validation and they never reach the client (MC1 include_related / fabric-
   // connect would see nothing). Mirrors the agents-meta ruleDescriptionSchema.
-  related: z3.array(z3.string()).optional()
+  related: z3.array(z3.string()).optional(),
+  // v2.2 glossary aliases FIELD (C-001): mirrors agents.ts RuleDescription.
+  // MUST be declared here or zod .strip() drops aliases on output validation
+  // before plan-context feeds them into the BM25 body — long-tail alias terms
+  // would never reach the lexical/vector index (KT-PIT-0018 zod-strip lesson).
+  aliases: z3.array(z3.string()).optional()
 });
 var _descriptionIndexItemSchema = z3.object({
   stable_id: z3.string(),
@@ -129,6 +139,7 @@ var _preflightDiagnosticSchema = z3.object({
   stable_ids: z3.array(z3.string()).optional(),
   path: z3.string().optional()
 });
+var _recallDropReasonSchema = z3.enum(["retrieval_budget", "payload_budget"]);
 var planContextOutputSchema = z3.object({
   revision_hash: z3.string(),
   stale: z3.boolean(),
@@ -143,12 +154,16 @@ var planContextOutputSchema = z3.object({
   // duplicated into every entry's requirement_profile). Omitted when no intent.
   intent: z3.string().optional(),
   candidates: z3.array(_descriptionIndexItemSchema),
-  // v2.2 A-INFRA-3 (W1-T3-TOPK) / MC4-payload-budget (W1-T4): number of
-  // lower-ranked candidates dropped by the unified truncation chain (top_k cap
-  // + payload-budget trim). Present and > 0 ONLY when truncation fired, so the
-  // steady-state wire shape is unchanged. Lets the LLM know the returned set is
-  // not exhaustive ("N more exist; narrow your intent").
-  omitted_candidate_count: z3.number().int().nonnegative().optional(),
+  // v2.2 A-INFRA-3 (W1-T3-TOPK) / MC4-payload-budget (W1-T4) / K6 (W3-K):
+  // structured list of lower-ranked candidates dropped by the unified truncation
+  // chain, each tagged with WHY it was dropped (`retrieval_budget` = top_k cap +
+  // ratio-to-top floor; `payload_budget` = MCP payload-byte trim). Present and
+  // non-empty ONLY when truncation fired, so the steady-state wire shape is
+  // unchanged. Replaces the bare numeric omission count so the LLM sees WHICH
+  // candidates were dropped and can act ("these N exist; narrow your intent").
+  // Reuses the archive-scan {key,reason} omission convention
+  // (_recallDropReasonSchema, keyed on id here).
+  dropped: z3.array(z3.object({ id: z3.string(), reason: _recallDropReasonSchema })).optional(),
   preflight_diagnostics: z3.array(_preflightDiagnosticSchema),
   warnings: z3.array(structuredWarningSchema).optional(),
   // v2.0.0-rc.22 Scope D T-D2: optional auto-heal banner fields. Surfaced
@@ -188,7 +203,11 @@ var planContextHintNarrowEntrySchema = z3.object({
   // W2-2 (KT-DEC-0027): the entry's must_read_if trigger hook, forwarded for the
   // SessionStart REFERENCE rendering (decision/pitfall/process → title + hook).
   // Optional — omitted when the frontmatter declares none.
-  must_read_if: z3.string().optional()
+  must_read_if: z3.string().optional(),
+  // TASK-003 (impact-map MVP): the entry's impact list, forwarded so the narrow
+  // PreToolUse hint can surface the consequences of ignoring this knowledge when
+  // editing a matching relevance path. Optional — omitted when none declared.
+  impact: z3.array(z3.string()).optional()
 });
 var planContextHintOutputSchema = z3.object({
   version: z3.literal(1),
@@ -236,8 +255,8 @@ var knowledgeSectionsOutputSchema = z3.object({
   diagnostics: z3.array(
     // v2.0.0-rc.23 TASK-013 (F8b): `missing_section` was removed alongside the
     // A-set enum. `missing_knowledge_metadata` stays as the warn-level signal
-    // for un-migrated v1.x entries (no knowledge_type AND no knowledge_layer
-    // in frontmatter). Does NOT block selection.
+    // for un-migrated v1.x entries (no knowledge_type in frontmatter). Does NOT
+    // block selection.
     z3.object({
       code: z3.enum(["missing_knowledge_metadata", "unresolved_selected_id"]),
       severity: z3.literal("warn"),
@@ -293,39 +312,66 @@ var recallInputSchema = z3.object({
     "When true, also surface the one-hop `related` graph neighbours (of the surfaced entries) that are present in the candidate set \u2014 their descriptions and read paths, NOT their bodies."
   )
 });
+var _recallEntrySchema = z3.object({
+  stable_id: z3.string(),
+  // 1-based relevance rank (entries are returned best-first). The surfaced
+  // ranking signal — entries are already sorted, rank makes the order explicit.
+  rank: z3.number().int().positive(),
+  // The DESCRIPTION (summary / intent_clues / must_read_if / related ...). No body.
+  description: _ruleDescriptionSchema,
+  // on-disk knowledge file to Read for the full body. Omitted when the entry has
+  // no resolvable file (description-only discovery) or was scoped out by `ids`.
+  read_path: z3.string().optional(),
+  // originating store alias (omitted for unqualified / single-store entries).
+  store: z3.object({ alias: z3.string() }).optional(),
+  // true when this entry's body is ALSO injected at SessionStart (broad
+  // model/guideline "ALWAYS-ACTIVE") — skip the Read, it is already in context.
+  body_in_context: z3.boolean().optional(),
+  // P1 recall-observability: the fused relevance score this entry scored during
+  // the plan-context sort (was computed internally but dropped before this wave).
+  // Optional + additive — backward-compatible. MUST be declared here or zod
+  // .strip() silently drops it at the MCP boundary (KT-PIT-0005).
+  score: z3.number().optional(),
+  // P1 recall-observability: numbers-only decomposition of `score` into its
+  // weighted signal contributions. NEVER carries body/description text — preserves
+  // the lean read_path contract (KT-DEC-0019 / KT-GLD-0005). bm25_rank/vector_rank
+  // are reserved for a later RRF wave (declared so the wire never strips them).
+  score_breakdown: z3.object({
+    final: z3.number(),
+    bm25: z3.number().optional(),
+    bm25_rank: z3.number().optional(),
+    vector: z3.number().optional(),
+    vector_rank: z3.number().optional(),
+    salience: z3.number(),
+    recency: z3.number(),
+    locality: z3.number(),
+    // BORROW-008 proximity boost — MUST be declared or zod .strip() drops it at
+    // the MCP boundary (KT-PIT-0005), desyncing wire `final` from its components.
+    proximity: z3.number(),
+    // PLN-004 F1 credibility content-age decay MULTIPLIER factor — optional
+    // (only present once the multiplier is wired). MUST be declared or zod
+    // .strip() drops it at the MCP boundary (KT-PIT-0005).
+    credibility: z3.number().optional()
+  }).optional()
+});
 var recallOutputSchema = z3.object({
   revision_hash: z3.string(),
   stale: z3.boolean(),
-  // v2.0.0-rc.38 UX-1/UX-4: mirrors planContextOutputSchema fold ① — per-path
-  // description_index collapsed into a single top-level `candidates`, and
-  // `preflight_diagnostics` lifted out of the removed `shared` wrapper.
-  entries: z3.array(
-    z3.object({
-      path: z3.string(),
-      requirement_profile: _requirementProfileSchema
-    })
-  ),
-  // v2.2 payload de-dup: single top-level echo of the caller's `intent` (was
-  // duplicated into every entry's requirement_profile). Omitted when no intent.
+  // ux-w2-4: single unified entry list (was candidates[] + paths[] + per-path
+  // requirement-profile entries[]). Each item carries description + read_path +
+  // rank + body_in_context, so the agent never joins two arrays on stable_id.
+  entries: z3.array(_recallEntrySchema),
+  // v2.2 payload de-dup: single top-level echo of the caller's `intent`.
+  // Omitted when no intent.
   intent: z3.string().optional(),
-  // W1 (KT-DEC-0026): the discovery index — every surfaced candidate's
-  // DESCRIPTION (summary / intent_clues / must_read_if / related ...). No body.
-  candidates: z3.array(_descriptionIndexItemSchema),
-  // W1 (KT-DEC-0026): the read-path index — one entry per surfaced candidate
-  // (scoped by `ids` when provided), in ranked order. `path` is the on-disk
-  // knowledge file the agent Reads to load the body on demand; `store` is the
-  // originating store alias (omitted for unqualified entries).
-  paths: z3.array(
-    z3.object({
-      stable_id: z3.string(),
-      path: z3.string(),
-      store: z3.object({ alias: z3.string() }).optional()
-    })
-  ),
-  // Number of lower-ranked candidates dropped by the retrieval budget. Present
-  // (and > 0) ONLY when truncation fired — keeps the steady-state wire shape
-  // unchanged while signalling "more exist; narrow your intent".
-  omitted_candidate_count: z3.number().int().nonnegative().optional(),
+  // K6 (W3-K): structured list of lower-ranked candidates dropped by the
+  // retrieval pipeline, each tagged with WHY (`retrieval_budget` = top_k cap +
+  // ratio-to-top floor; `payload_budget` = MCP payload-byte trim). Present (and
+  // non-empty) ONLY when truncation fired — keeps the steady-state wire shape
+  // unchanged while signalling which entries exist ("narrow your intent"), now
+  // with a controlled reason instead of a bare count. Reuses the archive-scan
+  // {key,reason} omission convention (_recallDropReasonSchema, keyed on id).
+  dropped: z3.array(z3.object({ id: z3.string(), reason: _recallDropReasonSchema })).optional(),
   preflight_diagnostics: z3.array(_preflightDiagnosticSchema),
   warnings: z3.array(structuredWarningSchema).optional(),
   auto_healed: z3.boolean().optional(),
@@ -366,6 +412,8 @@ var archiveScanOutputSchema = z3.object({
   // in first-seen order — ready for the Skill to load digests + stitch.
   session_ids: z3.array(z3.string()),
   // Sessions dropped by the filter, with the rule that fired (audit/debug).
+  // Shares the {key,reason} omission convention with recall's dropped[] above
+  // (keys on session_id here, on id in recall).
   dropped: z3.array(
     z3.object({
       session_id: z3.string(),
@@ -428,15 +476,19 @@ var _FabExtractKnowledgeInputBaseSchema = z3.object({
   user_messages_summary: z3.string().describe("Skill-side summary of the user's intent/messages, kept compact"),
   type: z3.enum(["decisions", "pitfalls", "guidelines", "models", "processes"]).describe("Knowledge type bucket (plural form, mirrors directory layout)"),
   slug: z3.string().describe("URL-safe short identifier proposed by the Skill; server may sanitize"),
-  // Store-only cutover: layer is a compatibility audience hint. The server
-  // resolves the actual write target through semantic_scope/write_routes and
-  // writes to the selected mounted store's knowledge/pending/<type>/ tree.
-  // Defaults to 'team' to preserve existing call sites (Skill bumps as needed).
-  layer: z3.enum(["team", "personal"]).optional().describe(
-    "Compatibility storage audience. 'personal' writes to the personal store; non-personal writes resolve by semantic_scope/write_routes. Defaults to 'team'."
-  ),
-  semantic_scope: z3.string().regex(SCOPE_COORDINATE_PATTERN).optional().describe(
-    "Logical audience/write route coordinate for this pending entry, e.g. personal, team, project:fabric-v2, org:acme:team:platform. Server validates and resolves it through write_routes."
+  // v2.2 C1 (W1) — author-facing scope is now TWO fields only: `audience` +
+  // `paths`. Everything else (layer / visibility_store / relevance_scope /
+  // store) is engine-derived, never author input (C1 §一.1). The physical write
+  // store is the hard privacy boundary (cross-store-write R5#3); `audience` only
+  // subdivides WHO within that boundary.
+  //
+  //   audience — the open scope coordinate describing WHO the entry is for
+  //              (personal | team | project:x | org:y...). Replaces the old
+  //              `layer` + `semantic_scope` pair: a `personal` coordinate routes
+  //              to the personal store; everything else resolves via write_routes.
+  //              Omit → engine defaults to project:<active> (bound repo) or team.
+  audience: z3.string().regex(SCOPE_COORDINATE_PATTERN, { message: SCOPE_COORDINATE_HINT }).optional().describe(
+    "WHO this entry is for \u2014 an open scope coordinate (personal | team | project:x | org:y...). The sole author-facing audience field; the engine derives layer/visibility_store/store from it + the physical write store. Omit to default to project:<active> (bound repo) or team."
   ),
   // v2.0.0-rc.7 T6: proposed_reason — required enum that drives `## Why
   // proposed` rendering. Skills (archive / import / review) infer the
@@ -462,11 +514,16 @@ var _FabExtractKnowledgeInputBaseSchema = z3.object({
   // a `knowledge_scope_degraded` event keyed by `pending:<idempotency_key>`.
   // NOTE: these fields MUST NOT be part of the idempotency hash inputs at
   // extract-knowledge.ts:78 — preserves rc.5→rc.7 collision detection.
-  relevance_scope: z3.enum(["narrow", "broad"]).optional().describe(
-    "Optional relevance scope. 'narrow' restricts plan-context-hint surfacing to relevance_paths; 'broad' always surfaces. Omit to let the meta-builder default to 'broad'. Personal + narrow is silently degraded to broad + []."
-  ),
-  relevance_paths: z3.array(z3.string()).optional().describe(
-    "Optional path anchors for narrow scope. Workspace-relative globs or paths. Omit to let the meta-builder default to []. Ignored when scope is broad (server preserves the array for audit)."
+  //   paths — relevance anchors (workspace-relative globs/paths). The engine
+  //           DERIVES relevance_scope from this field's presence: non-empty →
+  //           narrow (surface only when an edit matches an anchor); empty/omitted
+  //           → broad (always surface). This eliminates the old separate
+  //           relevance_scope flag and its narrow+empty illegal state by
+  //           construction (KT-MOD-0001). Glob syntax follows Copilot `applyTo`
+  //           / Cursor `globs` (cross-client moat). Personal audience forces
+  //           broad+[] (workspace-relative paths cross-project lose meaning).
+  paths: z3.array(z3.string()).optional().describe(
+    "Relevance anchors (workspace-relative globs/paths). Non-empty \u2192 narrow (surface only on matching edits); empty/omitted \u2192 broad (always surface). The engine derives relevance_scope from this \u2014 there is no separate scope flag."
   ),
   // v2.0.0-rc.23 TASK-006 (a-C1): four optional structured fields that the
   // skill-side LLM populates from raw observations. The same information
@@ -512,7 +569,7 @@ var _FabExtractKnowledgeInputBaseSchema = z3.object({
   // discover unclaimed slots, then propagates the chosen slot label here
   // so the resulting pending entry counts toward coverage.
   //
-  // STRICT optionality: every non-onboard fab_extract_knowledge call MUST
+  // STRICT optionality: every non-onboard fab_propose call MUST
   // omit this field. The skill is the only producer; downstream consumers
   // (plan_context retrieval, doctor lints) treat missing as a steady-state
   // signal that the entry was NOT part of an onboard pass.
@@ -624,13 +681,21 @@ var _fabReviewModifyChangesSchema = z3.object({
   // edges via fab_recall and sends the merged set. Absent this field the modify
   // path silently dropped `related` via zod .strip() (KT-PIT-0005 recurrence),
   // leaving the only programmatic related-write path non-functional.
-  related: z3.array(z3.string()).optional()
+  related: z3.array(z3.string()).optional(),
+  // rc.9 (2026-07-06): discovery-signal scalar patches — must_read_if triggers
+  // Reference-type entry surfacing; intent_clues drives the AI's "should I Read
+  // the body?" judgment; impact enumerates consequence prose surfaced in the
+  // BM25F body slot. Before rc.9 these three fields were undeclared here, so
+  // fab_review modify silently .strip()'d them (KT-PIT-0005 recurrence) and the
+  // only path to fix a bad-shape must_read_if / missing intent_clues was direct
+  // Edit — bypassing the skill audit trail. All three are REPLACE semantics
+  // (mirror tags/related). must_read_if is a scalar string; intent_clues +
+  // impact are flow-arrays.
+  must_read_if: z3.string().optional(),
+  intent_clues: z3.array(z3.string()).optional(),
+  impact: z3.array(z3.string()).optional()
 });
 var FabReviewInputSchema = z3.discriminatedUnion("action", [
-  z3.object({
-    action: z3.literal("list"),
-    filters: _fabReviewFiltersSchema
-  }),
   z3.object({
     action: z3.literal("approve"),
     pending_paths: z3.array(z3.string()).min(1)
@@ -663,11 +728,6 @@ var FabReviewInputSchema = z3.discriminatedUnion("action", [
       layer: z3.enum(["team", "personal"])
     })
   }),
-  z3.object({
-    action: z3.literal("search"),
-    query: z3.string().min(1),
-    filters: _fabReviewFiltersSchema
-  }),
   z3.object({
     action: z3.literal("defer"),
     pending_paths: z3.array(z3.string()).min(1),
@@ -675,13 +735,32 @@ var FabReviewInputSchema = z3.discriminatedUnion("action", [
     reason: z3.string().optional()
   })
 ]);
-var FabReviewInputShape = {
-  action: z3.enum(["list", "approve", "reject", "modify", "modify-content", "modify-layer", "search", "defer"]).describe(
-    "Action selector. Discriminates the per-action fields below; required. modify-content edits scalars (no layer); modify-layer is the layer-flip path (changes.layer required); modify is the legacy combined alias."
+var FabPendingInputSchema = z3.discriminatedUnion("action", [
+  z3.object({
+    action: z3.literal("list"),
+    filters: _fabReviewFiltersSchema
+  }),
+  z3.object({
+    action: z3.literal("search"),
+    query: z3.string().min(1),
+    filters: _fabReviewFiltersSchema
+  })
+]);
+var FabPendingInputShape = {
+  action: z3.enum(["list", "search"]).describe(
+    "Action selector. Discriminates the per-action fields below; required. list browses pending entries; search ranges over pending + canonical knowledge."
   ),
   filters: _fabReviewFiltersSchema.describe(
     "Optional filters (type/layer/maturity/tags/created_after). Used by action=list and action=search."
   ),
+  query: z3.string().min(1).optional().describe(
+    "Substring query against title/summary/tags/path. Required (non-empty) when action=search."
+  )
+};
+var FabReviewInputShape = {
+  action: z3.enum(["approve", "reject", "modify", "modify-content", "modify-layer", "defer"]).describe(
+    "Action selector. Discriminates the per-action fields below; required. modify-content edits scalars (no layer); modify-layer is the layer-flip path (changes.layer required); modify is the legacy combined alias. (list/search moved to the read-only fab_pending tool.)"
+  ),
   pending_paths: z3.array(z3.string()).min(1).optional().describe(
     "Workspace-relative pending entry paths. Required when action=approve|reject|defer (non-empty array)."
   ),
@@ -694,9 +773,6 @@ var FabReviewInputShape = {
   changes: _fabReviewModifyChangesSchema.optional().describe(
     "Frontmatter scalar patches (title/summary/layer/maturity/tags/relevance_*/semantic_scope/related). Required when action=modify. semantic_scope re-scopes the entry's resolution coordinate in place (e.g. team \u2192 project:<id>) without moving stores; personal-root coordinates are rejected (use modify-layer)."
   ),
-  query: z3.string().min(1).optional().describe(
-    "Substring query against title/summary/tags/path. Required (non-empty) when action=search."
-  ),
   until: z3.string().datetime().optional().describe(
     "ISO-8601 datetime upper bound for the deferral. Optional; used only when action=defer."
   )
@@ -757,11 +833,6 @@ var _fabReviewSearchItemSchema = z3.object({
   stable_id: z3.string().optional()
 });
 var FabReviewOutputSchema = z3.discriminatedUnion("action", [
-  z3.object({
-    action: z3.literal("list"),
-    items: z3.array(_fabReviewListItemSchema),
-    warnings: z3.array(structuredWarningSchema).optional()
-  }),
   z3.object({
     action: z3.literal("approve"),
     approved: z3.array(z3.object({ pending_path: z3.string(), stable_id: z3.string() })),
@@ -781,25 +852,36 @@ var FabReviewOutputSchema = z3.discriminatedUnion("action", [
     warnings: z3.array(structuredWarningSchema).optional()
   }),
   z3.object({
-    action: z3.literal("search"),
-    // v2.0.0-rc.29 TASK-007 (BUG-M4): search returns the new search-item
-    // shape with `area` discriminator + neutrally-named `path` field.
-    items: z3.array(_fabReviewSearchItemSchema),
+    action: z3.literal("defer"),
+    deferred: z3.array(z3.string()),
+    warnings: z3.array(structuredWarningSchema).optional()
+  })
+]);
+var FabPendingOutputSchema = z3.discriminatedUnion("action", [
+  z3.object({
+    action: z3.literal("list"),
+    items: z3.array(_fabReviewListItemSchema),
     warnings: z3.array(structuredWarningSchema).optional()
   }),
   z3.object({
-    action: z3.literal("defer"),
-    deferred: z3.array(z3.string()),
+    action: z3.literal("search"),
+    items: z3.array(_fabReviewSearchItemSchema),
     warnings: z3.array(structuredWarningSchema).optional()
   })
 ]);
-var FabReviewOutputShape = {
-  action: z3.enum(["list", "approve", "reject", "modify", "search", "defer"]).describe(
+var FabPendingOutputShape = {
+  action: z3.enum(["list", "search"]).describe(
     "Echoes the input action; clients can switch on it for per-variant fields below."
   ),
   items: z3.array(z3.union([_fabReviewListItemSchema, _fabReviewSearchItemSchema])).optional().describe(
     "Pending entries (action=list, `pending_path` shape) or pending+canonical entries (action=search, `area`+`path` shape)."
   ),
+  warnings: z3.array(structuredWarningSchema).optional()
+};
+var FabReviewOutputShape = {
+  action: z3.enum(["approve", "reject", "modify", "defer"]).describe(
+    "Echoes the input action; clients can switch on it for per-variant fields below. (list/search results moved to the read-only fab_pending tool.)"
+  ),
   approved: z3.array(z3.object({ pending_path: z3.string(), stable_id: z3.string() })).optional().describe(
     "Allocated stable ids paired with their original pending paths. Present when action=approve."
   ),
@@ -829,6 +911,13 @@ var fabReviewAnnotations = {
   openWorldHint: false,
   title: "Review pending knowledge entries"
 };
+var fabPendingAnnotations = {
+  readOnlyHint: true,
+  idempotentHint: true,
+  destructiveHint: false,
+  openWorldHint: false,
+  title: "Browse and search pending knowledge entries"
+};
 var citeContractMetricsSchema = z3.object({
   decisions_cited: z3.number().int().nonnegative(),
   pitfalls_cited: z3.number().int().nonnegative(),
@@ -1035,8 +1124,6 @@ var KnowledgeEntryFrontmatterSchema = z3.object({
   // draft | verified | proven
   layer: LayerSchema,
   // personal | team
-  layer_reason: z3.string().optional(),
-  // why this layer (for ambiguous cases)
   created_at: z3.string()
   // ISO 8601 timestamp
   // Note: 'tags' and other fields can be added later but core schema is these 6
@@ -1071,6 +1158,7 @@ export {
   PERSONAL_SCOPE,
   KNOWN_SCOPE_PREFIXES,
   SCOPE_COORDINATE_PATTERN,
+  SCOPE_COORDINATE_HINT,
   scopeCoordinateSchema,
   scopeRoot,
   isPersonalScope,
@@ -1097,10 +1185,15 @@ export {
   FabExtractKnowledgeOutputSchema,
   fabExtractKnowledgeAnnotations,
   FabReviewInputSchema,
+  FabPendingInputSchema,
+  FabPendingInputShape,
   FabReviewInputShape,
   FabReviewOutputSchema,
+  FabPendingOutputSchema,
+  FabPendingOutputShape,
   FabReviewOutputShape,
   fabReviewAnnotations,
+  fabPendingAnnotations,
   citeContractMetricsSchema,
   citeLayerTypeBreakdownSchema,
   citeCoverageReportSchema,