@lmzhen/dsh-evolution-core 0.5.0 → 0.6.1

package/lib/types/constants.d.ts

@@ -106,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).

package/lib/types/index.d.ts

@@ -56,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/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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-core",
   "description": "Shared stores, prompts, signals and lifecycle logic for the dsh-evolution plugin family (community build)",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "publishConfig": {
     "access": "public"
   },