@lmzhen/dsh-evolution-core 0.4.1 → 0.6.0

package/lib/types/citations.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Citation resolution for skill bodies and support files (design §5.2).
+ *
+ * WHY this exists beside `supportRefs` (skill-store.ts): that scanner answers
+ * "does this text contain a path-shaped token", which is the right question
+ * when a package is being ARCHIVED — every such path may dangle — and the wrong
+ * one when a section is only being MOVED, where nothing leaves and the only
+ * thing that changes is the directory a citation is read from. Measured false
+ * positives of the token scan: a URL tail (`https://host/references/x.md`), a
+ * category path the original Hermes documents as legitimate
+ * (`skills/scripts/foo.py`), and a prose command line
+ * (`npm run scripts/build.mjs`).
+ *
+ * CONTRACT: a token whose path STARTS WITH a support directory is a citation of
+ * this skill and is resolved from the SKILL ROOT, in whichever file it is
+ * written. A token that merely contains a support directory further along its
+ * path belongs to something else: it is reported as `foreign` and never
+ * resolved.
+ *
+ * PURE: existence is decided against the caller's file list, so identical
+ * inputs always answer the same report.
+ */
+/** Support directories that make a path a citation of the owning skill. */
+export declare const CITATION_SUPPORT_DIRS: readonly string[];
+/** How one path-shaped token was classified. */
+export type CitationKind = 
+/** Starts with a support directory: a citation of this skill. */
+'citation'
+/** Inside a fenced code block: illustrative, never resolved. */
+ | 'fence'
+/** Tail of a URL. */
+ | 'url'
+/** Contains a support directory further along its path (`skills/scripts/foo.py`). */
+ | 'foreign'
+/** A command line naming a path (`npm run scripts/build.mjs`). */
+ | 'prose';
+/** One scanned token with its classification and resolution. */
+export interface CitationRef {
+    /** The matched token, verbatim, after trailing sentence punctuation is stripped. */
+    raw: string;
+    /** 1-based line number in the scanned content. */
+    line: number;
+    /** Skill-root-relative target, or null when the token is not a citation of this skill. */
+    target: string | null;
+    /** The base a citation is read from; this scanner resolves the skill root only. */
+    base: 'root';
+    kind: CitationKind;
+    /** Whether `target` names a file in the caller's file list. */
+    exists: boolean;
+    /** `#fragment` carried by the token, when present. */
+    fragment?: string | undefined;
+}
+/** One scan of a body or support file. */
+export interface CitationReport {
+    refs: readonly CitationRef[];
+    /** Citations whose target is provably absent from the file list. */
+    dangling: readonly CitationRef[];
+    /** Citations a non-recursive listing cannot decide (target sits under a listed directory). */
+    unverified: readonly CitationRef[];
+    /** Path-shaped tokens that are not citations of this skill (foreign/url/prose/fence). */
+    foreign: readonly CitationRef[];
+    /** True when the scan stopped at the budget: a partial report never reads as clean. */
+    truncated: boolean;
+}
+/** Scan budget: bounded so a pathological body cannot stall a maintenance run. */
+export declare const DEFAULT_CITATION_REF_BUDGET = 500;
+/**
+ * Resolve every path-shaped token in `content`.
+ * @param input - content, the skill-root-relative path of its owner, the skill's
+ *   file list, and an optional scan budget.
+ * @returns the refs plus the dangling and foreign subsets; `truncated` marks a
+ *   report that stopped at the budget.
+ */
+export declare function resolveCitations(input: {
+    content: string;
+    file: string;
+    files: readonly string[];
+    budget?: number | undefined;
+}): CitationReport;
+/** The sanctioned body hook (design §5.6): a list item whose payload is
+ * exactly one support-file path, so the file stays discoverable in the body. */
+export declare const HOOK_LINE_RE: RegExp;
+/** The retirement escape hatch (design §5.6): a standalone body comment that
+ * names the support file it exempts and the reason it must survive. The path
+ * is part of the marker because the proposal list is per FILE, and a reason is
+ * required — an unexplained exemption is what this hook exists to prevent. */
+export declare const KEEP_LINE_RE: RegExp;
+/** Whether a skill-relative path names a FILE rather than a directory: the same
+ * rule the scanner applies to a token's final segment (`name.ext`). The support
+ * listing is one level deep and includes directory entries (a real library has
+ * `references/archive`), which no pointer or retirement list may treat as a file.
+ * @param path - a skill-root-relative support path.
+ * @returns true when the final segment is file-shaped.
+ */
+export declare function isFileShapedPath(path: string): boolean;
+/** Result of one hook scan over a body. */
+export interface BodyHookScan {
+    /** Targets named by a sanctioned hook line, in file order, deduplicated. */
+    targets: readonly string[];
+    /** Target -> the reason its `keep` marker records. */
+    kept: ReadonlyMap<string, string>;
+}
+/**
+ * Scan a body for sanctioned hooks and `keep` markers.
+ * @param content - the SKILL.md body (frontmatter included).
+ * @returns hook targets plus the `keep` reasons keyed by target.
+ */
+export declare function scanBodyHooks(content: string): BodyHookScan;
+//# sourceMappingURL=citations.d.ts.map

package/lib/types/constants.d.ts

@@ -52,6 +52,26 @@ export declare const PROTECTED_BUILTIN_SKILLS: ReadonlySet<string>;
 export declare const MAX_SKILL_NAME_LENGTH = 64;
 export declare const MAX_DESCRIPTION_LENGTH = 1024;
 export declare const MAX_SKILL_CONTENT_CHARS = 100000;
+/** The authoring DISCIPLINE band, taken from the upstream standard (archive §5):
+ * peer skills sit at 8-14k characters and a body pushing past 20k belongs in
+ * `references/*.md`. Deliberately separate from `MAX_SKILL_CONTENT_CHARS`: the
+ * hard ceiling is a deployment-tunable limit, this band is the authoring
+ * standard — deriving the band from the ceiling is exactly what let a 40k
+ * ceiling hide a 99k body without a single signal saying "split me" (V3). */
+export declare const AUTHORING_SPLIT_LINE_CHARS = 20000;
+/** Upstream's conversion basis for CHARACTER LIMITS: 2.75 chars/token, labelled
+ * model-independent in the config template (\`cli-config.yaml.example:538\`), and the
+ * basis behind every quoted token figure there — memory 2200 chars ≈ 800 tokens,
+ * user 1375 ≈ 500, SKILL.md 100_000 ≈ 36k (\`tools/skill_manager_tool.py:455\`).
+ * Limits are deliberately conservative, so this is the basis a BORROWED LIMIT must
+ * be converted with. */
+export declare const UPSTREAM_LIMIT_CHARS_PER_TOKEN = 2.75;
+/** The platform's own estimate basis: \`CHARS_PER_TOKEN = 4\` in
+ * \`@deepseek-ai/dsh-token-meter/estimate.ts\` (its comment reads "used until exact
+ * tokenization is needed"), matching upstream's ESTIMATE-side heuristic — "~4
+ * chars/token is the usual English heuristic" (\`agent/prompt_builder.py:1179\`).
+ * Estimates use this; limits use the constant above. */
+export declare const PLATFORM_ESTIMATE_CHARS_PER_TOKEN = 4;
 export declare const MAX_SKILL_FILE_BYTES = 1048576;
 export declare const DEFAULT_REVIEW_MEMORY_INTERVAL = 10;
 export declare const DEFAULT_REVIEW_SKILL_INTERVAL = 10;
@@ -86,6 +106,12 @@ export declare const DEFAULT_REVIEW_CONTEXT_MESSAGES = 60;
 export declare const DEFAULT_REVIEW_MESSAGE_CHARS = 2000;
 export declare const DEFAULT_CURATOR_BOOT_GRACE_SECONDS = 10;
 export declare const DEFAULT_CURATOR_REVIEW_MAX_TOKENS = 2048;
+/** Threat-scan WINDOW SIZE (not a total cap — E-12: the whole text is scanned in
+ * overlapping windows, so content beyond this stays in scope). The coverage
+ * floor is `PATTERN_OVERLAP + 1` (V6-05). Single home for the core scanners'
+ * default parameter and clamp fallback, plus evolution-threat's Config default
+ * — the two packages previously wrote 65_536 independently (G0/S0.1). */
+export declare const DEFAULT_THREAT_MAX_SCAN_CHARS = 65536;
 /** 0.3.17 (S3.10, T-1): control-plane fields a model-facing write call may
  * never carry — single source for plan-validator, evolution-policy and the
  * threat scanner (they used to each hardcode the list).
@@ -102,6 +128,11 @@ export declare const EVOLUTION_WRITE_TOOLS: readonly ["memory", "skill_manage"];
  * 0.3.16 (T-4): moved here from skill-store.ts so drift-signals (pure, no IO)
  * can reference it without importing the skill-store module. */
 export declare const AUTHORING_DESCRIPTION_BAR = 60;
+/** The split hint both size refusals share (0.5.0 V1). The same sentence used to
+ * be copied into validateFrontmatter AND the patch path, and neither copy named
+ * where the content should go — the upstream cap message names the destination
+ * directories, and that is the part a model actually acts on. */
+export declare const CONTENT_SPLIT_HINT = "Consider splitting into a smaller SKILL.md with supporting files in references/ or templates.";
 /** V27 G2.4: the largest millisecond delay a timer accepts. `AbortSignal.timeout`
  * (and `setTimeout`) coerce anything larger to 1ms after a Node warning, so a
  * timeout configured above this ceiling silently collapses to "immediately

package/lib/types/cost.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Context-cost accounting for skill bodies (design §5.2).
+ *
+ * A raw character count is a poor budget: the same 100k characters cost very
+ * different amounts of context in Chinese-heavy prose and in English. The
+ * weighted unit makes the two comparable, and the token range exists only to
+ * make the load cost visible next to the character count — it is an ESTIMATE,
+ * never a measurement.
+ *
+ * Accounting basis: the ON-DISK form (`skillMdOnDisk()`, the same view the
+ * write limit uses), so a body that is exactly at the limit cannot read as
+ * over-limit here and pass there (the v37 P2-1 deadlock class).
+ */
+/** Token weight of one CJK / kana / full-width code unit on the LIMIT basis —
+ * upstream's model-independent conversion is 2.75 chars/token for prose, and CJK
+ * prose is ~1 token per character (the conservative end of the 0.6–1.0 range the
+ * estimate side reports). Thresholds are compared on THIS basis so a borrowed
+ * character line keeps its meaning; the estimate range below reports the spread. */
+export declare const TOKEN_CJK_WEIGHT = 1;
+/** Token weight of one non-CJK code unit on the LIMIT basis (1 / 2.75 ≈ 0.364). */
+export declare const TOKEN_ASCII_WEIGHT: number;
+/** Token-per-unit bounds of the estimate range (CJK: 0.6–1.0, non-CJK: 1/4–1/3).
+ * The range is the 4-chars/token estimate family, so on ASCII-heavy bodies the
+ * LIMIT-basis `tokens` point can sit above `tokensHigh` (1/2.75 > 1/3): the two
+ * answer different questions and are never nested by construction. */
+export declare const COST_CJK_TOKEN_LOW = 0.6;
+export declare const COST_CJK_TOKEN_HIGH = 1;
+export declare const COST_ASCII_TOKEN_LOW = 0.25;
+export declare const COST_ASCII_TOKEN_HIGH: number;
+/** The token line a borrowed CHARACTER threshold draws for ONE body: 20k characters
+ * of THIS composition, expressed in the same tokens `bodyCost` counts. Comparing
+ * `tokens` against this line is deliberately equivalent to "chars >= line" — that
+ * equivalence is what keeps a borrowed line's textual effect identical — while the
+ * judgment itself, and every number reported, stays on the token scale.
+ * @param lineChars - the borrowed character line (whole-body characters).
+ * @param cost - the body's own cost breakdown.
+ * @returns the equivalent token line (0 when the body is empty). */
+export declare function tokenLineFor(lineChars: number, cost: BodyCost): number;
+/** Cost of one body: raw counts, the weighted total, and the estimate range. */
+export interface BodyCost {
+    /** Code units of the on-disk form — the same measure `maxSkillContentChars` bounds. */
+    chars: number;
+    /** Code units matched by the CJK ranges. */
+    cjk: number;
+    /** Code units that are not CJK (includes surrogate halves and syntax). */
+    ascii: number;
+    /** Single token count on the LIMIT basis: `cjk * TOKEN_CJK_WEIGHT + ascii *
+     * TOKEN_ASCII_WEIGHT`, rounded. This is the number every threshold compares
+     * against, so a threshold borrowed as a character line converts faithfully. */
+    tokens: number;
+    /** Lower bound of the token estimate. */
+    tokensLow: number;
+    /** Upper bound of the token estimate. */
+    tokensHigh: number;
+}
+/**
+ * Cost of one skill body.
+ * @param content - the body text as written (trailing whitespace is normalized
+ *   away by the on-disk accounting, so callers need not pre-trim).
+ * @returns the cost breakdown; an empty body answers all-zero.
+ */
+export declare function bodyCost(content: string): BodyCost;
+//# sourceMappingURL=cost.d.ts.map

package/lib/types/curator.d.ts

@@ -81,6 +81,12 @@ export interface CuratorRunReport {
     llmReviewEnabled?: boolean;
     /** V6-35 (0.3.36): lenient-parse shape notes from the LLM nomination block. */
     nominationsWarnings?: string[];
+    /** 0.5.0 V1 (design §16.6-④): archived entries past the retention window that
+     * the CURRENT policy keeps rather than deletes. Present (even empty) only when
+     * the retention policy was `report`, so a report cannot read as "nothing
+     * expired" for a run that pruned under a different policy. `null` means the
+     * listing could not be read — unknown, never "nothing expired". */
+    wouldPrune?: string[] | null;
 }
 export interface CuratorReportInput {
     runId: string;
@@ -99,6 +105,7 @@ export interface CuratorReportInput {
     snapshotPath?: string;
     llmReviewEnabled?: boolean;
     nominationsWarnings?: readonly string[];
+    wouldPrune?: readonly string[] | null;
 }
 export declare function buildCuratorRunReport(input: CuratorReportInput): CuratorRunReport;
 /**

package/lib/types/drift-signals.d.ts

@@ -10,6 +10,8 @@
  *
  * Distinct from `signals.ts` — the session-level review signal gate.
  */
+import { type CitationReport } from './citations.ts';
+import { type BodyCost } from './cost.ts';
 /** One skill's library state; the assembler (not this module) reads IO. */
 export interface DriftSkillSnapshot {
     name: string;
@@ -27,6 +29,23 @@ export interface DriftSkillSnapshot {
     protected?: string | null | undefined;
     /** Frontmatter values the strict-YAML platform catalog cannot load (0.3.11). */
     catalogInvalid?: boolean | undefined;
+    /** Weighted context cost of the body (design §5.2); undefined = not measured. */
+    cost?: BodyCost | undefined;
+    /** Citation scan of the body (design §5.2); undefined = not scanned. */
+    citations?: CitationReport | undefined;
+    /** Per-support-file read counts (design §5.5); undefined = no evidence. */
+    demand?: Readonly<Record<string, number>> | undefined;
+    /** Idle age of the owning skill (design §5.6); undefined = no record to age. */
+    liveness?: SkillLiveness | undefined;
+    /** Character counts of support files that can possibly exceed the content cap
+     * (design §16.6, V4); undefined = not measured. The assembler pre-filters by
+     * byte size, which is complete for the oversize question. */
+    supportChars?: Readonly<Record<string, number>> | undefined;
+}
+/** Retirement-proposal input for one skill (design §5.6). */
+export interface SkillLiveness {
+    /** Idle days since the lifecycle age anchor (`last activity ?? created_at`). */
+    idleDays: number;
 }
 /** verdict=over means "relatively positioned above the threshold", never a violation. */
 type DriftVerdict = 'pass' | 'over' | 'unknown';
@@ -56,11 +75,39 @@ export interface DriftReport {
 /** Physical line length at/above which a body line is reported overlong (011 §4). */
 export declare const DRIFT_MAX_LINE_CHARS = 1500;
 /** Signal-set version: bump whenever ids/thresholds change (011 §7 version coupling). */
-export declare const DRIFT_SIGNALS_VERSION = "1";
+export declare const DRIFT_SIGNALS_VERSION = "3";
 /** Render-time nouns for the MAINTAIN_PROMPT placeholders (single vocabulary with the facts block). */
 export declare const DRIFT_SIGNAL_NOUNS: Readonly<Record<string, string>>;
 /** Detect support files the body never references (by basename or relative path). */
 export declare function missingSupportPointers(body: string, supportFiles: readonly string[]): string[];
+/** Support files the body mentions WITHOUT the sanctioned hook form (design
+ * §5.6). Such a mention still counts as a pointer for `pointer_missing`, but
+ * only the hook form keeps the file discoverable after a move — detail only.
+ * A file carrying a `keep` marker is exempt: its mention IS the marker. */
+export declare function unhookedSupportPointers(body: string, supportFiles: readonly string[]): string[];
+/** Why a retirement report lists nothing (design §5.6). */
+export type RetirementStatus = 'listed' | 'none' | 'no-age' | 'unscanned';
+/** One support file proposed for retirement review. */
+export interface RetirementCandidate {
+    path: string;
+    /** Whole idle days of the owning skill at scan time. */
+    idleDays: number;
+}
+/** Retirement proposal for one skill: candidates plus the reason when empty. */
+export interface RetirementReport {
+    candidates: readonly RetirementCandidate[];
+    status: RetirementStatus;
+}
+/** Support files with no readers, no citations and no `keep` marker whose owning
+ * skill has been idle for at least the lifecycle stale window. PROPOSAL INPUT
+ * only — nothing retires a file on its own — and an unmeasurable input (no age
+ * evidence, no citation scan) yields an empty list WITH its reason, never a
+ * silent "nothing qualifies".
+ * @param snapshot - the skill's drift snapshot.
+ * @param supportFiles - its enumerated support files, in listing order.
+ * @returns the candidates plus the status that explains an empty list.
+ */
+export declare function retirementReport(snapshot: DriftSkillSnapshot, supportFiles: readonly string[]): RetirementReport;
 /** Duplicate `## heading` occurrences: singleton results default to head of the file. */
 export declare function duplicateHeadings(body: string): Array<{
     heading: string;

package/lib/types/frontmatter.d.ts

@@ -134,6 +134,14 @@ export declare function normalizeFrontmatter(content: string): FrontmatterNormal
  * excluded. Pure and deduplicated.
  */
 export declare function relatedSkillNames(content: string, exclude?: string): string[];
+/** S1.2 (v37 P2-1): the content limit applies to the bytes that LAND ON DISK.
+ * Every write normalizes with `trimEnd() + '\n'`, so judging the raw argument let
+ * a 100_000-character body with no trailing newline land as 100_001 bytes — and
+ * every later patch/update of that skill was then refused, which made it
+ * unmaintainable through `skill_manage` with no repair path at all. */
+/** The bytes that land on disk for a SKILL.md write — the ONE accounting basis
+ * shared by the content limit and the cost estimate (design §5.2). */
+export declare function skillMdOnDisk(content: string): string;
 /** Whether `content` would exceed `limit` once written. */
 export declare function exceedsContentLimit(content: string, limit: number): boolean;
 /** S1.2: the repair path — a write that makes an already-over-limit file smaller.

package/lib/types/index.d.ts

@@ -25,6 +25,9 @@
  *   `evolution-events.ts`, `io.ts` (the ctx.evolutionIo seam itself).
  * @module @lmzhen/dsh-evolution-core
  */
+export * from './citations.ts';
+export * from './reference-rewrite.ts';
+export * from './cost.ts';
 export * from './curator.ts';
 export * from './evolution-events.ts';
 export * from './gates.ts';
@@ -53,6 +56,7 @@ export * from './threats.ts';
 export * from './tool-dispatch.ts';
 export * from './usage.ts';
 export * from './constants.ts';
+export * from './params.ts';
 export * from './numeric.ts';
 export * from './opt-in.ts';
 //# sourceMappingURL=index.d.ts.map

package/lib/types/limits.d.ts

@@ -5,11 +5,79 @@
  * store share one declaration site. Re-exported by skill-store.ts: the package
  * export surface is unchanged.
  */
+/** How a restructure treats a section carrying support-file citations (design §2.2). */
+export type CitationPolicy = 'verify' | 'refuse';
+/** `verify` checks that every cited target exists and otherwise allows the move;
+ * `refuse` restores the pre-0.5 behaviour of refusing ANY citation-carrying
+ * section. Resolved at the call site, so every existing limits object keeps
+ * working (unknown policy never silently changes a write path). */
+export declare const DEFAULT_CITATION_POLICY: CitationPolicy;
+/** How a consolidation treats the source's support files (design §16.7).
+ * `off` refuses as before; `plan` keeps refusing but reports what a re-home
+ * would have to rewrite; `apply` (V2) performs the re-home and the rewrites, but
+ * only when the plan proves it leaves NOTHING dangling — otherwise it refuses
+ * exactly like `plan`. */
+export type ReferenceRewritePolicy = 'off' | 'plan' | 'apply';
+/** Default: report the plan on refusal, never write (behaviour unchanged). */
+export declare const DEFAULT_REFERENCE_REWRITE_POLICY: ReferenceRewritePolicy;
+/** What happens to `.archive` entries past the retention window (design §16.6-④).
+ * `report` (the default) names them and deletes nothing; `prune` restores the
+ * pre-0.5 deletion, which upstream never does. */
+export type ArchiveRetentionPolicy = 'report' | 'prune';
+/** Default: report-only, because upstream's hard invariant is never to delete. */
+export declare const DEFAULT_ARCHIVE_RETENTION_POLICY: ArchiveRetentionPolicy;
+/** How the 100k-character cap treats SUPPORT files (design §16.6, V4). Upstream
+ * applies the cap to every written file; we land it in `report` mode first (the
+ * write goes through with an advisory) and `enforce` refuses — with the same
+ * net-shrink repair path SKILL.md already has, so an over-cap legacy file can
+ * always be brought back under the cap instead of becoming unmaintainable. */
+export type SupportFileCharPolicy = 'report' | 'enforce';
+/** Default: report, so the cap cannot brick an existing oversize file on upgrade
+ * (the live library carries a 189k-character release log today). */
+export declare const DEFAULT_SUPPORT_FILE_CHAR_POLICY: SupportFileCharPolicy;
+/** The four stage defaults in ONE object, so the policy schema's `z.default(...)`
+ * calls and the store's fallbacks cannot drift apart. */
+export declare const POLICY_STAGE_DEFAULTS: Readonly<{
+    citationPolicy: "verify";
+    referenceRewrite: "plan";
+    archiveRetention: "report";
+    supportFileCharPolicy: "report";
+}>;
+/** The policy-snapshot fields that select a write-behaviour STAGE (design §16).
+ * Structural, not imported from evolution-policy, so core stays a leaf. */
+export interface PolicyStageFields {
+    citationPolicy?: CitationPolicy | undefined;
+    referenceRewrite?: ReferenceRewritePolicy | undefined;
+    archiveRetention?: ArchiveRetentionPolicy | undefined;
+    supportFileCharPolicy?: SupportFileCharPolicy | undefined;
+}
+/**
+ * The ONE conversion from the deployment policy snapshot to library limits
+ * (design §16.7): every plugin that owns a writable SkillLibrary spreads this into
+ * its limits, so a stage selected in cordis.yml reaches every write path. A
+ * per-plugin copy would be the third home for the same threshold.
+ *
+ * Only PRESENT fields are copied: an absent policy field must fall through to the
+ * library default rather than pinning `undefined` onto an optional limit (which
+ * `exactOptionalPropertyTypes` forbids and which would defeat the `?? DEFAULT`
+ * resolution inside the store).
+ * @param snapshot - the evolutionPolicy snapshot, or undefined when unmounted.
+ * @returns the stage fields the snapshot actually carries.
+ */
+export declare function policyStageLimits(snapshot: PolicyStageFields | undefined): PolicyStageFields;
 export interface SkillLimits {
     maxNameLength: number;
     maxDescriptionLength: number;
     maxSkillContentChars: number;
     maxSkillFileBytes: number;
+    /** See CitationPolicy. Optional so existing limits objects stay valid. */
+    citationPolicy?: CitationPolicy | undefined;
+    /** See ReferenceRewritePolicy; absent means the default (`plan`). */
+    referenceRewrite?: ReferenceRewritePolicy | undefined;
+    /** See ArchiveRetentionPolicy; absent means the default (`report`). */
+    archiveRetention?: ArchiveRetentionPolicy | undefined;
+    /** See SupportFileCharPolicy; absent means the default (`report`). */
+    supportFileCharPolicy?: SupportFileCharPolicy | undefined;
 }
 export declare const DEFAULT_SKILL_LIMITS: SkillLimits;
 //# sourceMappingURL=limits.d.ts.map

package/lib/types/params.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Parameter id consolidation (G0/S0.2): one semantic gets ONE id.
+ *
+ * Nine places in this family carry the same value under two carriers: three use
+ * the SAME name in two carriers (reviewMode, staleAfterDays, archiveAfterDays —
+ * resolved by the existing policy-shadows-row rule) and six use DIFFERENT names.
+ * This module owns the six: the policy/snapshot name is the canonical id, the
+ * plugin-row name is a deprecated alias kept readable for one minor version
+ * (0.6.x) and removable in 0.7.0.
+ *
+ * Reading stays compatible (a carrier still spelling the legacy name resolves),
+ * writing is strict (the write path accepts canonical ids only, so no new
+ * document is created under a deprecated name).
+ * @module
+ */
+/** Deprecated alias (plugin-row name) -> canonical id (policy/snapshot name). */
+export declare const PARAM_ALIASES: Readonly<Record<string, string>>;
+/**
+ * Resolve any parameter id to its canonical form.
+ * @param id - canonical id or deprecated alias.
+ * @returns the canonical id; ids without an alias pass through unchanged.
+ */
+export declare function resolveParamId(id: string): string;
+/**
+ * Whether an id is a deprecated alias.
+ * @param id - parameter id to test.
+ * @returns true when the id must be migrated to its canonical form.
+ */
+export declare function isDeprecatedParamId(id: string): boolean;
+/**
+ * Guard for the write path: only canonical ids may be written.
+ * @param id - parameter id a caller intends to write.
+ * @returns the canonical id.
+ * @throws {Error} when the id is a deprecated alias; the message names both ids.
+ */
+export declare function canonicalWriteId(id: string): string;
+/**
+ * Read a parameter from a carrier that may still spell the legacy name.
+ * @param carrier - config/snapshot object to read from, or undefined.
+ * @param id - canonical id (a deprecated alias is accepted and resolved first).
+ * @returns the canonical value when present, else the alias value, else undefined.
+ */
+export declare function readParam(carrier: object | undefined, id: string): unknown;
+/** Exposure group (design §7.2): the unit a developer changes together. */
+export type ParamGroup = 'library' | 'write-caps' | 'review' | 'memory' | 'curator' | 'deployment' | 'internal';
+/** Exposure tier (design §7.1): the interface combination a parameter gets. */
+export type ParamTier = 'E0' | 'E1' | 'E2' | 'E3' | 'E4';
+/** Where the authoritative value lives. */
+export type ParamAuthority = 'code' | 'cordis' | 'install';
+/**
+ * One parameter's exposure contract (design §8.1).
+ *
+ * MACHINE-READ CONTRACT: the entries below are written ONE PER LINE with the
+ * key order id, group, tier, authority, owner, applies, docAnchor, summary so
+ * the .mjs generators (`gen-param-docs.mjs`, `verify-param-registry.mjs`) can
+ * parse this text without importing TypeScript. `param-registry.spec.ts`
+ * asserts that the parsed text and this runtime array agree, so the two sides
+ * cannot drift.
+ *
+ * `applies` is the SETTINGS-side timing: 'none' means the parameter is not
+ * writable through the user layer (a cordis.yml change still follows the
+ * deployment's patch-reload policy).
+ */
+export interface ParamExposure {
+    id: string;
+    group: ParamGroup;
+    tier: ParamTier;
+    authority: ParamAuthority;
+    owner: string;
+    applies: 'live' | 'restart' | 'none';
+    docAnchor: string;
+    summary: string;
+}
+/**
+ * The parameter registry. G1/S1.1 seeds it with the review group (G-C); the
+ * remaining groups land in S2.1. E3 = behaviour preference the user may change
+ * (live); E2 = resource or identity knob that stays with the deployment.
+ */
+export declare const PARAM_EXPOSURE: readonly ParamExposure[];
+/** The settings namespace each OWNER PACKAGE registers (design §7.2).
+ *
+ * Keyed by owner rather than by group because a namespace has exactly one
+ * registrant (the platform refuses a second registration of the same name),
+ * while a group may span packages — group 'memory' is served by memory-files and
+ * tool-memory, each owning its own section. A package without an entry has no
+ * user layer (its knobs stay deployment-only). */
+export declare const PARAM_NAMESPACES: Readonly<Record<string, string>>;
+/** Structural view of one registered settings scope (platform Service Definition).
+ * Declared locally so this module keeps its zero-import, zero-dependency shape. */
+interface SettingsScopeLike {
+    get(): unknown;
+    watch(callback: (next: unknown, prev: unknown) => void): () => void;
+}
+/** Structural view of the platform settings provider; only the members the
+ * family uses are named. A missing `describe` disables the user layer loudly
+ * (see {@link paramSectionOverrides}) instead of reading as 'no overrides'. */
+export interface SettingsProviderLike {
+    register(namespace: string, schema: unknown, options: {
+        base: unknown;
+        applies?: 'live' | 'restart';
+        /** Owner-side refusal of a resolved section (cross-field rules the schema
+         * cannot express); throwing refuses the WRITE that produced the value. */
+        validate?: (value: unknown) => void;
+    }): SettingsScopeLike;
+    /** Merge a patch into one namespace's user layer. A stale `expectedRevision`
+     * rejects with the platform's SETTINGS_CONFLICT error. */
+    update?(namespace: string, patch: object, expectedRevision?: number): Promise<void>;
+    describe?(options?: {
+        redactSecrets?: boolean;
+    }): {
+        ns: string;
+        /** Current resolved section (schema defaults < base < user). */
+        value?: unknown;
+        /** Raw user section: a key's PRESENCE marks a user override. */
+        user?: Record<string, unknown>;
+        /** Monotonic revision of that raw section; a write sends it back. */
+        revision?: number;
+        /** Owner's declared effect timing. */
+        applies?: 'live' | 'restart';
+    }[];
+}
+/** Hooks a caller may supply when a section attaches to the settings service.
+ * @typeParam T - the section's value type (what `validate` inspects). */
+export interface ParamSectionOptions<T extends object = object> {
+    /** Called once when the user layer turns unreadable (a warning, never silent). */
+    warn?: (message: string) => void;
+    /** Called after every committed change that the reader can observe — the place
+     * to REBUILD registration-level facts (the platform's own `installSection`
+     * documents the same hook shape). Consumers that read at use time pass nothing. */
+    onChange?: () => void;
+    /** Refuse a resolved section the owner could not act on: a cross-field rule the
+     * schema cannot express (the platform applies this hook to the RESOLVED section,
+     * so a user value is judged together with the deployment layer beneath it).
+     * Throwing refuses the write that produced the value. */
+    validate?: (value: T) => void;
+}
+/** Reader for one parameter section: presence-aware user overrides. */
+export interface ParamOverrides<T extends object> {
+    /** The namespace this reader is bound to. */
+    readonly namespace: string;
+    /** The user-set value for one key, or undefined when the user never set it. */
+    get<K extends keyof T & string>(key: K): T[K] | undefined;
+    /** The resolved section (defaults < base < user) — display and tests. */
+    resolved(): T;
+}
+/**
+ * G3: expose one parameter section to the user layer.
+ *
+ * Precedence stays 'user > deployment > default': the caller keeps reading its
+ * deployment carriers (policy snapshot, then the plugin row) and consults
+ * {@link ParamOverrides.get} FIRST — an unset key returns undefined, so the
+ * deployment value keeps winning and the family's shadowing rules survive.
+ *
+ * Failure posture: a provider without `describe` (or one whose describe throws)
+ * leaves the user layer UNAVAILABLE and warns once — deployment values then
+ * apply. Treating an unreadable user layer as 'no overrides' would silently
+ * ignore a setting the user did write, so the warning names it.
+ * @typeParam T - the section's value type.
+ * @param provider - the platform settings provider, or undefined when absent.
+ * @param namespace - namespace to register.
+ * @param schema - schemastery schema the platform validates against.
+ * @param base - composition base layer (the plugin row's values).
+ * @param options - warning sink and the change hook.
+ * @returns a reader bound to the namespace.
+ */
+export declare function paramSectionOverrides<T extends object>(provider: SettingsProviderLike | undefined, namespace: string, schema: unknown, base: T, options?: ParamSectionOptions<T>): ParamOverrides<T>;
+/** Minimal structural view of the cordis context used to attach a section.
+ * The callback takes `unknown` on purpose: cordis's own `inject` declares a
+ * `Context` parameter, and a callback accepting `unknown` is assignable to it
+ * (parameter contravariance) while a narrower shape is not. */
+export interface SettingsHostLike {
+    inject(names: string[], callback: (ctx: unknown) => void): unknown;
+}
+/**
+ * Attach a parameter section through the optional settings service.
+ * @typeParam T - the section's value type.
+ * @param host - the plugin context (structurally typed).
+ * @param namespace - namespace to register.
+ * @param schema - schemastery schema the platform validates against.
+ * @param base - composition base layer (the plugin row's values).
+ * @param options - warning sink and the change hook.
+ * @returns a reader that follows the provider when it appears.
+ */
+export declare function installParamSection<T extends object>(host: SettingsHostLike, namespace: string, schema: unknown, base: T, options?: ParamSectionOptions<T>): ParamOverrides<T>;
+/**
+ * Number-typed read over {@link readParam}: the family's tunables are numbers,
+ * and a value of another type reads as absent so the caller's default applies
+ * (the same outcome the numeric clamps produce for a malformed value).
+ * @param carrier - config/snapshot object to read from, or undefined.
+ * @param id - canonical id (a deprecated alias is accepted and resolved first).
+ * @returns the resolved number, or undefined when absent or not a number.
+ */
+export declare function readNumberParam(carrier: object | undefined, id: string): number | undefined;
+export {};
+//# sourceMappingURL=params.d.ts.map