wicked-core-ts 0.7.3 → 0.7.5

package/index.d.ts

@@ -311,10 +311,53 @@ export declare class Core {
   recallKnowledge(query: string, k: number): Promise<string>
   /** All registered governance policies, as a JSON array of `Policy` objects. */
   listPolicies(): Promise<string>
-  /** All conformance rules on the store (Pattern + Policy types), as a JSON array. */
-  listConformanceRules(): Promise<string>
+  /**
+   * All conformance rules on the store (Pattern + Policy types), as a JSON array of
+   * serialized `ConformanceRule` objects — severity-first (critical→info), then weight DESC
+   * within a band, then id. The rows carry the unified steering-rule model's fields
+   * (steering_type / applies_to / excludes / weight / effect / trigger / obligations /
+   * criteria / provenance / …) exactly as the model serializes them — default-valued steering
+   * fields are elided on the wire (absent steering_type ⇒ "architecture", absent weight ⇒ 1).
+   *
+   * Steering facets (the studio Steering surface's list):
+   * - `steeringType` filters on the rule's `steering_type` — one of architecture | development |
+   *   security | testing | operations | compliance | design-ux. A rule authored before the
+   *   field existed counts as `"architecture"` (the model's serde default); an unknown value
+   *   REJECTS (fails closed — a typo must not read as "no rules of that type").
+   * - `includeRetired: true` adds withdrawn rules (retire-not-delete: they still explain the
+   *   past decisions that cite them; recall/enforcement never returns them).
+   *
+   * Both omitted ⇒ the exact pre-0.7.5 behavior (every active rule).
+   */
+  listConformanceRules(steeringType?: string | undefined | null, includeRetired?: boolean | undefined | null): Promise<string>
+  /**
+   * The doctrine RuleSet parents (AW-13 grouping) as a JSON array of
+   * `{ domain, rule_ids, rule_count }` rows, domain-sorted. The array length is the wiki
+   * meta's `ruleset_count` (crew's `countRuleSets` resolved `null` on engine builds without
+   * this binding — "cannot count" must never impersonate "0"); the rows carry `Contains`
+   * membership so grouping renders without a second round-trip. Membership is the store's
+   * edges verbatim — a retired rule stays listed in its RuleSet (grouping is doc structure,
+   * not enforcement). Read-only connection; never blocks the single-writer actor.
+   */
+  listRuleSets(): Promise<string>
   /** All conformance claims (governance decisions) on the store, as a JSON array. */
   listConformanceClaims(): Promise<string>
+  /**
+   * The AW-23 / arch-R23 population/connection scoreboard — the wiki-health report that tells
+   * a POPULATED rule corpus from an ingested-once-and-decaying one: rule counts, typing
+   * coverage, connection (ref-resolution) coverage, enforcement evidence, recall volume.
+   * Resolves to the SAME JSON `wicked-core rules scoreboard --json` emits (a pretty-printed
+   * `Scoreboard` object) — one report shape for CLI operators and crew/studio consumers alike.
+   *
+   * `docsDir` mirrors the CLI's `--dir`: typing coverage is doc-side (`enforcement_class`
+   * lives in frontmatter, never on the rule node), so it needs the SAME docs root
+   * `rules ingest --dir` used; omit it and the report says `typing.available: false`,
+   * honestly, in-band — never a fake 0% or 100%. `ambiguityCap` mirrors `--ambiguity-cap`
+   * (default 5; must be ≥ 1 — fails closed on 0, like the CLI). Strictly a REPORT over a
+   * read-only connection: it never blocks the single-writer actor, and residue gating stays
+   * `rules drift`'s job.
+   */
+  governanceScoreboard(docsDir?: string | undefined | null, ambiguityCap?: number | undefined | null): Promise<string>
   /**
    * Upsert a governance policy. `policy_json` is a JSON-serialized `Policy` object
    * (fields: id, kind, applies_to, effect, trigger, severity, criteria, rule, obligations).
@@ -324,10 +367,77 @@ export declare class Core {
   upsertPolicy(policyJson: string): Promise<string>
   /**
    * Upsert a conformance rule. `rule_json` is a JSON-serialized `ConformanceRule` object
-   * (fields: id, rule_type, statement, severity, confidence, targets, provenance).
-   * Validates server-side (INV-C1/C2/C4). Idempotent on stable id.
+   * (fields: id, rule_type, statement, severity, confidence, targets, provenance — plus the
+   * unified steering-rule fields: steering_type, applies_to, excludes, weight, and the
+   * optional effect / trigger / obligations / criteria; a rule without `effect` stays
+   * recall-only). The JSON passes through un-projected — the model's own serde is the wire
+   * contract, so new steering fields ride this binding without a rebuild. Provenance is
+   * first-class for UI/chat-authored rules too (`provenance.source: "ui" | "chat"`), not just
+   * doc-ingested `path@sha#id` rows. Validates server-side (INV-C1/C2/C4). Idempotent on
+   * stable id.
    */
   upsertConformanceRule(ruleJson: string): Promise<string>
+  /**
+   * STEERING batch import (the unified steering-rule model). `batch_json` is a JSON
+   * `{ default_type: string | null, entries: [...] }` document where each entry is either a
+   * frontmattered markdown doc (`{ kind: "doc", name?, content }` — parsed by the SAME
+   * MarkdownAdapter/normalize path `rules ingest --dir` runs, provenance `path@sha#id` refs
+   * included) or a ready rule object (`{ kind: "rule", rule }` — the rule JSON passes to the
+   * upsert path un-projected, so new model fields ride through without a rebuild).
+   * `default_type` is applied as the `steering_type` of every rule whose entry omits one; a
+   * rule that names its own type keeps it.
+   *
+   * Fail-closed PER ENTRY: a bad entry (unparseable doc, invalid rule, INV violation,
+   * duplicate id within the batch) rejects ALONE with its reason — the rest still land; only
+   * a malformed batch envelope rejects the whole call. Every write goes through the
+   * single-writer actor (validate + `register_rule`). Resolves to a JSON array of per-entry
+   * results, batch order: `{ index, name?, status: "imported" | "rejected", ids?, error? }`
+   * (`ids` = the rule ids the entry minted — a doc can mint several; a rejected entry mints
+   * none). This binding is also crew's PRESENCE SENTINEL for the whole steering seam
+   * (`steeringSupported()`): it ships with the unified model, so its existence tells crew the
+   * engine round-trips the steering fields instead of silently dropping them.
+   */
+  steeringImport(batchJson: string): Promise<string>
+  /**
+   * Governance rules eval — run an eval corpus through the REAL SELECT→DECIDE gate path and
+   * score every sample (the engine seam behind crew's `POST /api/v1/testing/evals/run`).
+   * `args_json` is `{ type?, corpus?, knowledgeDb?, dbPath }` (camelCase keys are the PINNED
+   * binding contract): `type` slices the corpus to one of the 7 steering types; `corpus`
+   * names an estate knowledge scope (`evals:<name>` — a corpus landed by
+   * [`Core::governance_corpus_import`]) or, omitted, selects the compiled-in default corpus;
+   * `knowledgeDb` powers embedding gap hints (absent/unusable ⇒ the report carries
+   * `degraded: "facet-only"` — an honest downgrade to keyword hints, never fabricated
+   * similarity); `dbPath` is the rules store, opened READ-ONLY — this call never goes through
+   * the single-writer actor and never writes either store.
+   *
+   * Resolves to the `EvalReport` JSON exactly as the engine serializes it (snake_case — crew
+   * passes it through verbatim as the pinned wire contract):
+   * `{ results: [{ sample: { id, description, kind, steering_type }, expected: "deny"|"allow",
+   * fired: [rule-id…], verdict: "caught"|"gap"|"false_positive", nearest_rules? }],
+   * summary: { total, caught, gaps, false_positives }, degraded: "facet-only"|null }`.
+   *
+   * Fail-closed: malformed args, an unknown steering type, a corpus name outside the
+   * `evals:` scope, or a missing store reject the Promise with the engine's reason — crew maps
+   * those to 400, and gates the whole route on this binding's PRESENCE (absent ⇒ 501).
+   */
+  governanceEvals(argsJson: string): Promise<string>
+  /**
+   * Import an eval corpus into the estate knowledge store (the engine seam behind crew's
+   * `POST /api/v1/testing/corpora/import`). `args_json` is `{ name, samples, knowledgeDb? }`
+   * (camelCase keys are the PINNED binding contract): `samples` is an array of
+   * `{ id, description, kind: "good"|"bad", steering_type, signals: { phase?, tool?, files?,
+   * content? } }` — validated fail-closed as a whole corpus (blank/duplicate ids, unknown
+   * steering types reject the batch) and landed under scope `evals:<name>`, one chunk per
+   * sample, id-keyed (re-import upserts in place) WITH embeddings via the same
+   * `KnowledgeEngine` path the rules fan-out uses. `knowledgeDb` defaults to the operator's
+   * `~/.wicked-estate/knowledge.db`; tests must always pass a temp path.
+   *
+   * Resolves to the `ImportReceipt` JSON `{ imported, scope: "evals:<name>", embedded }` —
+   * `embedded` is VERIFIED against the durable store after the write handle drops, not
+   * asserted. Fail-closed on malformed args (crew maps that to 400; route presence-gates on
+   * this binding like [`Core::governance_evals`] — absent ⇒ 501).
+   */
+  governanceCorpusImport(argsJson: string): Promise<string>
   /**
    * Withdraw a governance policy from enforcement (FINDING-038 — governance state was otherwise
    * append-only, so a mis-authored policy denied forever).
@@ -367,7 +477,8 @@ export declare class Core {
   registerWorkflow(json: string): Promise<string>
   /**
    * Recall which conformance rules apply to the given `query_json` (a JSON-serialized
-   * `RuleQuery` — fields: language, layer, framework, severity, rule_type; all optional).
+   * `RuleQuery` — fields: language, layer, framework, severity, rule_type, steering_type;
+   * all optional).
    * An empty or whitespace `query_json` is treated as an all-rules query (no facet filters).
    * Opens a read-only connection — does not block the single-writer actor. Returns a JSON
    * array of `ConformanceRule` objects, severity-first then id.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-core-ts",
-  "version": "0.7.3",
+  "version": "0.7.5",
   "description": "Node/TypeScript bindings (napi-rs) for wicked-core: drive the in-process orchestration engine from JS/TS.",
   "license": "MIT",
   "repository": {
@@ -38,14 +38,15 @@
     "smoke": "node smoke.mjs",
     "smoke:lifecycle": "node smoke-lifecycle.mjs",
     "smoke:terminal": "node smoke-terminal.mjs",
-    "smoke:all": "node smoke.mjs && node smoke-lifecycle.mjs && node smoke-terminal.mjs"
+    "smoke:evals": "node smoke-evals.mjs",
+    "smoke:all": "node smoke.mjs && node smoke-lifecycle.mjs && node smoke-terminal.mjs && node smoke-evals.mjs"
   },
   "optionalDependencies": {
-    "wicked-core-ts-darwin-arm64": "0.7.3",
-    "wicked-core-ts-darwin-x64": "0.7.3",
-    "wicked-core-ts-linux-arm64-gnu": "0.7.3",
-    "wicked-core-ts-linux-x64-gnu": "0.7.3",
-    "wicked-core-ts-win32-x64-msvc": "0.7.3"
+    "wicked-core-ts-darwin-arm64": "0.7.5",
+    "wicked-core-ts-darwin-x64": "0.7.5",
+    "wicked-core-ts-linux-arm64-gnu": "0.7.5",
+    "wicked-core-ts-linux-x64-gnu": "0.7.5",
+    "wicked-core-ts-win32-x64-msvc": "0.7.5"
   },
   "devDependencies": {
     "@napi-rs/cli": "^2.18.4"