@fenglimg/fabric-shared 2.0.0-rc.22 → 2.0.0-rc.23

package/dist/chunk-GDYPVGWT.js

@@ -0,0 +1,671 @@
+// src/schemas/api-contracts.ts
+import { z as z2 } from "zod";
+
+// src/onboard-slots.ts
+import { z } from "zod";
+var ONBOARD_SLOT_NAMES = [
+  "tech-stack-decision",
+  "architecture-pattern",
+  "code-style-tone",
+  "build-system-idiom",
+  "domain-vocabulary"
+];
+var onboardSlotSchema = z.enum(ONBOARD_SLOT_NAMES);
+var ONBOARD_SLOT_TOTAL = ONBOARD_SLOT_NAMES.length;
+
+// src/schemas/api-contracts.ts
+var structuredWarningSchema = z2.object({
+  code: z2.string(),
+  file: z2.string(),
+  line: z2.number().optional(),
+  action_hint: z2.string()
+});
+var _knowledgeTypeEnum = z2.enum(["model", "decision", "guideline", "pitfall", "process"]);
+var _maturityEnum = z2.enum(["draft", "verified", "proven"]);
+var _layerEnum = z2.enum(["personal", "team"]);
+var _ruleDescriptionSchema = z2.object({
+  summary: z2.string(),
+  intent_clues: z2.array(z2.string()),
+  tech_stack: z2.array(z2.string()),
+  impact: z2.array(z2.string()),
+  must_read_if: z2.string(),
+  entities: z2.array(z2.string()).optional(),
+  // v2.0: optional knowledge-entry fields. Absent for v1.x rules; present for
+  // entries that declare frontmatter `id/type/maturity/layer`.
+  id: z2.string().optional(),
+  knowledge_type: _knowledgeTypeEnum.optional(),
+  maturity: _maturityEnum.optional(),
+  knowledge_layer: _layerEnum.optional(),
+  layer_reason: z2.string().optional(),
+  created_at: z2.string().optional()
+});
+var _descriptionIndexItemSchema = z2.object({
+  stable_id: z2.string(),
+  level: z2.enum(["L0", "L1", "L2"]),
+  required: z2.boolean(),
+  selectable: z2.boolean(),
+  description: _ruleDescriptionSchema,
+  // v2.0: top-level knowledge surface for client-side filtering. Mirrors
+  // description.* — exposed here so MCP clients can filter without reaching
+  // into the nested payload.
+  type: _knowledgeTypeEnum.optional(),
+  maturity: _maturityEnum.optional(),
+  layer: _layerEnum.optional(),
+  layer_reason: z2.string().optional(),
+  // v2/rc.2: tag list shipped via frontmatter (commit a85121a). Exposed at
+  // the API surface so MCP clients can filter without re-parsing the
+  // description payload. Absent on legacy entries; consumers should treat
+  // missing as [].
+  tags: z2.array(z2.string()).optional(),
+  // v2.0-rc.5 (C1): relevance scope/paths drive plan-context-hint narrowing.
+  // Exposed at the API surface so MCP clients (and the `fabric
+  // plan-context-hint` CLI from D1) can filter without re-parsing the
+  // description payload. Defaults applied at the parse layer
+  // (knowledge-meta-builder + agentsMetaNodeBaseSchema):
+  //   relevance_scope → 'broad'  (always-surface, safe default)
+  //   relevance_paths → []       (no path anchors)
+  // Consumers should treat missing fields as broad/[]. Optional on the wire
+  // so older servers without rc.5 schemas remain wire-compatible.
+  relevance_scope: z2.enum(["narrow", "broad"]).optional(),
+  relevance_paths: z2.array(z2.string()).optional()
+});
+var _requirementProfileSchema = z2.object({
+  target_path: z2.string(),
+  path_segments: z2.array(z2.string()),
+  extension: z2.string(),
+  known_tech: z2.array(z2.string()),
+  user_intent: z2.string(),
+  detected_entities: z2.array(z2.string())
+});
+var planContextInputSchema = z2.object({
+  paths: z2.array(z2.string()).min(1).describe("Candidate file paths to build neutral rule selection context for"),
+  intent: z2.string().optional().describe("User-stated requirement or implementation intent; used only to build a neutral requirement profile"),
+  known_tech: z2.array(z2.string()).optional().describe("Known technologies involved in the requirement profile"),
+  detected_entities: z2.record(z2.array(z2.string())).optional().describe("Optional path-keyed detected entities for the requirement profile"),
+  client_hash: z2.string().optional().describe("Revision hash from a prior fab_plan_context response; enables stale detection"),
+  correlation_id: z2.string().optional().describe("Optional caller-provided correlation id for Event Ledger records"),
+  session_id: z2.string().optional().describe("Optional caller-provided session id for Event Ledger records"),
+  // v2.0-rc.5 A3 (TASK-007): `include_deprecated` removed — it was a no-op
+  // placeholder (MaturitySchema has no `deprecated` value). When the maturity
+  // enum widens we re-introduce the flag as part of that protocol bump.
+  // v2/rc.2 (Q6): client-supplied layer scope. When omitted, the server
+  // falls back to fabric-config.default_layer_filter (TASK-002) so a single
+  // workspace policy controls the default. Explicit values override.
+  layer_filter: z2.enum(["team", "personal", "both"]).optional().describe(
+    "Restrict description_index to the named layer. Default: fabric-config.default_layer_filter (TASK-002)."
+  ),
+  // v2.0-rc.5 C3 (TASK-012): explicit path context for `narrow` relevance
+  // filtering. When omitted, the server falls back to `paths` so existing
+  // callers see narrowing against the requested paths. When the resolved
+  // list is empty, the narrow filter fails open (every narrow entry passes).
+  target_paths: z2.array(z2.string()).optional().describe(
+    "Path context for narrow-scope relevance filtering. Defaults to `paths`; empty = no filter."
+  )
+});
+var planContextOutputSchema = z2.object({
+  revision_hash: z2.string(),
+  stale: z2.boolean(),
+  selection_token: z2.string(),
+  entries: z2.array(
+    z2.object({
+      path: z2.string(),
+      requirement_profile: _requirementProfileSchema,
+      description_index: z2.array(_descriptionIndexItemSchema)
+    })
+  ),
+  shared: z2.object({
+    description_index: z2.array(_descriptionIndexItemSchema),
+    preflight_diagnostics: z2.array(
+      z2.object({
+        code: z2.literal("missing_description"),
+        severity: z2.literal("warn"),
+        message: z2.string(),
+        stable_ids: z2.array(z2.string()).optional(),
+        path: z2.string().optional()
+      })
+    )
+  }),
+  warnings: z2.array(structuredWarningSchema).optional(),
+  // v2.0.0-rc.22 Scope D T-D2: optional auto-heal banner fields. Surfaced
+  // ONLY when the loadActiveMetaOrStale call detected drift and rebuilt the
+  // meta in-place. Downstream CLI / hint renderers use this pair to render a
+  // "knowledge meta auto-healed (was <prev>, now <curr>)" notice without
+  // having to query the event ledger.
+  auto_healed: z2.boolean().optional(),
+  previous_revision_hash: z2.string().optional()
+});
+var planContextAnnotations = {
+  readOnlyHint: true,
+  idempotentHint: true,
+  destructiveHint: false,
+  openWorldHint: false,
+  title: "Plan rule context"
+};
+var planContextHintNarrowEntrySchema = z2.object({
+  id: z2.string(),
+  type: z2.string(),
+  maturity: z2.string(),
+  summary: z2.string()
+});
+var planContextHintOutputSchema = z2.object({
+  version: z2.literal(1),
+  revision_hash: z2.string(),
+  target_paths: z2.array(z2.string()),
+  narrow: z2.array(planContextHintNarrowEntrySchema),
+  broad_count: z2.number().int().nonnegative()
+});
+var knowledgeSectionsInputSchema = z2.object({
+  selection_token: z2.string().min(1).describe("Selection token returned by fab_plan_context"),
+  ai_selected_stable_ids: z2.array(z2.string()).describe(
+    "Stable ids picked from fab_plan_context entries[].description_index[].stable_id where selectable=true; choose 1..N to fetch bodies for"
+  ),
+  ai_selection_reasons: z2.record(z2.string().min(1)).describe("Reason for each AI-selected L1 stable_id"),
+  correlation_id: z2.string().optional().describe("Optional caller-provided correlation id for Event Ledger records"),
+  session_id: z2.string().optional().describe("Optional caller-provided session id for Event Ledger records"),
+  // v2.0 rc.5 TASK-014 (C5): optional client identity hash propagated into
+  // knowledge_consumed events. Falls back to empty string when unset — full
+  // client-identity propagation deferred to rc.6.
+  client_hash: z2.string().optional().describe("Optional caller-provided client hash propagated into knowledge_consumed events")
+});
+var knowledgeSectionsOutputSchema = z2.object({
+  revision_hash: z2.string(),
+  /**
+   * @deprecated rc.23 TASK-002 F3 — removed in rc.24. The L0/L1/L2 selection
+   * ceremony was fully retired in rc.5 A3 (see comment above
+   * `planContextOutputSchema`); downstream consumers should use
+   * `rules[].level` directly. Kept as optional for one rc to avoid breaking
+   * pre-rc.23 clients that destructure this field.
+   */
+  precedence: z2.tuple([z2.literal("L2"), z2.literal("L1"), z2.literal("L0")]).optional().describe(
+    "DEPRECATED (removed in rc.24): hardcoded L2/L1/L0 precedence tuple from the retired rc.5 selection ceremony. Use rules[].level instead."
+  ),
+  selected_stable_ids: z2.array(z2.string()),
+  rules: z2.array(
+    z2.object({
+      stable_id: z2.string(),
+      level: z2.enum(["L0", "L1", "L2"]),
+      path: z2.string(),
+      // v2.0.0-rc.23 TASK-013 (F8b): replaced the legacy
+      // `sections: Record<string,string>` (keyed by the 4-element A-set enum)
+      // with the full markdown body (frontmatter stripped). Callers scan the
+      // body for whichever B-set heading they need (Summary / Why proposed /
+      // Session context / Evidence) — section-name discipline is now a writer
+      // convention, not an API contract.
+      body: z2.string()
+    })
+  ),
+  diagnostics: z2.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.
+    z2.object({
+      code: z2.literal("missing_knowledge_metadata"),
+      severity: z2.literal("warn"),
+      stable_id: z2.string(),
+      message: z2.string()
+    })
+  ),
+  // v2/rc.3 (Q6): present iff a layer-flip in fab_review/modify changed the
+  // canonical stable_id since the caller's selection_token was minted.
+  // Clients should retry against `redirect_to.stable_id`.
+  redirect_to: z2.object({ stable_id: z2.string() }).optional().describe(
+    "Post-layer-flip redirect. Populated when stable_id changed after token mint (rc.3 fab_review/modify)."
+  ),
+  warnings: z2.array(structuredWarningSchema).optional()
+});
+var knowledgeSectionsAnnotations = {
+  readOnlyHint: true,
+  idempotentHint: true,
+  destructiveHint: false,
+  openWorldHint: false,
+  title: "Filter rule sections"
+};
+var ProposedReasonSchema = z2.enum([
+  "explicit-user-mark",
+  "diagnostic-then-fix",
+  "decision-confirmation",
+  "wrong-turn-revert",
+  "new-dependency-or-pattern",
+  "dismissal-with-reason"
+]);
+var PROPOSED_REASON_DESCRIPTIONS = {
+  "explicit-user-mark": "\u7528\u6237\u663E\u5F0F\u6807\u8BB0\u9700\u5F52\u6863\uFF08always / never / \u4E0B\u6B21\u6CE8\u610F \u7B49\u89C4\u8303\u6027\u8BED\u8A00\uFF09\u3002",
+  "diagnostic-then-fix": "\u8BCA\u65AD\u8FC7\u7A0B\u53D1\u73B0\u65B0\u6A21\u5F0F\u6216\u8E29\u5751\uFF0C\u4FEE\u590D\u540E\u503C\u5F97\u6C89\u6DC0\u3002",
+  "decision-confirmation": "\u22652 \u5019\u9009\u65B9\u6848\u7ECF\u6743\u8861\u540E\u786E\u8BA4\u9009\u578B\uFF0C\u9700\u4FDD\u7559 rationale\u3002",
+  "wrong-turn-revert": "\u5C1D\u8BD5\u67D0\u8DEF\u5F84\u540E\u56DE\u9000\uFF0C\u9519\u8BEF\u8DEF\u5F84\u672C\u8EAB\u662F\u503C\u5F97\u8BB0\u5F55\u7684 pitfall\u3002",
+  "new-dependency-or-pattern": "\u5F15\u5165\u65B0\u4F9D\u8D56 / \u65B0\u6A21\u5F0F / \u65B0\u547D\u540D\u7EA6\u5B9A\u3002",
+  "dismissal-with-reason": "\u7528\u6237\u660E\u786E\u62D2\u7EDD\u67D0\u65B9\u6848\u5E76\u7ED9\u51FA\u539F\u56E0\uFF0C\u539F\u56E0\u5373\u53EF\u5F52\u6863\u77E5\u8BC6\u3002"
+};
+var _sourceSessionsField = z2.array(z2.string().min(1)).min(1);
+var _FabExtractKnowledgeInputBaseSchema = z2.object({
+  // v2.0.0-rc.7 T5: array form. rc.23 dropped the legacy single-string alias.
+  source_sessions: _sourceSessionsField.optional().describe(
+    "Originating session ids; correlates with Event Ledger records. Array form (T5+, rc.23 made it the sole accepted shape)."
+  ),
+  recent_paths: z2.array(z2.string()).describe("Workspace paths recently touched in the source session \u2014 used as scope hints"),
+  user_messages_summary: z2.string().describe("Skill-side summary of the user's intent/messages, kept compact"),
+  type: z2.enum(["decisions", "pitfalls", "guidelines", "models", "processes"]).describe("Knowledge type bucket (plural form, mirrors directory layout)"),
+  slug: z2.string().describe("URL-safe short identifier proposed by the Skill; server may sanitize"),
+  // rc.5 B1: dual pending root. When 'personal', the server writes to
+  // ~/.fabric/knowledge/pending/<type>/; otherwise to .fabric/knowledge/pending/<type>/.
+  // Defaults to 'team' to preserve existing call sites (Skill bumps as needed).
+  layer: z2.enum(["team", "personal"]).optional().describe(
+    "Storage layer for the pending entry. 'team' writes under the workspace; 'personal' writes under the user's home. Defaults to 'team'."
+  ),
+  // v2.0.0-rc.7 T6: proposed_reason — required enum that drives `## Why
+  // proposed` rendering. Skills (archive / import / review) infer the
+  // appropriate reason per their semantics (see each SKILL.md).
+  proposed_reason: ProposedReasonSchema.describe(
+    "Why this entry is being proposed. Drives `## Why proposed` rendering and enables future maturity-promotion scoring."
+  ),
+  // v2.0.0-rc.7 T6: session_context — required 3-5 line markdown blob that
+  // captures the session goal + key turning point. Future-self review reads
+  // this without conversation transcript access. Min length guards against
+  // empty placeholders; cap is soft (no max), Skill caps at ~600 chars.
+  session_context: z2.string().min(20, { message: "session_context must be \u226520 chars (3-5 lines describing goal + turning point)" }).describe(
+    "3-5 line markdown blob \u2014 session goal + key turning point. Reviewed by future-self without transcript access."
+  ),
+  // v2.0.0-rc.8 A1 (skill-contract-fix): relevance scope/paths on the
+  // creation surface. Mirrors `_fabReviewModifyChangesSchema.relevance_*`
+  // (L518-533) verbatim so callers can declare scope at archive time
+  // instead of waiting for a fab_review.modify follow-up. Both fields are
+  // optional — when omitted, the pending file omits the YAML lines entirely
+  // (knowledge-meta-builder defaults to broad + [] at parse time, see
+  // L1007-1021). Personal + narrow is silently degraded to broad + [] at
+  // service entry, mirroring the rc.5 review.ts:725-739 behaviour, and emits
+  // 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: z2.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: z2.array(z2.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)."
+  ),
+  // 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
+  // historically lived only in `## Session context` prose, forcing future-self
+  // reviewers / plan-context retrievers to re-read the entire body to decide
+  // relevance. Lifting them into structured frontmatter lets downstream
+  // surfaces (description_index, scoring, relevance triage) consume them
+  // directly. ALL FOUR ARE STRICTLY OPTIONAL — skills that cannot infer them
+  // confidently must omit, not guess.
+  //
+  // IMPORTANT: these fields MUST NOT participate in the idempotency_key hash
+  // (see rc.8 A1 convention at extract-knowledge.ts — relevance_scope /
+  // relevance_paths follow the same rule). Including them would let an LLM
+  // re-roll of the same observation create a second pending file just because
+  // its inferred metadata wording drifted.
+  intent_clues: z2.array(z2.string()).optional().describe(
+    "Short LLM-readable triggers describing when this rule should fire and when it should not. Each item \u226480 chars, imperative phrasing (e.g. 'when editing Cocos UI batch code', 'NOT for non-batch contexts'). Optional \u2014 omit when the skill cannot infer cleanly."
+  ),
+  tech_stack: z2.array(z2.string()).optional().describe(
+    "Tech stack / languages / frameworks the rule applies to (e.g. ['typescript', 'cocos-creator', 'nodejs']). Inferred from recent_paths file extensions and manifest files. Optional \u2014 omit when the rule is stack-agnostic."
+  ),
+  impact: z2.array(z2.string()).optional().describe(
+    "Consequences of ignoring this rule, used by the LLM to weight relevance vs cost. Each item \u2264120 chars (e.g. 'O(n\xB2) re-render on every frame', 'silent data loss on collision'). Optional \u2014 omit when impact is not observable."
+  ),
+  must_read_if: z2.string().optional().describe(
+    "One-line strong trigger; when this condition holds the entry is considered required reading. Single line \u2264160 chars (e.g. 'touching anything under packages/cli/src/commands/hooks.ts'). Optional \u2014 omit when no single strong trigger fits."
+  ),
+  // v2.0.0-rc.23 TASK-014 (F8c): optional onboard-slot tag. The S5 slot
+  // mechanism reintroduces a Skill-orchestrated "project tone" capture
+  // surface after F8a deleted the auto-`fab scan` baseline pipeline.
+  // fabric-archive's first-run phase reads `fab onboard-coverage` to
+  // 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
+  // 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.
+  //
+  // IDEMPOTENCY: like the four a-C1 fields and the rc.8 A1 relevance pair,
+  // `onboard_slot` MUST NOT participate in the idempotency_key hash at
+  // extract-knowledge.ts:100-106. An LLM that re-rolls the same observation
+  // with a different (or absent) slot must still collapse onto the same
+  // pending file — otherwise the slot mechanic itself could spawn
+  // duplicate entries.
+  onboard_slot: onboardSlotSchema.optional().describe(
+    "Optional slot tag from the S5 onboarding set (tech-stack-decision / architecture-pattern / code-style-tone / build-system-idiom / domain-vocabulary); lets fabric-archive's first-run phase claim a project-tone slot. Skill propose-time only; never required."
+  )
+});
+var FabExtractKnowledgeInputSchema = _FabExtractKnowledgeInputBaseSchema.superRefine(
+  (value, ctx) => {
+    const hasArray = Array.isArray(value.source_sessions) && value.source_sessions.length > 0;
+    if (!hasArray) {
+      ctx.addIssue({
+        code: z2.ZodIssueCode.custom,
+        message: "source_sessions (non-empty string array) is required",
+        path: ["source_sessions"]
+      });
+    }
+  }
+);
+var FabExtractKnowledgeInputShape = _FabExtractKnowledgeInputBaseSchema.shape;
+var FabExtractKnowledgeOutputSchema = z2.object({
+  pending_path: z2.string().describe("Workspace-relative path to the persisted pending entry"),
+  idempotency_key: z2.string().describe("Stable key derived from inputs; identical inputs yield identical key"),
+  // v2.0.0-rc.23 TASK-009 (d): optional warnings surface for the first-reconcile
+  // gate (`meta_stale` / `reconcile_failed`). Absent on the steady-state path.
+  warnings: z2.array(structuredWarningSchema).optional()
+});
+var fabExtractKnowledgeAnnotations = {
+  readOnlyHint: false,
+  idempotentHint: true,
+  destructiveHint: false,
+  openWorldHint: false,
+  title: "Extract pending knowledge entry"
+};
+var _fabReviewFiltersSchema = z2.object({
+  type: z2.enum(["decisions", "pitfalls", "guidelines", "models", "processes"]).optional(),
+  layer: z2.enum(["team", "personal", "both"]).optional(),
+  maturity: z2.enum(["draft", "verified", "proven"]).optional(),
+  tags: z2.array(z2.string()).optional(),
+  // rc.4 TASK-006 fix (c): ISO-8601 lower bound on entry created_at; entries
+  // strictly older than this threshold are excluded from list / search
+  // results. Additive optional field — existing callers unaffected.
+  created_after: z2.string().datetime().optional()
+}).optional();
+var _fabReviewModifyChangesSchema = z2.object({
+  title: z2.string().optional(),
+  summary: z2.string().optional(),
+  // Q7: writing `layer` here triggers a layer-flip; downstream callers may
+  // observe a redirect_to in fab_get_knowledge_sections if stable_id changes.
+  layer: z2.enum(["team", "personal"]).optional(),
+  maturity: z2.enum(["draft", "verified", "proven"]).optional(),
+  tags: z2.array(z2.string()).optional(),
+  // v2.0-rc.5 C3 (TASK-012): relevance scope/paths patches. Applied to
+  // pending AND canonical entries. When an explicit team→personal layer flip
+  // arrives on a narrow entry, the server auto-degrades to broad + [] and
+  // emits a `knowledge_scope_degraded` event regardless of what the caller
+  // sent in these fields (personal-implies-broad).
+  relevance_scope: z2.enum(["narrow", "broad"]).optional(),
+  relevance_paths: z2.array(z2.string()).optional()
+});
+var FabReviewInputSchema = z2.discriminatedUnion("action", [
+  z2.object({
+    action: z2.literal("list"),
+    filters: _fabReviewFiltersSchema
+  }),
+  z2.object({
+    action: z2.literal("approve"),
+    pending_paths: z2.array(z2.string()).min(1)
+  }),
+  z2.object({
+    action: z2.literal("reject"),
+    pending_paths: z2.array(z2.string()).min(1),
+    reason: z2.string().min(1)
+  }),
+  z2.object({
+    action: z2.literal("modify"),
+    pending_path: z2.string().min(1),
+    changes: _fabReviewModifyChangesSchema
+  }),
+  z2.object({
+    action: z2.literal("search"),
+    query: z2.string().min(1),
+    filters: _fabReviewFiltersSchema
+  }),
+  z2.object({
+    action: z2.literal("defer"),
+    pending_paths: z2.array(z2.string()).min(1),
+    until: z2.string().datetime().optional(),
+    reason: z2.string().optional()
+  })
+]);
+var FabReviewInputShape = {
+  action: z2.enum(["list", "approve", "reject", "modify", "search", "defer"]).describe(
+    "Action selector. Discriminates the per-action fields below; required."
+  ),
+  filters: _fabReviewFiltersSchema.describe(
+    "Optional filters (type/layer/maturity/tags/created_after). Used by action=list and action=search."
+  ),
+  pending_paths: z2.array(z2.string()).min(1).optional().describe(
+    "Workspace-relative pending entry paths. Required when action=approve|reject|defer (non-empty array)."
+  ),
+  pending_path: z2.string().min(1).optional().describe(
+    "Workspace-relative pending OR canonical entry path. Required when action=modify."
+  ),
+  reason: z2.string().optional().describe(
+    "Reason string. Required (non-empty) when action=reject; optional when action=defer."
+  ),
+  changes: _fabReviewModifyChangesSchema.optional().describe(
+    "Frontmatter scalar patches (title/summary/layer/maturity/tags/relevance_*). Required when action=modify."
+  ),
+  query: z2.string().min(1).optional().describe(
+    "Substring query against title/summary/tags/path. Required (non-empty) when action=search."
+  ),
+  until: z2.string().datetime().optional().describe(
+    "ISO-8601 datetime upper bound for the deferral. Optional; used only when action=defer."
+  )
+};
+var _fabReviewListItemSchema = z2.object({
+  pending_path: z2.string(),
+  type: z2.enum(["decisions", "pitfalls", "guidelines", "models", "processes"]),
+  layer: z2.enum(["team", "personal"]),
+  maturity: z2.enum(["draft", "verified", "proven"]),
+  tags: z2.array(z2.string()).optional(),
+  title: z2.string().optional(),
+  summary: z2.string().optional(),
+  // rc.5 B1: dual pending root. 'team' = workspace .fabric/knowledge/pending,
+  // 'personal' = ~/.fabric/knowledge/pending. Distinct from `layer` (frontmatter):
+  // origin reflects where the pending file actually lives on disk; layer reflects
+  // the declared classification that will drive the approve destination.
+  origin: z2.enum(["team", "personal"]).optional()
+});
+var FabReviewOutputSchema = z2.discriminatedUnion("action", [
+  z2.object({
+    action: z2.literal("list"),
+    items: z2.array(_fabReviewListItemSchema),
+    warnings: z2.array(structuredWarningSchema).optional()
+  }),
+  z2.object({
+    action: z2.literal("approve"),
+    approved: z2.array(z2.object({ pending_path: z2.string(), stable_id: z2.string() })),
+    warnings: z2.array(structuredWarningSchema).optional()
+  }),
+  z2.object({
+    action: z2.literal("reject"),
+    rejected: z2.array(z2.string()),
+    warnings: z2.array(structuredWarningSchema).optional()
+  }),
+  z2.object({
+    action: z2.literal("modify"),
+    pending_path: z2.string(),
+    // When a layer-flip occurred, prior_stable_id and new_stable_id differ.
+    prior_stable_id: z2.string().optional(),
+    new_stable_id: z2.string().optional(),
+    warnings: z2.array(structuredWarningSchema).optional()
+  }),
+  z2.object({
+    action: z2.literal("search"),
+    items: z2.array(_fabReviewListItemSchema),
+    warnings: z2.array(structuredWarningSchema).optional()
+  }),
+  z2.object({
+    action: z2.literal("defer"),
+    deferred: z2.array(z2.string()),
+    warnings: z2.array(structuredWarningSchema).optional()
+  })
+]);
+var FabReviewOutputShape = {
+  action: z2.enum(["list", "approve", "reject", "modify", "search", "defer"]).describe(
+    "Echoes the input action; clients can switch on it for per-variant fields below."
+  ),
+  items: z2.array(_fabReviewListItemSchema).optional().describe(
+    "Pending/canonical entries surfaced. Present when action=list or action=search."
+  ),
+  approved: z2.array(z2.object({ pending_path: z2.string(), stable_id: z2.string() })).optional().describe(
+    "Allocated stable ids paired with their original pending paths. Present when action=approve."
+  ),
+  rejected: z2.array(z2.string()).optional().describe(
+    "Pending paths that were rejected (files retained on disk; doctor owns vacuum). Present when action=reject."
+  ),
+  pending_path: z2.string().optional().describe(
+    "Echoed target path for the modification. Present when action=modify."
+  ),
+  prior_stable_id: z2.string().optional().describe(
+    "Prior stable id. Present when action=modify AND a layer-flip reallocated the id."
+  ),
+  new_stable_id: z2.string().optional().describe(
+    "New stable id after reallocation. Present when action=modify AND a layer-flip reallocated the id."
+  ),
+  deferred: z2.array(z2.string()).optional().describe(
+    "Pending paths that were deferred (files retained on disk). Present when action=defer."
+  ),
+  // v2.0.0-rc.23 TASK-009 (d): optional warnings surface for the first-reconcile
+  // gate (`meta_stale` / `reconcile_failed`). Absent on the steady-state path.
+  warnings: z2.array(structuredWarningSchema).optional()
+};
+var fabReviewAnnotations = {
+  readOnlyHint: false,
+  idempotentHint: false,
+  destructiveHint: false,
+  openWorldHint: false,
+  title: "Review pending knowledge entries"
+};
+var ledgerSourceSchema = z2.enum(["ai", "human"]);
+var timestampFilterSchema = z2.preprocess((value) => {
+  if (value === void 0 || value === null || value === "") {
+    return void 0;
+  }
+  if (typeof value === "number") {
+    return value;
+  }
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+      return void 0;
+    }
+    if (/^\d+$/.test(trimmed)) {
+      return Number.parseInt(trimmed, 10);
+    }
+    const parsed = Date.parse(trimmed);
+    return Number.isNaN(parsed) ? value : parsed;
+  }
+  return value;
+}, z2.number().int().nonnegative());
+var ledgerQuerySchema = z2.object({
+  source: ledgerSourceSchema.optional(),
+  since: timestampFilterSchema.optional()
+});
+var historyStateQuerySchema = z2.object({
+  ledger_id: z2.string().trim().min(1).optional(),
+  ts: timestampFilterSchema.optional()
+}).superRefine((value, ctx) => {
+  const provided = [value.ledger_id, value.ts].filter((entry) => entry !== void 0);
+  if (provided.length !== 1) {
+    ctx.addIssue({
+      code: z2.ZodIssueCode.custom,
+      message: "Provide exactly one of ledger_id or ts.",
+      path: ["ledger_id"]
+    });
+  }
+});
+var humanLockApproveRequestSchema = z2.object({
+  file: z2.string().min(1),
+  start_line: z2.number().int().positive(),
+  end_line: z2.number().int().positive(),
+  new_hash: z2.string().min(1)
+});
+var humanLockFileParamsSchema = z2.object({
+  file: z2.string().min(1)
+});
+var annotateIntentRequestSchema = z2.object({
+  ledger_entry_id: z2.string().min(1),
+  annotation: z2.string().trim().min(1)
+});
+var KnowledgeTypeSchema = z2.enum([
+  "model",
+  // entities, data structures, relationships
+  "decision",
+  // architectural/technical choices with rationale
+  "guideline",
+  // recommended practices (recommend) or anti-patterns (avoid)
+  "pitfall",
+  // known risks, failure modes, troubleshooting
+  "process"
+  // workflows, state machines, operational steps
+]);
+var MaturitySchema = z2.enum(["draft", "verified", "proven"]);
+var LayerSchema = z2.enum(["personal", "team"]);
+var StableIdSchema = z2.string().regex(/^K[PT]-(MOD|DEC|GLD|PIT|PRO)-\d{4,}$/);
+var KnowledgeEntryFrontmatterSchema = z2.object({
+  id: StableIdSchema,
+  // e.g., "KT-DEC-0042"
+  type: KnowledgeTypeSchema,
+  // one of 5 types
+  maturity: MaturitySchema,
+  // draft | verified | proven
+  layer: LayerSchema,
+  // personal | team
+  layer_reason: z2.string().optional(),
+  // why this layer (for ambiguous cases)
+  created_at: z2.string()
+  // ISO 8601 timestamp
+  // Note: 'tags' and other fields can be added later but core schema is these 6
+});
+var KNOWLEDGE_TYPE_CODES = {
+  model: "MOD",
+  decision: "DEC",
+  guideline: "GLD",
+  pitfall: "PIT",
+  process: "PRO"
+};
+function formatKnowledgeId(layer, type, counter) {
+  const layerPrefix = layer === "personal" ? "KP" : "KT";
+  const typeCode = KNOWLEDGE_TYPE_CODES[type];
+  return `${layerPrefix}-${typeCode}-${String(counter).padStart(4, "0")}`;
+}
+function parseKnowledgeId(id) {
+  const match = id.match(/^(KP|KT)-(MOD|DEC|GLD|PIT|PRO)-(\d+)$/);
+  if (!match) return null;
+  const layer = match[1] === "KP" ? "personal" : "team";
+  const typeCode = match[2];
+  const entry = Object.entries(KNOWLEDGE_TYPE_CODES).find(([, code]) => code === typeCode);
+  if (!entry) return null;
+  const type = entry[0];
+  return { layer, type, counter: parseInt(match[3], 10) };
+}
+
+export {
+  ONBOARD_SLOT_NAMES,
+  onboardSlotSchema,
+  ONBOARD_SLOT_TOTAL,
+  structuredWarningSchema,
+  planContextInputSchema,
+  planContextOutputSchema,
+  planContextAnnotations,
+  planContextHintNarrowEntrySchema,
+  planContextHintOutputSchema,
+  knowledgeSectionsInputSchema,
+  knowledgeSectionsOutputSchema,
+  knowledgeSectionsAnnotations,
+  ProposedReasonSchema,
+  PROPOSED_REASON_DESCRIPTIONS,
+  FabExtractKnowledgeInputSchema,
+  FabExtractKnowledgeInputShape,
+  FabExtractKnowledgeOutputSchema,
+  fabExtractKnowledgeAnnotations,
+  FabReviewInputSchema,
+  FabReviewInputShape,
+  FabReviewOutputSchema,
+  FabReviewOutputShape,
+  fabReviewAnnotations,
+  ledgerSourceSchema,
+  ledgerQuerySchema,
+  historyStateQuerySchema,
+  humanLockApproveRequestSchema,
+  humanLockFileParamsSchema,
+  annotateIntentRequestSchema,
+  KnowledgeTypeSchema,
+  MaturitySchema,
+  LayerSchema,
+  StableIdSchema,
+  KnowledgeEntryFrontmatterSchema,
+  KNOWLEDGE_TYPE_CODES,
+  formatKnowledgeId,
+  parseKnowledgeId
+};