@polydeukes/core 0.3.0 → 0.5.0

package/dist/config.d.ts

@@ -1,18 +1,15 @@
 /**
- * Config schema v2 + `defineConfig()` validator — config as data (CONFIG-04).
+ * Config schema and the `defineConfig()` validator — config as data.
  *
- * This is the single settings surface the three areas share (covenant's `protectedPaths`,
- * ledger's `testCmd`, memory's ticket pattern all reference this shape). Since schema v2 the
- * input is pure JSON-representable data: `testCmd` is a `{scope}` template string, and
- * `defineConfig` is the runtime validator for parsed unknown data (the CONFIG-03 loader feeds
- * it values the compiler never saw). It stays a pure function — zero file I/O, zero runtime
- * dependencies (hand-rolled validation; the published JSON Schema is a sibling artifact the
- * source never reads).
+ * The single settings surface the areas share. The input is pure JSON-representable data,
+ * and `defineConfig` is the runtime validator for parsed unknown values the compiler never
+ * saw. It stays a pure function — no file I/O and no runtime dependencies: validation is
+ * hand-rolled, and the published JSON Schema is a sibling artifact this source never reads.
  */
-/** Conventional default telemetry log path (PRD §4.3) — local-only observation data. */
+/** Conventional default telemetry log path — local-only observation data. */
 export declare const DEFAULT_TELEMETRY_LOG_PATH = ".polydeukes/roi.log";
 /**
- * `LanguageProfile` — the unit of the language axis (PRD §4.1).
+ * `LanguageProfile` — the unit of the language axis.
  *
  * `testCmd` is a shell command template: every literal `{scope}` token is substituted at
  * resolve time, and the core only carries the resulting string — it never interprets it.
@@ -27,16 +24,22 @@ export type LanguageProfile = {
     testCmd: string;
 };
 /**
- * `DisciplineForbid` — the delta-family predicate value (COVENANT-10 §4.1).
+ * `DisciplineForbid` — the delta-family predicate value.
  *
- * The string shorthand is equivalent to `{ added }`; `removed`/`present` directions are
- * deferred (COVENANT-12) and rejected by validation.
+ * The string shorthand is equivalent to `{ added }`. It is the only direction that exists;
+ * anything else is rejected by validation.
  */
 export type DisciplineForbid = string | {
     added: string;
 };
 /**
- * `DisciplineEntry` — one user-declared discipline (COVENANT-10 §4.1). Pure JSON data.
+ * `EnforceLevel` — an entry's own rung on the promotion ladder. `advise` records a break
+ * without stopping it; `block` pins the entry at block whatever default the ladder later
+ * adopts. Absence means advise; `block` is the promotion rung.
+ */
+export type EnforceLevel = 'block' | 'advise';
+/**
+ * `DisciplineEntry` — one user-declared discipline. Pure JSON data.
  *
  * Exactly one predicate key (`forbid` | `immutable` | `forbidCommand` |
  * `requirePrecedent`) per entry; `in`/`except` scope the delta and context families.
@@ -46,8 +49,10 @@ export type DisciplineForbid = string | {
 export type DisciplineEntry = {
     /** unique handle — telemetry label and verdict reason prefix */
     id: string;
-    /** prose rationale, documentation only — never judged */
+    /** prose rationale — never judged, and carried into the break message */
     why?: string;
+    /** the author's level; composes with the observer's surface level, lenient side winning */
+    enforce?: EnforceLevel;
     /** delta/context-family scope: glob(s) the file path must match (absent = every file change) */
     in?: string | string[];
     /** delta/context-family scope: glob(s) excluded after `in` */
@@ -63,44 +68,61 @@ export type DisciplineEntry = {
     /**
      * context family — the session evidence one edit requires beforehand. Exactly one
      * evidence key. The core owns and fully validates `command`; every other key is
-     * adapter vocabulary whose value passes through verbatim (CONFIG-07 layering).
+     * adapter vocabulary whose value passes through verbatim.
      */
     requirePrecedent?: Record<string, unknown>;
 };
 /**
- * `PolydeukesConfig` — the input shape a user writes (PRD §4.1). JSON-serializable data.
+ * `DisciplineDraft` — an unpromoted discipline: the promotion ladder's first rung,
+ * registered as prose ahead of any predicate.
+ *
+ * A draft is declared, never inferred — only the literal `draft: true` makes one, and an
+ * entry with neither a predicate nor the marker stays a validation error. It carries no
+ * predicate, scope, or trigger key, produces no registration, no judgment, and no
+ * telemetry row; `pdks explain` renders it as unpromoted.
+ */
+export type DisciplineDraft = {
+    /** unique handle in the same label space as judged entries and meta-covenant labels */
+    id: string;
+    /** the draft's whole body — required prose, unlike the judged families' optional why */
+    why: string;
+    /** the explicit marker; only the literal true exists (false is rejected as dead data) */
+    draft: true;
+};
+/**
+ * `PolydeukesConfig` — the input shape a user writes. JSON-serializable data.
  *
  * Language keys (`typescript`, `python`, …) are user *values*, not the core's vocabulary —
  * no language or tool literal appears in the core source.
  */
 export type PolydeukesConfig = {
-    /** IDE schema reference (CONFIG-03) — accepted and ignored, never part of the resolution */
+    /** IDE schema reference — accepted and ignored, never part of the resolution */
     $schema?: string;
     /** language axis, first-class. keys are user values ('typescript', 'python', …) */
     languages: Record<string, LanguageProfile>;
-    /** raw protected path patterns — normalization is CONFIG-02's job */
+    /** raw protected path patterns — normalized downstream, never here */
     protectedPaths?: string[];
     /**
-     * adapter namespaces (CONFIG-07) — keys are ecosystem values (never validated), each
-     * value is that adapter's own settings object, passed through verbatim (the vocabulary
-     * belongs to the adapter, whose own validator judges the contents)
+     * adapter namespaces — keys are ecosystem values (never validated), each value is that
+     * adapter's own settings object, passed through verbatim (the vocabulary belongs to the
+     * adapter, whose own validator judges the contents)
      */
     adapters?: Record<string, Record<string, unknown>>;
     telemetry?: {
-        /** conventional default applies when omitted (§4.3) */
+        /** conventional default applies when omitted */
         logPath?: string;
     };
     /** user-declared disciplines — validated here, compiled by the covenant package */
-    disciplines?: DisciplineEntry[];
+    disciplines?: (DisciplineEntry | DisciplineDraft)[];
     /**
-     * TTL witness values for the covenant valve seam (CONFIG-05) — consumed at
-     * assembly time, validated here
+     * TTL witness values for the covenant valve seam — consumed at assembly time,
+     * validated here
      */
     witness?: {
         /**
          * the agreed phrase a human types alone on a message's first line — quoting it
-         * mid-sentence is a mention, not an invocation (COVENANT-15). Non-empty after
-         * trimming; the value itself is free (provenance, not secrecy, is the defence)
+         * mid-sentence is a mention, not an invocation. Non-empty after trimming; the value
+         * itself is free, since provenance rather than secrecy is the defence
          */
         token: string;
         /** validity window in minutes from the user message's timestamp — finite and > 0 */
@@ -110,11 +132,11 @@ export type PolydeukesConfig = {
 /**
  * `ResolvedLanguageProfile` — a {@link LanguageProfile} with its template compiled.
  *
- * Consumers keep the callable shape (`testCmd(scope)`), identical to schema v1 (LEDGER-05).
+ * Consumers keep the callable shape (`testCmd(scope)`).
  */
 export type ResolvedLanguageProfile = {
     productionGlob: string | string[];
-    /** compiled from the template — consumers keep the callable shape (LEDGER-05) */
+    /** compiled from the template — consumers keep the callable shape */
     testCmd: (scope: string) => string;
 };
 /**
@@ -130,8 +152,14 @@ export type ResolvedConfig = {
     telemetry: {
         logPath: string;
     };
-    /** validated discipline data, passed through verbatim (absent stays absent) */
+    /**
+     * validated judged entries only — drafts are split out at resolution time so the
+     * covenant compiler has no path that receives one. Present whenever the input
+     * declared a `disciplines` array, holding exactly its judged entries in order.
+     */
     disciplines?: DisciplineEntry[];
+    /** validated drafts in declaration order (absent when the input carries none) */
+    drafts?: DisciplineDraft[];
     /** validated witness data, passed through verbatim (absent stays absent) */
     witness?: {
         token: string;
@@ -139,7 +167,7 @@ export type ResolvedConfig = {
     };
 };
 /**
- * `ConfigValidationError` — raised when a config fails structural validation (PRD §4.3).
+ * `ConfigValidationError` — raised when a config fails structural validation.
  *
  * The message names the offending field path so the developer sees exactly what is wrong.
  * This throw is a developer-time error (config authoring), a different axis from the
@@ -150,13 +178,13 @@ export declare class ConfigValidationError extends Error {
 }
 /**
  * Validate parsed unknown data as a {@link PolydeukesConfig} and return a
- * {@link ResolvedConfig} with defaults filled and templates compiled (PRD §4.3).
- * Pure — no file I/O.
+ * {@link ResolvedConfig} with defaults filled and templates compiled. Pure — no file I/O.
  *
  * Throws {@link ConfigValidationError} (naming the offending field path) when the top level
  * is not a plain object, any object level carries an unknown key, `languages` is
  * missing/empty, any language's `productionGlob` is missing/empty, any `testCmd` is not a
- * non-empty string template, `telemetry.logPath` is not a string, `protectedPaths` carries a
- * non-string element, or `adapters` is not a map of plain-object namespaces.
+ * non-empty string template, `telemetry.logPath` is not a non-empty string after trimming,
+ * `protectedPaths` carries a non-string or empty element, or `adapters` is not a map of
+ * plain-object namespaces.
  */
 export declare function defineConfig(config: unknown): ResolvedConfig;