@saasontools/strauss-kb 0.1.2 → 0.1.4

package/dist/index.d.cts

@@ -334,6 +334,12 @@ type KbWriteInput = {
     /** Replace an existing record rather than failing on the collision. */
     overwrite?: boolean;
 };
+type KbWriteResult = KbRecord & {
+    /** Whether this write also marked prior records superseded. */
+    action: "created" | "superseded-prior";
+    /** `frontmatter.strauss_supersedes` ids that were actually marked. */
+    supersededIds: string[];
+};
 /**
  * Reads and writes a knowledge bundle.
  *
@@ -357,7 +363,7 @@ declare class KbStore {
      * concept id, so a caller cannot produce a file whose identity disagrees with
      * its contents.
      */
-    write(bundlePath: string, input: KbWriteInput, actor?: string): Promise<KbRecord>;
+    write(bundlePath: string, input: KbWriteInput, actor?: string): Promise<KbWriteResult>;
     /** One record by concept id, or null when it does not exist. */
     read(bundlePath: string, conceptId: string): Promise<KbRecord | null>;
     /**
@@ -447,6 +453,19 @@ declare class KbStore {
      * knows which agent touched what. So a bad line is surfaced and left alone.
      */
     readLog(bundlePath: string): Promise<ReturnType<typeof parseLog>>;
+    /**
+     * `markSuperseded`, tolerant of the two ways it legitimately doesn't land:
+     * a missing target (a broken link, legal per compose.ts) or a CAS conflict
+     * from a concurrent writer touching the same target. A conflict is retried
+     * a bounded number of times — each attempt re-reads the target fresh — and
+     * on the last, `false` reports "not marked" rather than throwing: the
+     * caller's own record is already published, so failing here would leave
+     * that publish unreported instead of undone. kb_validate's existing
+     * "not marked superseded" check is what surfaces the residue.
+     */
+    private markSupersededRetrying;
+    /** The one-directional half of `supersede`: marks `conceptId` superseded. */
+    private markSuperseded;
     private mutate;
     /**
      * Two guarantees, both about writers running in parallel.
@@ -583,6 +602,7 @@ declare const composeInputSchema: z.ZodObject<{
         last_modified: z.ZodOptional<z.ZodString>;
     }, z.core.$loose>>>;
     assumption: z.ZodOptional<z.ZodBoolean>;
+    stale_after: z.ZodOptional<z.ZodString>;
     verify: z.ZodOptional<z.ZodArray<z.ZodString>>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
     relatedConceptIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -631,9 +651,260 @@ declare const INDEX_FILE = "INDEX.md";
  * decide what is worth opening, and a list of titles does not answer that.
  */
 declare function renderIndex(records: KbRecord[]): string;
+/**
+ * One record's index line. The single writer of this shape — `context` emits
+ * the same line rather than growing a second index renderer that would drift
+ * from this one.
+ */
+declare function renderIndexLine(record: KbRecord): string;
 /** Whether the stored projection still matches the records it claims to index. */
 declare function indexIsStale(stored: string | null, expected: string): boolean;
 
+/**
+ * Pin manifests, in three layers.
+ *
+ * Pins are workspace state, not base state: they record which bases a session
+ * should be shown at every context birth. The pinned base is never touched —
+ * not even its log — because a base must remain copyable without knowing who
+ * pins it.
+ *
+ * The layers, nearest wins when the same base appears in more than one:
+ *
+ * | layer   | file                                    | for                        |
+ * | ------- | --------------------------------------- | -------------------------- |
+ * | project | <workspace>/.strauss/kb-pins.json       | committed, the team's pins |
+ * | local   | <workspace>/.strauss/kb-pins.local.json | personal, gitignored       |
+ * | user    | ~/.strauss/kb-pins.json                 | personal, every workspace  |
+ *
+ * Every manifest's paths resolve against its own root — the workspace for
+ * project and local, the home directory for user — so each file is portable
+ * with the tree it belongs to. `STRAUSS_KB_USER_ROOT` overrides the user root
+ * (tests, unusual homes).
+ */
+declare const PINS_FILE: string;
+declare const PINS_LOCAL_FILE: string;
+declare const PIN_LAYERS: readonly ["project", "local", "user"];
+type KbPinLayer = (typeof PIN_LAYERS)[number];
+/**
+ * Primary state — it records an intent nothing else holds — but trivially
+ * rewritable, so a full rewrite on change is fine and no append log is needed.
+ * Unknown keys are preserved on rewrite, the same tolerance the record reader
+ * extends to frontmatter it did not write.
+ */
+declare const pinSchema: z.ZodObject<{
+    path: z.ZodString;
+    pinnedAt: z.ZodOptional<z.ZodString>;
+    mode: z.ZodCatch<z.ZodOptional<z.ZodEnum<{
+        full: "full";
+        index: "index";
+    }>>>;
+    profiles: z.ZodCatch<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    frozen: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$loose>;
+declare const pinsManifestSchema: z.ZodObject<{
+    pins: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        pinnedAt: z.ZodOptional<z.ZodString>;
+        mode: z.ZodCatch<z.ZodOptional<z.ZodEnum<{
+            full: "full";
+            index: "index";
+        }>>>;
+        profiles: z.ZodCatch<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+        frozen: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
+    }, z.core.$loose>>>;
+    context: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$loose>;
+type KbPin = z.infer<typeof pinSchema>;
+type KbPinsManifest = z.infer<typeof pinsManifestSchema>;
+type KbContextBudgets = {
+    budgetTokens?: number;
+    fullUnderTokens?: number;
+};
+/** A pin as the merged view hands it back: entry + where it came from. */
+type KbMergedPin = KbPin & {
+    layer: KbPinLayer;
+    absolutePath: string;
+};
+type KbMergedPins = {
+    /** Effective pins after dedup — nearest layer wins per resolved path. */
+    pins: KbMergedPin[];
+    /** Per-layer manifests that parsed, for budget merging. */
+    manifests: Partial<Record<KbPinLayer, KbPinsManifest>>;
+};
+/** One pinned base, with whether it currently resolves to anything readable. */
+type KbPinStatus = {
+    /** As stored — relative to its layer's root. */
+    path: string;
+    layer: KbPinLayer;
+    pinnedAt: string | null;
+    absolutePath: string;
+    /** The directory exists and yielded at least one parseable record. */
+    valid: boolean;
+    recordCount: number;
+    mode: "full" | "index" | null;
+    profiles: string[] | null;
+    frozen: boolean;
+};
+type KbPinResult = {
+    path: string;
+    layer: KbPinLayer;
+    pinnedAt: string;
+    alreadyPinned: boolean;
+    mode?: "full" | "index";
+    profiles?: string[];
+    frozen?: boolean;
+    /** Set when the path holds no readable records — pinned anyway. */
+    warning?: string;
+};
+type KbPinOptions = {
+    mode?: "full" | "index";
+    profiles?: string[];
+    frozen?: boolean;
+    /** Which manifest to write. Defaults to the committed project layer. */
+    layer?: KbPinLayer;
+};
+
+/**
+ * One manifest's budgets for one profile: the named profile's values over the
+ * manifest's `"default"` entry. What is absent here falls through to the
+ * caller's built-ins — a manifest narrows, it never has to be complete.
+ */
+declare function contextProfileBudgets(manifest: KbPinsManifest, profile?: string): KbContextBudgets;
+/**
+ * Budgets across the layers: user underneath, local over it, project on top —
+ * the committed file is the workspace's word — and explicit flags above all
+ * of this, applied by the caller.
+ */
+declare function mergedContextBudgets(merged: KbMergedPins, profile?: string): KbContextBudgets;
+
+declare class KbPinsMalformedError extends Error {
+    constructor(file: string, cause: string);
+}
+declare class KbBaseFrozenError extends Error {
+    constructor(bundlePath: string, layer: KbPinLayer);
+}
+
+/**
+ * Refuses when a write would land in a base this workspace froze. Called by
+ * every mutating command; a workspace that pinned a base `--frozen` said the
+ * base is concluded, and a quiet write past that would be exactly the silent
+ * drift the pin was meant to stop.
+ */
+declare function assertBaseNotFrozen(workspaceDir: string, bundlePath: string): Promise<void>;
+
+/**
+ * One layer's manifest, or an empty one when the file is missing.
+ *
+ * A malformed file throws rather than being treated as empty: every write path
+ * does a full rewrite, and rewriting over content we could not read would
+ * destroy the one copy of it. Read-only consumers that must stay silent
+ * (`context` from a session hook, the merged reader) skip malformed layers
+ * themselves.
+ */
+declare function readPinsLayer(workspaceDir: string, layer: KbPinLayer): Promise<KbPinsManifest>;
+/** Where a stored pin points, resolved against its layer's root. */
+declare function resolvePinPath(rootDir: string, path: string): string;
+/**
+ * All three layers, merged. A malformed layer is skipped rather than thrown:
+ * this feeds hooks at every session start, and one broken personal file must
+ * not silence the team's pins — `pin`/`unpin` against the broken layer still
+ * refuse loudly.
+ */
+declare function readMergedPins(workspaceDir: string): Promise<KbMergedPins>;
+
+/** Every effective pin across the layers, with whether it points at records. */
+declare function listPins(store: KbStore, workspaceDir: string): Promise<KbPinStatus[]>;
+
+/**
+ * Adds a base to one layer's manifest. Idempotent — re-pinning a pinned path
+ * with no options returns the existing entry untouched, and re-pinning with
+ * `mode`, `profiles`, or `frozen` updates just those fields, which is how a
+ * pin's rendering or writability is changed. A path that is not (yet) a valid
+ * base succeeds with a warning: bases are routinely pinned before they are
+ * populated, the same way records link to records that do not exist yet.
+ */
+declare function pinBase(store: KbStore, workspaceDir: string, bundlePath: string, at: string, options?: KbPinOptions): Promise<KbPinResult>;
+
+/**
+ * Removes a base from every layer that holds it — unpinned means gone, not
+ * "gone from one file and still injected from another". A malformed layer is
+ * skipped (it cannot be rewritten safely); the layers actually touched are
+ * reported.
+ */
+declare function unpinBase(workspaceDir: string, bundlePath: string): Promise<{
+    path: string;
+    removed: boolean;
+    layers: KbPinLayer[];
+}>;
+
+/**
+ * What the hooks ask for by name, so the numbers live in one place and a repo
+ * can override them in its pin manifest rather than editing hook commands.
+ * `session-start` is a fresh window — room for tiny bases to arrive whole.
+ * `compact` competes with a summary for a smaller window — index only.
+ * `turn` is per-turn injection (Antigravity) — same tight stance as compact.
+ */
+declare const CONTEXT_PROFILES: Record<string, KbContextBudgets>;
+type KbContextOptions = {
+    /** Refuse past this. Defaults to 4000 tokens. */
+    budgetTokens?: number;
+    /** Emit bases whose full `load` fits under this as records, not index. 0 = off. */
+    fullUnderTokens?: number;
+    /**
+     * A named budget set. Resolution, most specific wins: explicit options,
+     * then the manifest's `context[profile]` over its `context.default`, then
+     * the built-in profile, then the package defaults. An unknown profile is
+     * not an error — it simply falls through; hooks must never break over a
+     * name.
+     */
+    profile?: string;
+    /**
+     * Where budget pressure is reported outside the block itself: a full pin
+     * that had to degrade to an index, a block that refused. The block already
+     * says both to the agent; this says them to the operator's log.
+     */
+    warn?: (entry: Record<string, unknown>) => void;
+};
+type KbContextResult = {
+    /** The markdown block. Empty when there are no pins — silence, not a stub. */
+    block: string;
+    /** Refused: over budget. The block then lists the bases instead of the index. */
+    refused: boolean;
+    approxTokens: number;
+    budgetTokens: number;
+    bases: {
+        path: string;
+        absolutePath: string;
+        approxTokens: number;
+    }[];
+};
+/**
+ * Builds the block, or a refusal that lists the bases — never a truncation. A
+ * truncated index is indistinguishable from a complete one, so a reader would
+ * take a slice for the whole, which is `load`'s argument one layer up.
+ */
+declare function buildContext(store: KbStore, workspaceDir: string, options?: KbContextOptions): Promise<KbContextResult>;
+/**
+ * The same block in the envelope hook protocols that demand strict JSON on
+ * stdout require:
+ * those protocols treat non-JSON stdout as a violation, where Claude Code and
+ * Codex take plain text. One canonical writer for the block; this is wrapping.
+ */
+declare function toHookJson(block: string, event: string): string;
+declare const CONTEXT_BEGIN = "<!-- strauss-kb:begin -->";
+declare const CONTEXT_END = "<!-- strauss-kb:end -->";
+type KbSyncResult = {
+    file: string;
+    action: "created" | "replaced" | "appended" | "removed" | "unchanged";
+};
+/**
+ * Idempotently plants the block between sentinels in an instruction file
+ * (AGENTS.md, CLAUDE.md). This is how a runtime without a reliable
+ * post-compact hook keeps a refreshable index: the file is re-read where the
+ * conversation is not. Everything outside the sentinels is left alone.
+ */
+declare function syncInstructions(file: string, block: string): Promise<KbSyncResult>;
+
 /**
  * The frontmatter contract, emitted rather than restated.
  *
@@ -762,6 +1033,7 @@ declare const decisionInputSchema: z.ZodObject<{
         author: z.ZodOptional<z.ZodString>;
         last_modified: z.ZodOptional<z.ZodString>;
     }, z.core.$loose>>>;
+    stale_after: z.ZodOptional<z.ZodString>;
     slug: z.ZodString;
     why: z.ZodString;
     anchors: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -802,15 +1074,17 @@ declare function selectDecisions(records: KbRecord[]): KbRecord[];
 /**
  * Every operation a knowledge base exposes, defined once.
  *
- * The CLI and the MCP server are both projections of this list. Kept apart they
- * drift within a day — fourteen commands against six tools — which is the same
- * failure as a schema restated in prose beside the code that enforces it, one
- * level up. A command added here appears in both surfaces or in neither, and a
- * test asserts exactly that.
+ * The CLI and the MCP server are both projections of this table. Kept apart
+ * they drift within a day — fourteen commands against six tools — which is the
+ * same failure as a schema restated in prose beside the code that enforces it,
+ * one level up. A command added to the table appears in both surfaces or in
+ * neither, and a test asserts exactly that.
  *
  * The two differ only in how arguments arrive: MCP passes an object matching
  * `input`, while the CLI has to turn positional argv into the same object.
  * `fromArgv` is that adapter and is the only per-surface code a command needs.
+ *
+ * One file per command in this folder; `index.ts` assembles the table.
  */
 type KbCommandContext = {
     store: KbStore;
@@ -820,8 +1094,13 @@ type KbCommandContext = {
 type KbCommand<Shape extends z.ZodRawShape = z.ZodRawShape> = {
     /** CLI verb. */
     name: string;
-    /** MCP tool name. */
-    tool: string;
+    /**
+     * MCP tool name. Absent only for CLI-only plumbing (`sync-instructions`),
+     * which exists to edit files for hooks and instruction blocks rather than to
+     * give an agent a capability — the capability, "get the pinned context
+     * block", is `kb_context`.
+     */
+    tool?: string;
     /** Argument spelling for CLI usage output. */
     usage: string;
     /** Shown to an agent choosing a tool, so it carries the judgment too. */
@@ -837,10 +1116,16 @@ type KbCommand<Shape extends z.ZodRawShape = z.ZodRawShape> = {
      */
     failsWhen?(result: unknown): boolean;
 };
-declare const KB_COMMANDS: KbCommand<z.ZodRawShape>[];
-declare const KB_COMMANDS_BY_NAME: Map<string, KbCommand<Readonly<{
-    [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
-}>>>;
+
+/**
+ * The command table, assembled from one file per command.
+ *
+ * Order is the CLI usage listing's order: the write path, the read path,
+ * base housekeeping, the format, and the workspace pin verbs.
+ */
+
+declare const KB_COMMANDS: KbCommand[];
+declare const KB_COMMANDS_BY_NAME: Map<string, KbCommand>;
 
 /**
  * A knowledge base's own MCP server, over stdio.
@@ -974,4 +1259,4 @@ declare function parseMarkdownWithFrontmatter<S extends z.ZodType>(text: string,
     frontmatter: ReturnType<S["safeParse"]>;
 };
 
-export { BaseError, type ComposeInput, type ComposedRecord, DECISION_TYPE, type DecisionInput, type DiffFile, type DiffHunk, type DiffMatch, type ErrorDetails, type ErrorProps, ErrorTypes, Fault, INDEX_FILE, KB_COMMANDS, KB_COMMANDS_BY_NAME, KB_CONCEPT_ID_PATTERN, KB_CONFIDENCES, KB_DIR, KB_MATERIALITIES, KB_RECORD_STATUSES, KB_RECORD_TYPES, KB_SLUG_PATTERN, type KbActorStamp, type KbAdjudicated, type KbAnchor, type KbCommand, type KbCommandContext, KbInvalidConceptIdError, type KbLoadResult, type KbLogEntry, type KbLogReadResult, type KbLogger, type KbRecord, KbRecordAlreadyExistsError, type KbRecordFrontmatter, KbRecordNotFoundError, type KbRecordStatus, type KbRecordType, type KbRecordTypeSpec, type KbSearchLogger, type KbSource, type KbStanding, KbStore, type KbSupersededStub, type KbTraceEdge, type KbTraceOptions, type KbTraceStep, type KbValidationProblem, type KbWarning, KbWriteConflictError, type KbWriteInput, LOG_FILE, type MatchOptions, NO_DECISION_SLUG, type QmdModule, RECORD_TYPES, SEARCH_INDEX_FILE, type SearchHit, type SearchOptions, type SymbolRange, TRACE_EDGES, adjudicate, composeDecisionRecord, composeInputSchema, composeNoDecisionRecord, composeRecord, createKbMcpServer, decisionInputSchema, indexIsStale, isKbRecordType, isNoDecisionRecord, kbActorStampSchema, kbAnchorSchema, kbConceptIdSchema, kbJsonSchemas, kbLogEntrySchema, kbRecordFrontmatterSchema, kbSourceSchema, loadQmd, matchToDiff, parseLog, parseMarkdownWithFrontmatter, renderIndex, renderLogEntry, resolveHeads, resolveHits, runKbCli, runKbMcpServer, searchBase, selectDecisions, splitMarkdownFrontmatter, stringifyMarkdownWithFrontmatter, trace, validateBundle };
+export { BaseError, CONTEXT_BEGIN, CONTEXT_END, CONTEXT_PROFILES, type ComposeInput, type ComposedRecord, DECISION_TYPE, type DecisionInput, type DiffFile, type DiffHunk, type DiffMatch, type ErrorDetails, type ErrorProps, ErrorTypes, Fault, INDEX_FILE, KB_COMMANDS, KB_COMMANDS_BY_NAME, KB_CONCEPT_ID_PATTERN, KB_CONFIDENCES, KB_DIR, KB_MATERIALITIES, KB_RECORD_STATUSES, KB_RECORD_TYPES, KB_SLUG_PATTERN, type KbActorStamp, type KbAdjudicated, type KbAnchor, KbBaseFrozenError, type KbCommand, type KbCommandContext, type KbContextBudgets, type KbContextOptions, type KbContextResult, KbInvalidConceptIdError, type KbLoadResult, type KbLogEntry, type KbLogReadResult, type KbLogger, type KbMergedPin, type KbMergedPins, type KbPin, type KbPinLayer, type KbPinOptions, type KbPinResult, type KbPinStatus, KbPinsMalformedError, type KbPinsManifest, type KbRecord, KbRecordAlreadyExistsError, type KbRecordFrontmatter, KbRecordNotFoundError, type KbRecordStatus, type KbRecordType, type KbRecordTypeSpec, type KbSearchLogger, type KbSource, type KbStanding, KbStore, type KbSupersededStub, type KbSyncResult, type KbTraceEdge, type KbTraceOptions, type KbTraceStep, type KbValidationProblem, type KbWarning, KbWriteConflictError, type KbWriteInput, LOG_FILE, type MatchOptions, NO_DECISION_SLUG, PINS_FILE, PINS_LOCAL_FILE, PIN_LAYERS, type QmdModule, RECORD_TYPES, SEARCH_INDEX_FILE, type SearchHit, type SearchOptions, type SymbolRange, TRACE_EDGES, adjudicate, assertBaseNotFrozen, buildContext, composeDecisionRecord, composeInputSchema, composeNoDecisionRecord, composeRecord, contextProfileBudgets, createKbMcpServer, decisionInputSchema, indexIsStale, isKbRecordType, isNoDecisionRecord, kbActorStampSchema, kbAnchorSchema, kbConceptIdSchema, kbJsonSchemas, kbLogEntrySchema, kbRecordFrontmatterSchema, kbSourceSchema, listPins, loadQmd, matchToDiff, mergedContextBudgets, parseLog, parseMarkdownWithFrontmatter, pinBase, readMergedPins, readPinsLayer, renderIndex, renderIndexLine, renderLogEntry, resolveHeads, resolveHits, resolvePinPath, runKbCli, runKbMcpServer, searchBase, selectDecisions, splitMarkdownFrontmatter, stringifyMarkdownWithFrontmatter, syncInstructions, toHookJson, trace, unpinBase, validateBundle };