@fenglimg/fabric-shared 2.0.0 → 2.1.0-rc.2

package/dist/chunk-WVPDH4BF.js

@@ -0,0 +1,952 @@
+// 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(["models", "decisions", "guidelines", "pitfalls", "processes"]);
+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(),
+  // 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,
+  // `description` becomes their canonical (and only) home, so the schema must
+  // validate them here. Optional + default-safe (tags/[]/broad) so legacy
+  // entries without frontmatter still parse.
+  tags: z2.array(z2.string()).optional(),
+  relevance_scope: z2.enum(["narrow", "broad"]).optional(),
+  relevance_paths: z2.array(z2.string()).optional()
+});
+var _descriptionIndexItemSchema = z2.object({
+  stable_id: z2.string(),
+  description: _ruleDescriptionSchema
+});
+var _requirementProfileSchema = z2.object({
+  target_path: 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(
+    "Recommended: pass the current client session id (Claude Code: $session_id; Codex: corresponding identifier) \u2014 enables cross-session debt tracking in fabric doctor and accurate archive-hint cross-session count. Falls back gracefully if omitted."
+  ),
+  // 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 _preflightDiagnosticSchema = z2.object({
+  // v2.0.0-rc.38 UX-2: `empty_shell_suppressed` surfaces draft entries whose
+  // description carries no selection signal (summary === stable_id + empty
+  // intent_clues/tech_stack/impact). They are filtered out of `candidates` to
+  // cut noise; this diagnostic names them so `fabric doctor` /
+  // --enrich-descriptions can prompt enrichment.
+  code: z2.enum(["missing_description", "empty_shell_suppressed"]),
+  severity: z2.literal("warn"),
+  message: z2.string(),
+  stable_ids: z2.array(z2.string()).optional(),
+  path: z2.string().optional()
+});
+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
+    })
+  ),
+  candidates: z2.array(_descriptionIndexItemSchema),
+  preflight_diagnostics: z2.array(_preflightDiagnosticSchema),
+  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(),
+  // v2.0.0-rc.37 NEW-24: stale-id redirect map. Populated when one or more
+  // recent fab_review modify-layer flips reassigned a canonical stable_id
+  // and the NEW id is in this response's description_index. Callers that
+  // cached the OLD id from a prior session look it up here and substitute
+  // the new id before issuing fab_get_knowledge_sections / fab_recall. Empty
+  // (field omitted) when no actionable redirects exist for the surfaced
+  // candidate set. See packages/server/src/services/id-redirect.ts.
+  redirects: z2.record(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 candidates[].stable_id; 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(),
+  // v2.0.0-rc.38 UX-13 (D-MCP step-2 audit): the deprecated `precedence`
+  // L2/L1/L0 tuple (flagged "removed in rc.24" but still emitted) is gone — it
+  // was a constant 3-string field on every response read by no production
+  // consumer. Use rules[].level for ordering.
+  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) + v2.0.0-rc.37 NEW-24: present iff at least one stable_id in
+  // the caller-supplied ai_selected_stable_ids was rewritten by the layer-flip
+  // redirect resolver. Pre-rc.37: this was a single { stable_id } object set
+  // only on the rare token-mint-vs-flip race. rc.37+: also accepts a map of
+  // (old_id → new_id) when multiple rewrites fire in one fetch. Both shapes
+  // are accepted for forward-compat; readers should branch on shape and
+  // refresh their cached ids accordingly.
+  redirect_to: z2.union([
+    z2.object({ stable_id: z2.string() }),
+    z2.record(z2.string())
+  ]).optional().describe(
+    "Post-layer-flip redirect. Pre-rc.37: { stable_id } shape from rc.3 fab_review/modify. rc.37+: also accepts a (old_id \u2192 new_id) map for fab_get_knowledge_sections / fab_recall transparent rewrite."
+  ),
+  warnings: z2.array(structuredWarningSchema).optional()
+});
+var knowledgeSectionsAnnotations = {
+  readOnlyHint: true,
+  idempotentHint: true,
+  destructiveHint: false,
+  openWorldHint: false,
+  title: "Filter rule sections"
+};
+var recallInputSchema = z2.object({
+  paths: z2.array(z2.string()).min(1).describe(
+    "Candidate file paths to recall Fabric rules for. Same semantics as fab_plan_context.paths."
+  ),
+  intent: z2.string().optional().describe("User-stated requirement or implementation intent; used to build a neutral requirement profile."),
+  known_tech: z2.array(z2.string()).optional().describe("Known technologies involved."),
+  detected_entities: z2.record(z2.array(z2.string())).optional().describe("Optional path-keyed detected entities."),
+  client_hash: z2.string().optional().describe("Revision hash from a prior call; enables stale detection."),
+  correlation_id: z2.string().optional().describe("Optional caller-provided correlation id for Event Ledger records."),
+  session_id: z2.string().optional().describe(
+    "Current client session id (Claude Code: $session_id; Codex: corresponding identifier). Enables cross-session debt tracking. Falls back gracefully if omitted."
+  ),
+  layer_filter: z2.enum(["team", "personal", "both"]).optional().describe(
+    "Restrict recall to the named layer. Default: fabric-config.default_layer_filter."
+  ),
+  target_paths: z2.array(z2.string()).optional().describe(
+    "Path context for narrow-scope relevance filtering. Defaults to `paths`; empty = no filter."
+  ),
+  ids: z2.array(z2.string()).optional().describe(
+    "Optional explicit stable_ids to fetch. When omitted, fab_recall returns ALL entries plan-context surfaces (the common case after rc.37 selectable-filter removal). When provided, filters fetched bodies to this set."
+  )
+});
+var recallOutputSchema = z2.object({
+  revision_hash: z2.string(),
+  stale: z2.boolean(),
+  // Selection token surfaced for callers who want to continue the conversation
+  // with fab_get_knowledge_sections (e.g. fetch additional ids later) — every
+  // recall response is still token-backed internally.
+  selection_token: z2.string(),
+  // 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: z2.array(
+    z2.object({
+      path: z2.string(),
+      requirement_profile: _requirementProfileSchema
+    })
+  ),
+  candidates: z2.array(_descriptionIndexItemSchema),
+  preflight_diagnostics: z2.array(_preflightDiagnosticSchema),
+  // Same shape as knowledgeSectionsOutputSchema.rules — full body keyed by stable_id.
+  rules: z2.array(
+    z2.object({
+      stable_id: z2.string(),
+      level: z2.enum(["L0", "L1", "L2"]),
+      path: z2.string(),
+      body: z2.string()
+    })
+  ),
+  selected_stable_ids: z2.array(z2.string()),
+  diagnostics: z2.array(
+    z2.object({
+      code: z2.literal("missing_knowledge_metadata"),
+      severity: z2.literal("warn"),
+      stable_id: z2.string(),
+      message: z2.string()
+    })
+  ),
+  warnings: z2.array(structuredWarningSchema).optional(),
+  auto_healed: z2.boolean().optional(),
+  previous_revision_hash: z2.string().optional(),
+  // v2.0.0-rc.37 NEW-24: parallel to planContextOutputSchema.redirects — see
+  // that field for semantics. fab_recall transparently rewrites any old ids
+  // passed via `ids` before fetching bodies; the surfaced map still exposes
+  // the substitution to callers that want to refresh their cached state.
+  redirects: z2.record(z2.string()).optional()
+});
+var recallAnnotations = {
+  readOnlyHint: true,
+  idempotentHint: true,
+  destructiveHint: false,
+  openWorldHint: false,
+  title: "Recall Fabric knowledge (one-call)"
+};
+var archiveScanInputSchema = z2.object({
+  range: z2.union([z2.array(z2.string()).min(1), z2.literal("all")]).optional().describe(
+    "Phase 0 scope: explicit session_id[] to constrain the scan, or the 'all' sentinel. Omitted = scan everything since the last knowledge_proposed anchor."
+  ),
+  now_ms: z2.number().int().nonnegative().optional().describe("Override for the anti-loop cooldown clock (testing). Defaults to Date.now()."),
+  correlation_id: z2.string().optional().describe("Optional caller-provided correlation id for Event Ledger records."),
+  session_id: z2.string().optional().describe("Current client session id; recorded for cross-session debt tracking.")
+});
+var archiveScanOutputSchema = z2.object({
+  // ts of the most recent knowledge_proposed event (the lower bound), or null
+  // when the workspace has never archived (scan everything).
+  anchor_ts: z2.number().nullable(),
+  // Distinct session_ids since the anchor that survived the outcome filter,
+  // in first-seen order — ready for the Skill to load digests + stitch.
+  session_ids: z2.array(z2.string()),
+  // Sessions dropped by the filter, with the rule that fired (audit/debug).
+  dropped: z2.array(
+    z2.object({
+      session_id: z2.string(),
+      reason: z2.enum(["user_dismissed", "cooldown", "no_new_signal"])
+    })
+  ),
+  // max ts examined across the scan — becomes the next covered_through_ts.
+  covered_through_ts: z2.number().nullable(),
+  // Idempotency keys already proposed by prior archive runs but not yet
+  // reviewed (Phase 4.5 cross-session pending dedupe). Drop matching candidates.
+  already_proposed_keys: z2.array(z2.string()),
+  warnings: z2.array(structuredWarningSchema).optional()
+});
+var archiveScanAnnotations = {
+  readOnlyHint: true,
+  idempotentHint: true,
+  destructiveHint: false,
+  openWorldHint: false,
+  title: "Scan event ledger for archive candidates (deterministic)"
+};
+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.37 NEW-37 (werewolf dogfood remediation): optional tags array.
+  // Werewolf实测发现 100% canonical entries 的 `tags: []` 为空,主题聚类与
+  // 跨条目检索退化。Skills (fabric-archive / fabric-import) 应每个 entry 产
+  // 2-4 个 kebab-case 主题词。Server 写入时直接落 frontmatter `tags: [...]`;
+  // empty array 仍然合法(skill 无法 confident 推断时显式空)。
+  // IDEMPOTENCY: tags MUST NOT 参与 idempotency_key hash(同 relevance_*
+  // / intent_clues 等可变字段一致),re-extract 时 tags 调整不应产生重复
+  // pending file。
+  tags: z2.array(z2.string()).optional().describe(
+    "Optional topic tags (2-4 kebab-case strings recommended). Drives cross-entry retrieval + topic clustering. Skill-inferred from session content; omit when not confidently inferable. Empty array allowed but discouraged (degrades narrow hint topic signal)."
+  ),
+  // 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-`fabric scan` baseline pipeline.
+  // fabric-archive's first-run phase reads `fabric 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."
+  ),
+  // v2.0.0-rc.37 NEW-7: read-only evidence paths lifted from the legacy
+  // body `## Evidence` markdown block into structured frontmatter. These are
+  // paths the agent CONSULTED while building this knowledge but never
+  // modified — they document context without participating in the
+  // activation gate (relevance_paths does that). Splitting evidence into a
+  // first-class frontmatter array lets future plan-context retrieval read
+  // it as data (intersect with current paths to surface high-recall hits)
+  // instead of re-parsing markdown. Optional; omit when no read-only
+  // signal was captured. Like relevance_paths it MUST NOT participate in
+  // the idempotency_key hash (an idempotent re-extract may surface a
+  // slightly different read set without spawning a duplicate pending).
+  evidence_paths: z2.array(z2.string()).optional().describe(
+    "Workspace-relative paths the agent CONSULTED (read but never modified) while building this knowledge. Documents context without affecting activation. Lifted from the legacy body ## Evidence markdown block into structured frontmatter so plan-context retrieval can read it as data."
+  )
+});
+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(),
+  // v2.0.0-rc.27 TASK-001 (§2.2/§2.3): opt-in surfacing of lifecycle-filtered
+  // entries. Default (omit both) hides rejected entries and deferred entries
+  // whose deferred_until is in the future. Pass true to include them — e.g.
+  // for vacuum tooling, audit dashboards, or "show me what I parked" UX.
+  include_rejected: z2.boolean().optional(),
+  include_deferred: z2.boolean().optional(),
+  // v2.0.0-rc.27 TASK-006 (audit §2.23): opt-in body inspection. Default
+  // list/search return only frontmatter-derived fields — a malicious
+  // pending entry could hide a prompt-injection payload under `## Evidence`
+  // body content that frontmatter inspection never surfaces. Setting
+  // `include_body: true` attaches the full post-frontmatter content to
+  // each item, and (for search) extends the haystack to body text. The
+  // default-off design keeps the wire payload small for routine list
+  // calls; reviewer workflows pass `true` before approving so the body
+  // is rendered into the reviewer's UI for visual scan.
+  include_body: z2.boolean().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
+  }),
+  // v2.0.0-rc.37 NEW-12: explicit modify split. `modify-content` edits scalar
+  // frontmatter/body fields (title/summary/maturity/tags/relevance_*) and MUST
+  // NOT carry a layer change. `modify-layer` is the dedicated layer-flip path
+  // (changes.layer REQUIRED) which may reallocate the stable_id + emit an
+  // id-redirect (rc.37 NEW-24). Legacy `modify` stays for back-compat and
+  // routes by whether changes.layer is present.
+  z2.object({
+    action: z2.literal("modify-content"),
+    pending_path: z2.string().min(1),
+    changes: _fabReviewModifyChangesSchema
+  }),
+  z2.object({
+    action: z2.literal("modify-layer"),
+    pending_path: z2.string().min(1),
+    changes: _fabReviewModifyChangesSchema.extend({
+      layer: z2.enum(["team", "personal"])
+    })
+  }),
+  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", "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."
+  ),
+  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(),
+  // v2.0.0-rc.27 TASK-001 (§2.12): for personal-layer entries `pending_path`
+  // carries the human-friendly `~/...` form (legacy contract) while
+  // `pending_path_absolute` carries the os-expanded absolute path. Programmatic
+  // consumers (Read tool, fs.readFile, downstream MCP servers) should prefer
+  // the absolute variant — the `~` is a shell-only sigil that breaks every
+  // non-shell consumer. Team entries omit this field because their
+  // `pending_path` is already project-relative and unambiguous.
+  pending_path_absolute: z2.string().optional(),
+  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(),
+  // v2.0.0-rc.27 TASK-001 (§2.2/§2.3): frontmatter status markers. Default
+  // "active" (or absent). `rejected` entries are excluded from list/search
+  // unless filters.include_rejected=true; `deferred` entries are excluded
+  // when deferred_until is in the future. Authored by reject/defer write
+  // paths — never by extract or approve.
+  status: z2.enum(["active", "rejected", "deferred"]).optional(),
+  deferred_until: z2.string().datetime().optional(),
+  // v2.0.0-rc.27 TASK-006 (audit §2.23): full body content (everything
+  // after the closing `---` of frontmatter). Surfaced only when caller
+  // passes `filters.include_body: true`. Default-omitted to keep payload
+  // small for routine list calls.
+  body: z2.string().optional()
+});
+var _fabReviewSearchItemSchema = z2.object({
+  // Search hits live in one of two trees:
+  //  - "pending"   → .fabric/knowledge/pending/ (or ~/.fabric/knowledge/pending/)
+  //  - "canonical" → .fabric/knowledge/{decisions,pitfalls,...} (or personal mirror)
+  area: z2.enum(["pending", "canonical"]),
+  path: z2.string(),
+  path_absolute: z2.string().optional(),
+  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(),
+  origin: z2.enum(["team", "personal"]).optional(),
+  status: z2.enum(["active", "rejected", "deferred"]).optional(),
+  deferred_until: z2.string().datetime().optional(),
+  body: z2.string().optional(),
+  // For pending hits the upstream stable_id may still be unassigned — keep it
+  // optional so canonical hits (which always have one) parse alongside pending
+  // hits in the same array.
+  stable_id: z2.string().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"),
+    // v2.0.0-rc.29 TASK-007 (BUG-M4): search returns the new search-item
+    // shape with `area` discriminator + neutrally-named `path` field.
+    items: z2.array(_fabReviewSearchItemSchema),
+    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(z2.union([_fabReviewListItemSchema, _fabReviewSearchItemSchema])).optional().describe(
+    "Pending entries (action=list, `pending_path` shape) or pending+canonical entries (action=search, `area`+`path` shape)."
+  ),
+  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 citeContractMetricsSchema = z2.object({
+  decisions_cited: z2.number().int().nonnegative(),
+  pitfalls_cited: z2.number().int().nonnegative(),
+  contract_with: z2.number().int().nonnegative(),
+  contract_missing: z2.number().int().nonnegative(),
+  hard_violated: z2.number().int().nonnegative(),
+  cite_id_unresolved: z2.number().int().nonnegative(),
+  skip_count: z2.record(z2.string(), z2.number().int().nonnegative())
+});
+var citeLayerTypeBreakdownSchema = z2.object({
+  team: z2.record(z2.string(), z2.number().int().nonnegative()),
+  personal: z2.record(z2.string(), z2.number().int().nonnegative())
+});
+var citeCoverageReportSchema = z2.object({
+  status: z2.enum(["ok", "skipped"]),
+  marker_ts: z2.number().int().nonnegative(),
+  marker_emitted_now: z2.boolean(),
+  since_ts: z2.number().int().nonnegative(),
+  client_filter: z2.enum(["cc", "codex", "cursor", "all"]),
+  // v2.0.0-rc.24 TASK-08: layer filter discriminator. Optional so pre-TASK-10
+  // CLI callers (which never set the flag) still parse. Defaults to "all" at
+  // the service layer.
+  layer_filter: z2.enum(["team", "personal", "all"]).optional(),
+  metrics: z2.object({
+    edits_touched: z2.number().int().nonnegative(),
+    qualifying_cites: z2.number().int().nonnegative(),
+    recalled_unverified: z2.number().int().nonnegative(),
+    expected_but_missed: z2.number().int().nonnegative(),
+    total_turns: z2.number().int().nonnegative(),
+    // v2.0.0-rc.38 UX-8 (C, user-authorized): cite-policy COMPLIANCE rate —
+    // the corrected G-CITE semantic. The legacy qualifying_cites/edits ratio
+    // measured "how often an applicable KB id existed" (a function of corpus
+    // density / soak), NOT "did the AI follow the cite policy". Compliance
+    // credits every valid cite line — `KB: <id> [applied|dismissed]` AND
+    // `KB: none [reason]` (the policy explicitly allows the none sentinel) —
+    // over the turns where a cite was expected. null when no cite-expected
+    // turns observed (avoids a misleading 0/0 → 0). Range [0,1].
+    cite_compliance_rate: z2.number().min(0).max(1).nullable().optional(),
+    compliant_cites: z2.number().int().nonnegative().optional(),
+    noncompliant_cites: z2.number().int().nonnegative().optional(),
+    // Edit signals lacking session_id → uncorrelatable, silently excluded from
+    // expected_but_missed. >0 typically means a stale pre-session_id hook is
+    // installed (run `fabric install`). Surfaced so the denominator gap is
+    // visible rather than a silent 100% confound.
+    uncorrelatable_edits: z2.number().int().nonnegative().optional()
+  }),
+  per_client: z2.record(
+    z2.string(),
+    z2.object({
+      edits_touched: z2.number().int().nonnegative().optional(),
+      qualifying_cites: z2.number().int().nonnegative().optional(),
+      recalled_unverified: z2.number().int().nonnegative().optional(),
+      expected_but_missed: z2.number().int().nonnegative().optional(),
+      total_turns: z2.number().int().nonnegative().optional()
+    })
+  ).optional(),
+  dismissed_reason_histogram: z2.record(z2.string(), z2.number().int().nonnegative()).optional(),
+  none_reason_histogram: z2.record(z2.string(), z2.number().int().nonnegative()).optional(),
+  // v2.0.0-rc.24 TASK-08: contract-policy audit metrics. Status discriminates
+  // populated vs degraded modes. contract_metrics + per_layer_type are emitted
+  // (zeroed) in degraded modes so the renderer iterates one stable shape.
+  contract_metrics_status: z2.enum(["ok", "skipped:bootstrap_drift", "awaiting_marker"]).optional(),
+  contract_metrics: citeContractMetricsSchema.optional(),
+  per_layer_type: citeLayerTypeBreakdownSchema.optional(),
+  contract_marker_ts: z2.number().int().nonnegative().optional(),
+  generated_at: z2.string()
+});
+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([
+  "models",
+  // entities, data structures, relationships
+  "decisions",
+  // architectural/technical choices with rationale
+  "guidelines",
+  // recommended practices (recommend) or anti-patterns (avoid)
+  "pitfalls",
+  // known risks, failure modes, troubleshooting
+  "processes"
+  // 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 = {
+  models: "MOD",
+  decisions: "DEC",
+  guidelines: "GLD",
+  pitfalls: "PIT",
+  processes: "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,
+  recallInputSchema,
+  recallOutputSchema,
+  recallAnnotations,
+  archiveScanInputSchema,
+  archiveScanOutputSchema,
+  archiveScanAnnotations,
+  ProposedReasonSchema,
+  PROPOSED_REASON_DESCRIPTIONS,
+  FabExtractKnowledgeInputSchema,
+  FabExtractKnowledgeInputShape,
+  FabExtractKnowledgeOutputSchema,
+  fabExtractKnowledgeAnnotations,
+  FabReviewInputSchema,
+  FabReviewInputShape,
+  FabReviewOutputSchema,
+  FabReviewOutputShape,
+  fabReviewAnnotations,
+  citeContractMetricsSchema,
+  citeLayerTypeBreakdownSchema,
+  citeCoverageReportSchema,
+  ledgerSourceSchema,
+  ledgerQuerySchema,
+  historyStateQuerySchema,
+  humanLockApproveRequestSchema,
+  humanLockFileParamsSchema,
+  annotateIntentRequestSchema,
+  KnowledgeTypeSchema,
+  MaturitySchema,
+  LayerSchema,
+  StableIdSchema,
+  KnowledgeEntryFrontmatterSchema,
+  KNOWLEDGE_TYPE_CODES,
+  formatKnowledgeId,
+  parseKnowledgeId
+};