@fenglimg/fabric-shared 2.2.0-rc.9 → 2.3.0-rc.1

package/dist/{chunk-5AKCRBKJ.js → chunk-D7HUHWBI.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"
@@ -129,6 +130,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 +145,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
@@ -293,39 +299,40 @@ 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()
+});
 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 +373,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 +437,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 +475,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 +530,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.
@@ -627,10 +645,6 @@ var _fabReviewModifyChangesSchema = z3.object({
   related: 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 +677,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 +684,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 +722,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 +782,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 +801,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 +860,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(),
@@ -1071,6 +1109,7 @@ export {
   PERSONAL_SCOPE,
   KNOWN_SCOPE_PREFIXES,
   SCOPE_COORDINATE_PATTERN,
+  SCOPE_COORDINATE_HINT,
   scopeCoordinateSchema,
   scopeRoot,
   isPersonalScope,
@@ -1097,10 +1136,15 @@ export {
   FabExtractKnowledgeOutputSchema,
   fabExtractKnowledgeAnnotations,
   FabReviewInputSchema,
+  FabPendingInputSchema,
+  FabPendingInputShape,
   FabReviewInputShape,
   FabReviewOutputSchema,
+  FabPendingOutputSchema,
+  FabPendingOutputShape,
   FabReviewOutputShape,
   fabReviewAnnotations,
+  fabPendingAnnotations,
   citeContractMetricsSchema,
   citeLayerTypeBreakdownSchema,
   citeCoverageReportSchema,