@fractalsynapse/dsh-chapters 0.0.0-stage → 0.2.21

package/lib/rules.d.ts

@@ -0,0 +1,267 @@
+import { z } from 'zod';
+export declare const RULE_STATUS: readonly ["proposed", "core", "revoked"];
+export type RuleStatus = (typeof RULE_STATUS)[number];
+/** §7.1: two tiers, one store. Absent scope on any file or record ⇒ `project`. */
+export declare const RULE_SCOPE: readonly ["project", "session"];
+export type RuleScope = (typeof RULE_SCOPE)[number];
+/** How the bytes came to be: a person, the deterministic marker, or the model. */
+export declare const RULE_DERIVED_FROM: readonly ["human", "marker", "model"];
+export type RuleDerivedFrom = (typeof RULE_DERIVED_FROM)[number];
+/**
+ * The WARRANT behind a rule — what a human reads when deciding whether to trust
+ * it (record §7.5, amended 2026-10-21). `stated` means a human sentence is behind
+ * the rule; `inferred` means the model judged that a standing order would help and
+ * nobody said it. BOTH govern by default, because the premise of the tier is that
+ * the human may not know the rule yet — the distinction is displayed, not used as
+ * a permission check. Requiring a human to have already said it would make this
+ * tier redundant with the deterministic `ADD RULE:` marker.
+ */
+export declare const RULE_BASIS: readonly ["human", "marker", "stated", "inferred"];
+export type RuleBasis = (typeof RULE_BASIS)[number];
+export interface RuleRecord {
+    id: string;
+    projectKey: string;
+    number: number;
+    path: string;
+    category: string;
+    title: string;
+    sourceSession: string;
+    at: string;
+    /** §7.1 tier; absent ⇒ 'project' (the pre-#50 default). The `| undefined`
+     * unions are load-bearing: `exactOptionalPropertyTypes` is on, and this
+     * interface is what `ruleRecordSchema` types at the registry boundary. */
+    scope?: RuleScope | undefined;
+    /** session tier only: the session whose tree this rule belongs to (§7.5). */
+    session?: string | undefined;
+    /** §7.1 provenance; absent ⇒ 'human'. */
+    derivedFrom?: RuleDerivedFrom | undefined;
+    /** §7.4 always-rendered class; human-set only. */
+    pinned?: boolean | undefined;
+    /** §7.5 (amended 2026-10-21): review posture, NOT an evidence test. A mined
+     * rule is inert until this machine approves it only when `rulesAutoActivate` is
+     * off. The default is that it governs immediately — inferring a useful standing
+     * order IS the point of the tier. */
+    reviewOnly?: boolean | undefined;
+    /** §7.5: the warrant a human reads alongside the text. */
+    basis?: RuleBasis | undefined;
+    /** the chapter a mined rule came from (provenance for the review surface) */
+    chapter?: number | undefined;
+}
+export declare const ruleRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    projectKey: z.ZodString;
+    number: z.ZodNumber;
+    path: z.ZodString;
+    category: z.ZodString;
+    title: z.ZodString;
+    sourceSession: z.ZodString;
+    at: z.ZodString;
+    scope: z.ZodOptional<z.ZodEnum<{
+        project: "project";
+        session: "session";
+    }>>;
+    session: z.ZodOptional<z.ZodString>;
+    derivedFrom: z.ZodOptional<z.ZodEnum<{
+        model: "model";
+        human: "human";
+        marker: "marker";
+    }>>;
+    pinned: z.ZodOptional<z.ZodBoolean>;
+    reviewOnly: z.ZodOptional<z.ZodBoolean>;
+    basis: z.ZodOptional<z.ZodEnum<{
+        human: "human";
+        marker: "marker";
+        stated: "stated";
+        inferred: "inferred";
+    }>>;
+    chapter: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const ruleSlug: (category: string, title: string) => string;
+export declare const rulePath: (storeRoot: string, harnessId: string, number: number, category: string, title: string) => string;
+/** one write, ever: rules are proposed by their author and never rewritten (status rides facts) */
+export declare function renderRuleFile(input: {
+    number: number;
+    category: string;
+    title: string;
+    sourceSession: string;
+    at: string;
+    body: string;
+    scope?: RuleScope | undefined;
+    session?: string | undefined;
+    derivedFrom?: RuleDerivedFrom | undefined;
+    pinned?: boolean | undefined;
+    reviewOnly?: boolean | undefined;
+    basis?: RuleBasis | undefined;
+    chapter?: number | undefined;
+}): string;
+export interface ParsedRule {
+    number: number;
+    category: string;
+    title: string;
+    fileStatus: RuleStatus;
+    sourceSession: string;
+    body: string;
+    scope: RuleScope;
+    session: string;
+    derivedFrom: RuleDerivedFrom;
+    pinned: boolean;
+    reviewOnly: boolean;
+    basis: RuleBasis;
+    chapter: number;
+}
+export declare function parseRuleFile(text: string): ParsedRule | null;
+export interface RuleStatusFact {
+    rule: string;
+    status: RuleStatus;
+    at: string;
+}
+/** the machine's own facts, last-write-wins per rule (append-only file order) */
+export declare function loadRuleStatusFacts(mirrorDir: string, harnessId: string): Map<string, RuleStatusFact>;
+/** append-only, like every other curation write */
+export declare function appendRuleStatusFact(mirrorDir: string, harnessId: string, fact: RuleStatusFact): void;
+export declare function effectiveStatus(ruleId: string, facts: Map<string, RuleStatusFact>, fileStatus: RuleStatus): RuleStatus;
+/**
+ * §7.4: a PIN is a curation fact, never a rewrite. Rule files are write-once
+ * (§1.3) and the append-only rule has no exceptions, so "always show this one"
+ * rides `edits/<harness>/curation.jsonl` as its own fact type — one writer per
+ * file, per-machine by construction, and a git-revertable line.
+ */
+export interface RulePinFact {
+    rule: string;
+    pinned: boolean;
+    at: string;
+}
+export declare function appendRulePinFact(mirrorDir: string, harnessId: string, fact: RulePinFact): void;
+/** the machine's pins, last-write-wins (so `unpin` is a later fact, not a delete) */
+export declare function loadRulePins(mirrorDir: string, harnessId: string): Set<string>;
+export interface MirrorRule {
+    id: string;
+    relPath: string;
+    status: RuleStatus;
+    category: string;
+    title: string;
+    body: string;
+    bodyTokens: number;
+    /** §7.1 tier. A session rule has no business appearing in the mirror (§7.5);
+     * if one does (a hand-copied pool, an older build), the builder still only
+     * renders session rules collected from the LOCAL store for this ancestor
+     * path — so a smuggled file cannot govern a head. */
+    scope: RuleScope;
+    session: string;
+    derivedFrom: RuleDerivedFrom;
+    pinned: boolean;
+    /** §7.5: inert pending review — set only when `rulesAutoActivate` is off */
+    reviewOnly: boolean;
+    basis: RuleBasis;
+    chapter: number;
+}
+/** every rule file the mirror knows for one project, with THIS machine's effective status */
+export declare function collectMirrorRules(mirrorDir: string, projectKey: string, harnessId: string): MirrorRule[];
+export type RulesSectionResult = {
+    kind: 'none';
+} | {
+    kind: 'ok';
+    text: string;
+    tokens: number;
+    shown: {
+        project: number;
+        session: number;
+    };
+    withheld: {
+        project: number;
+        session: number;
+    };
+} | {
+    kind: 'refusal';
+    reason: string;
+    perRule: Array<{
+        id: string;
+        tokens: number;
+    }>;
+    cap: number;
+    total: number;
+};
+/** §7.3 options. Every #50 field is optional: with none of them supplied the
+ * builder renders exactly what it rendered before #50 — which is what keeps the
+ * existing notice goldens, the four door call sites, and the tape corpus intact. */
+export interface RulesSectionOptions {
+    projectKey: string;
+    harnessId: string;
+    budgetTokens: number;
+    /** local store root (`<cwd>/<storeRoot>`); supplies the session tier (§7.5). */
+    storeDir?: string | undefined;
+    /** this session's ancestor path, including itself (§7.5 activation). */
+    ancestorSessions?: ReadonlySet<string> | undefined;
+    /** §7.4 per-tier count caps; absent ⇒ unlimited (the pre-#50 behavior). */
+    projectCap?: number | undefined;
+    sessionCap?: number | undefined;
+    /** §7.4 relevance input: the archived span's topic signatures (or a query). */
+    relevanceTopics?: readonly string[] | undefined;
+}
+/**
+ * §7.4 selection: pinned first (ground rules are OLD — anything that ranks by
+ * recency or topicality evicts them first), then topicality when topics are
+ * supplied, then the pre-#50 category/id order. A pure function of the inputs,
+ * so two machines with the same files render the same head and the tapes stay
+ * stable.
+ */
+export declare function selectRules(rules: readonly MirrorRule[], topics?: readonly string[]): MirrorRule[];
+/** the rule ids a human switched off on THIS machine (both tiers) */
+export declare function revokedRuleIds(mirrorDir: string, harnessId: string): Set<string>;
+/**
+ * §7.5: session rules are collected from the LOCAL store, never from the pool
+ * mirror — they are not staged (`planStoreToRepo` skips `scope: session`), so
+ * the only place they exist is `<storeDir>/rules/<harness>/*.md`. Same parser,
+ * same id shape, so `list`, numbering and search stay one mechanism for both
+ * tiers.
+ */
+export declare function collectStoreRules(storeDir: string, harnessId: string, 
+/** §7.5: this machine's `rule-status` facts, so a human `approve` can switch a
+ * SUGGESTED model rule on without rewriting the write-once file. */
+facts?: Map<string, RuleStatusFact> | undefined): MirrorRule[];
+/**
+ * §7.5 transport predicate: is this authored rule file part of the machine-local
+ * session tier? Reads it through the SAME parser the collectors use — one
+ * definition of `scope`, never a second lightweight guess that can drift from it.
+ * An unreadable or non-rule file is treated as project (staged), because the
+ * exclusion must be a decision about the session tier specifically, not a
+ * side-effect of a parse miss.
+ */
+export declare function isSessionRuleFile(absPath: string): boolean;
+/**
+ * §7.5 activation, DERIVED rather than approved: a session rule binds exactly
+ * one session tree — its own session must be on the current session's ancestor
+ * path — and a human `revoke` is the one fact that can switch it off (files are
+ * write-once, §1.3, so there is nothing else to edit).
+ */
+export declare function sessionRuleActive(rule: MirrorRule, 
+/** `facts` is unused here (the caller resolves status into `rule.status`); it is
+ * accepted so both collectors and callers pass ONE options object around. */
+opts: {
+    ancestorSessions: ReadonlySet<string>;
+    revoked: ReadonlySet<string>;
+    facts?: Map<string, RuleStatusFact> | undefined;
+}): boolean;
+/** The session-tier view for one rebuilt head: active rules, id-ordered. */
+export declare function collectActiveSessionRules(storeDir: string, harnessId: string, opts: {
+    ancestorSessions: ReadonlySet<string>;
+    revoked: ReadonlySet<string>;
+    facts?: Map<string, RuleStatusFact> | undefined;
+}): MirrorRule[];
+/**
+ * §7.5 re-derivation and the capture path: scan text for the marker at LINE
+ * START and return the rule bodies, in order, deduped by exact body.
+ *
+ * Deterministic and model-free by contract (§1 invariant 1) — this is the
+ * per-turn path AND the rebuild-after-loss path, so it must never touch `ctx.llm`.
+ */
+export declare function parseRuleMarkers(text: string, prefix: string): string[];
+/**
+ * §7.3: the rules block a rebuilt head carries. `kind: 'none'` (no active rules
+ * and no corpus) MUST produce zero injected bytes at the call site — the tape
+ * corpus depends on it. Overflow of the TOKEN ceiling refuses with per-rule
+ * numbers, never clips (§1.2); a count CAP selects, and what it left out is
+ * ANNOUNCED, because silent selection would rebuild "lost in the noise" inside
+ * the fix for it.
+ */
+export declare function buildRulesSection(mirrorDir: string, opts: RulesSectionOptions): RulesSectionResult;