@fenglimg/fabric-shared 2.0.0-rc.30 → 2.0.0-rc.34

package/dist/index.js

@@ -1,12 +1,4 @@
-import {
-  BOOTSTRAP_CANONICAL,
-  BOOTSTRAP_MARKER_BEGIN,
-  BOOTSTRAP_MARKER_END,
-  BOOTSTRAP_REGEX,
-  LEGACY_KB_MARKER_BEGIN,
-  LEGACY_KB_MARKER_END,
-  LEGACY_KB_REGEX
-} from "./chunk-4OQXR6JW.js";
+import "./chunk-LXNCAKJZ.js";
 import {
   PROTECTED_TOKENS,
   createTranslator,
@@ -16,7 +8,7 @@ import {
   normalizeLocale,
   resolveFabricLocale,
   zhCNMessages
-} from "./chunk-225L7D4T.js";
+} from "./chunk-Z7UPW75I.js";
 import {
   FabExtractKnowledgeInputSchema,
   FabExtractKnowledgeInputShape,
@@ -59,11 +51,26 @@ import {
   planContextOutputSchema,
   structuredWarningSchema
 } from "./chunk-Y2YBFL2G.js";
-import "./chunk-LXNCAKJZ.js";
+import {
+  BOOTSTRAP_CANONICAL,
+  BOOTSTRAP_MARKER_BEGIN,
+  BOOTSTRAP_MARKER_END,
+  BOOTSTRAP_REGEX,
+  LEGACY_KB_MARKER_BEGIN,
+  LEGACY_KB_MARKER_END,
+  LEGACY_KB_REGEX
+} from "./chunk-4OQXR6JW.js";
 
 // src/schemas/agents-meta.ts
 import { z } from "zod";
 var FABRIC_AGENTS_PREFIX = ".fabric/agents/";
+var KNOWLEDGE_TYPE_SINGULAR_TO_PLURAL = {
+  model: "models",
+  decision: "decisions",
+  guideline: "guidelines",
+  pitfall: "pitfalls",
+  process: "processes"
+};
 var AGENTS_META_LAYERS = ["L0", "L1", "L2"];
 var AGENTS_META_TOPOLOGY_TYPES = ["mirror", "cross-cutting", "domain", "local", "global"];
 var AGENTS_META_IDENTITY_SOURCES = ["declared", "derived"];
@@ -79,7 +86,15 @@ var ruleDescriptionSchema = z.object({
   entities: z.array(z.string()).optional(),
   // v2.0 knowledge entry fields (TASK-002 schemas). All optional for backward compat.
   id: z.string().optional(),
-  knowledge_type: z.enum(["models", "decisions", "guidelines", "pitfalls", "processes"]).optional(),
+  // rc.31 NEW-1: forward-compat for legacy on-disk agents.meta.json carrying
+  // singular knowledge_type values (model/decision/guideline/pitfall/process).
+  // Normalize to canonical plural form before enum validation so doctor and
+  // plan-context-hint can load pre-rc.28 meta files without aborting. Disk
+  // gets rewritten to plural on next reconcile (via knowledge-meta-builder).
+  knowledge_type: z.preprocess(
+    (value) => typeof value === "string" && value in KNOWLEDGE_TYPE_SINGULAR_TO_PLURAL ? KNOWLEDGE_TYPE_SINGULAR_TO_PLURAL[value] : value,
+    z.enum(["models", "decisions", "guidelines", "pitfalls", "processes"])
+  ).optional(),
   maturity: z.enum(["draft", "verified", "proven"]).optional(),
   knowledge_layer: z.enum(["personal", "team"]).optional(),
   layer_reason: z.string().optional(),
@@ -455,6 +470,25 @@ var fabricConfigSchema = z5.object({
   // 7d Signal-B trigger because review specifically targets the long
   // tail. Large repos with slower cadence can raise to 30.
   review_stale_pending_days: z5.number().int().positive().optional().default(14),
+  // v2.0.0-rc.34 TASK-05: reverse-unarchive opt-in. When true, callers of the
+  // `unarchiveKnowledge` primitive (and any future doctor auto-detect lint built
+  // on top) will execute the file move + ledger emit. When false (default),
+  // the same callers MUST short-circuit before any mutation — the primitive is
+  // shipped but inert until explicitly enabled. Opt-in posture mirrors the
+  // archive-flow precedent: destructive-ish file moves stay behind a flag.
+  reverse_unarchive_enabled: z5.boolean().optional().default(false),
+  // v2.0.0-rc.34 TASK-05: forces `unarchiveKnowledge` into dry-run mode even
+  // when called with `options.dryRun=false`. Lets operators preview a
+  // restoration pass before flipping `reverse_unarchive_enabled` to true.
+  reverse_unarchive_dry_run: z5.boolean().optional().default(false),
+  // v2.0.0-rc.34 TASK-06: long-session cite-policy evict window in user-prompt
+  // turns. UserPromptSubmit hook (Claude Code only) maintains a per-session
+  // counter and re-injects the cite contract reminder via
+  // hookSpecificOutput.additionalContext when `turn_count % interval === 0`.
+  // Default 0 = OFF (opt-in). Recommend 10-20 for active sessions; 5 for
+  // high-contract-criticality projects. Other strategies (time-based,
+  // token-budget) deferred to rc.35 per plan locked-decisions 2026-05-26.
+  cite_evict_interval: z5.number().int().min(0).optional().default(0),
   // v2.0.0-rc.22 Scope A T3: sliding-window retention (in days) for the
   // event ledger rotation primitive (`rotateEventLedgerIfNeeded`). Lines
   // whose `ts` is older than `now - fabric_event_retention_days * 86_400_000`
@@ -485,6 +519,76 @@ var fabricConfigSchema = z5.object({
   // Default `[]` keeps the field optional on existing configs — fresh
   // installs land with no opt-outs.
   onboard_slots_opted_out: z5.array(z5.string()).optional().default([]),
+  // v2.0.0-rc.33 W2-1 (P0-9): TopK upper bound for the broad SessionStart hint
+  // banner emitted by knowledge-hint-broad.cjs. After plan-context-hint returns
+  // its full broad-scoped index, the hook slices the entries to this many
+  // before grouping/truncation rendering — keeps the banner from scrolling off
+  // screen on well-seeded repos (Werewolf-class projects routinely surface 40+
+  // broad entries which buried the actually-relevant top hits). Default 8 is
+  // calibrated against the rc.32 eval baseline (cite-coverage 3.1%): the
+  // banner needs to fit in ~1 screenful so the agent actually reads it.
+  // Range 1..50; values above 20 effectively disable the cap because the
+  // TRUNCATION_THRESHOLD=12 grouped-render kicks in. Mirrors the rc.7 T7 +
+  // archive_max_* pattern of externalizing previously-hardcoded thresholds.
+  hint_broad_top_k: z5.number().int().min(1).max(50).optional().default(8),
+  // v2.0.0-rc.33 W2-1 (P0-9): TopK upper bound for the narrow PreToolUse hint
+  // emitted by knowledge-hint-narrow.cjs. After filtering to entries whose
+  // `relevance_scope === "narrow"` (rc.27 TASK-005 audit §2.5 fix), the hook
+  // slices to this many before the E3 emit-gate / renderSummary pipeline.
+  // Default 5 keeps each per-Edit hint terse — five lines max so the agent's
+  // working memory is not displaced by an unwieldy banner. Range 1..20.
+  hint_narrow_top_k: z5.number().int().min(1).max(20).optional().default(5),
+  // v2.0.0-rc.33 W2-1 (P0-9): per-file dedup window (in PreToolUse turns) for
+  // the narrow hint. Same (file_path, stable_id) tuple stays silent for this
+  // many turns even when the E3 cross-session cache would otherwise re-emit.
+  // Closes the rc.32 eval finding that a single hot file (e.g. werewolf
+  // GameRoom.tsx edited 30 times in a row) re-fired the same narrow hint
+  // each time, training the agent to ignore it. Default 5; range 1..50.
+  // Storage: .fabric/.cache/narrow-dedup-window.json — distinct from session-
+  // hints cache so a window-only suppression does not poison cross-session
+  // dedupe semantics.
+  hint_narrow_dedup_window_turns: z5.number().int().min(1).max(50).optional().default(5),
+  // v2.0.0-rc.33 W2-5 (P1-8): cooldown between broad SessionStart hint emits,
+  // in hours. Distinct from the archive_hint_cooldown_hours that gates the
+  // fabric-hint Stop hook — knowledge-hint-broad re-fires on every
+  // SessionStart by default (compact / clear / new-window), which on long
+  // sessions becomes redundant noise. Setting to 1 means "emit the broad
+  // menu at most once per hour"; 0 means "no cooldown, current behavior."
+  // Range 0..168 (one week). Stored alongside fabric-hint's cooldown cache
+  // under a distinct knowledge-hint-broad key.
+  hint_broad_cooldown_hours: z5.number().int().min(0).max(168).optional().default(0),
+  // v2.0.0-rc.33 W2-5 (P1-8): cooldown for the narrow PreToolUse hint.
+  // Same shape as hint_broad_cooldown_hours but applies to per-Edit hint
+  // re-emission across the cooldown window — independent of E3 session-
+  // hints dedupe. Default 0 preserves rc.32 behavior; set to e.g. 1 to
+  // throttle hint frequency during rapid-fire editing sprints. Range
+  // 0..168 (one week).
+  hint_narrow_cooldown_hours: z5.number().int().min(0).max(168).optional().default(0),
+  // v2.0.0-rc.33 W4-B3 (T5 P2): per-maturity inactivity thresholds (days)
+  // driving orphan_demote. Hardcoded at stable=90/endorsed=30/draft=14 in
+  // rc.32; chatty workspaces want them tighter, slow ones want them looser.
+  // Each field optional; absent → defaults inside doctor.ts apply. Ranges
+  // chosen so a typo can't accidentally disable the lint (min 1).
+  orphan_demote_stable_days: z5.number().int().min(1).max(3650).optional(),
+  orphan_demote_endorsed_days: z5.number().int().min(1).max(3650).optional(),
+  orphan_demote_draft_days: z5.number().int().min(1).max(3650).optional(),
+  // v2.0.0-rc.33 W4-A3 (T4 P2): per-entry summary truncation length used by
+  // knowledge-hint-{broad,narrow}.cjs. Hard-coded at 80 chars in rc.32 — too
+  // short for entries with parameterized summaries (e.g. "Use bcrypt with
+  // cost=12 for password hashing"), too long for terse pitfalls. Range 40..240;
+  // default 80 preserves rc.32 behavior. Both hooks read the same key so the
+  // banner styling stays consistent across SessionStart + PreToolUse.
+  hint_summary_max_len: z5.number().int().min(40).max(240).optional().default(80),
+  // v2.0.0-rc.33 W2-6 (P0-7 + P0-8): when true, knowledge-hint hooks emit
+  // their banners as `hookSpecificOutput.additionalContext` JSON on stdout
+  // (per Claude Code PreToolUse hook contract — see
+  // https://docs.claude.com/en/docs/claude-code/hooks#preToolUse), so the
+  // agent receives them in-context instead of as stderr breadcrumbs the
+  // user may not surface to the model. Default true reflects the rc.33 cite-
+  // coverage focus (rc.32 baseline 3.1% → primary cause: reminders never
+  // entered model context). Set false to revert to legacy stderr-only mode
+  // for hosts that don't honor the JSON contract.
+  hint_reminder_to_context: z5.boolean().optional().default(true),
   // v2.0.0-rc.29 TASK-008 (BUG-F3): selection-token TTL override. The
   // `fab_plan_context` MCP tool hands clients a `selection_token` whose default
   // 5-minute lifetime (`SELECTION_TOKEN_TTL_MS` at
@@ -1052,6 +1156,17 @@ var knowledgeArchiveAttemptedEventSchema = z10.object({
   timestamp: z10.string().datetime(),
   reason: z10.string().optional()
 });
+var knowledgeUnarchivedEventSchema = z10.object({
+  ...eventLedgerEnvelopeSchema,
+  event_type: z10.literal("knowledge_unarchived"),
+  stable_id: z10.string().optional(),
+  timestamp: z10.string().datetime(),
+  reason: z10.string().optional(),
+  // Pre-move archive path (e.g. ".fabric/.archive/decisions/KT-D-0007--single-cjs-hook.md").
+  archive_path: z10.string().optional(),
+  // Post-move canonical path (e.g. ".fabric/knowledge/team/decisions/KT-D-0007--single-cjs-hook.md").
+  restored_to: z10.string().optional()
+});
 var knowledgeDeferredEventSchema = z10.object({
   ...eventLedgerEnvelopeSchema,
   event_type: z10.literal("knowledge_deferred"),
@@ -1219,6 +1334,8 @@ var eventLedgerEventSchema = z10.discriminatedUnion("event_type", [
   knowledgeDemotedEventSchema,
   knowledgeArchivedEventSchema,
   knowledgeArchiveAttemptedEventSchema,
+  // v2.0.0-rc.34 TASK-05: reverse of knowledge_archived
+  knowledgeUnarchivedEventSchema,
   knowledgeDeferredEventSchema,
   knowledgeRejectedEventSchema,
   // v2.0 rc.5 TASK-014: knowledge_consumed (consumption tracking)
@@ -1488,6 +1605,7 @@ export {
   knowledgeTestIndexSchema,
   knowledgeTestLinkSchema,
   knowledgeTestOrphanAnnotationSchema,
+  knowledgeUnarchivedEventSchema,
   ledgerAppendedEventSchema,
   ledgerEntrySchema,
   ledgerQuerySchema,

package/dist/types/index.d.ts

@@ -1,2 +1,2 @@
-export { e as AgentsActivationTier, a as AgentsIdentitySource, b as AgentsLayer, d as AgentsMeta, g as AgentsMetaCountersEnvelope, h as AgentsMetaKnowledgeTypeCounters, A as AgentsMetaNode, i as AgentsMetaNodeActivation, c as AgentsTopologyType, j as AiLedgerEntry, k as AuditMode, C as ClientPaths, D as DefaultLayerFilter, F as FabricConfig, l as FabricLanguage, m as HumanLedgerEntry, H as HumanLockEntry, L as LedgerEntry, M as McpPayloadLimits, R as RuleDescription, n as RuleDescriptionIndexItem } from '../index-DkXJGQCD.js';
+export { e as AgentsActivationTier, a as AgentsIdentitySource, b as AgentsLayer, d as AgentsMeta, g as AgentsMetaCountersEnvelope, h as AgentsMetaKnowledgeTypeCounters, A as AgentsMetaNode, i as AgentsMetaNodeActivation, c as AgentsTopologyType, j as AiLedgerEntry, k as AuditMode, C as ClientPaths, D as DefaultLayerFilter, F as FabricConfig, l as FabricLanguage, m as HumanLedgerEntry, H as HumanLockEntry, L as LedgerEntry, M as McpPayloadLimits, R as RuleDescription, n as RuleDescriptionIndexItem } from '../index-BjssYQb3.js';
 import 'zod';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fenglimg/fabric-shared",
-  "version": "2.0.0-rc.30",
+  "version": "2.0.0-rc.34",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",