@ontrails/warden 1.0.0-beta.15 → 1.0.0-beta.16

package/CHANGELOG.md

@@ -1,5 +1,136 @@
 # @ontrails/warden
 
+## 1.0.0-beta.16
+
+### Minor Changes
+
+- e991a5b: Add generic enum value aliases for CLI flags and migrate Warden command aliases onto the shared alias model.
+- 2e05e27: Add `--dev-permit` for local-development synthetic full-access. New `devPermitPreset()` exposes a boolean flag; when set, the CLI synthesizes a `BasePermit` (`id: 'dev-permit'`, scopes enumerated from every declared scope across the topo) and overlays it on `ctx.permit`. Mutually exclusive with `--permit` and `--token` — any combination fails with `ValidationError` listing the conflicting flags. New Warden rule `no-dev-permit-in-source` flags any committed source file containing `--dev-permit` as an error, with a tight allow-list (`packages/cli/src/flags.ts`, `packages/cli/src/build.ts`, the rule itself). The Warden runner still scans test TypeScript files for this literal while keeping unrelated source rules filtered out of tests. Apps that import `authResource`/`authLayer` are unaffected.
+- ad553a6: Add one warden rule coaching against the removed legacy layer API. `no-legacy-layer-imports` (error) flags any source-string reference to `authLayer`, `autoIterateLayer`, or `dateShortcutsLayer` and points the developer at the migration paths (CLI surface derivation for pagination/date-shortcuts; intrinsic permit enforcement for auth). Allow-list covers the migration notes in `packages/cli/src/{pagination,date-shortcuts}.ts` and the rule's own files. The rule is classified `lifecycle: temporary` with a `retireWhen` string tying it to the legacy layer migration window. Trail count bumps 45 → 46.
+- 802fdfc: Rename Warden guide manifest rule grouping from `category` to `concern` so the
+  public JSON contract matches the source metadata field.
+- 22c6c06: Accept ADR-0041 Unified Observability and ship the first activation and
+  observability primitives it depends on: activation trace records, topo-level
+  observe configuration, webhook activation materialization, signal/webhook
+  warden coaching, the `@ontrails/observe` package, sink composition, and
+  zero-dependency observe sinks.
+- 767eb41: Ship the default `warden` bin from `@ontrails/warden` and migrate the old private `apps/ci` runner into the package-local CLI surface.
+
+  The new bin supports `--ci`, `--pre-push`, `--depth`, `--fail-on`, `--strict`, `--format`, `--lock`, `--drafts`, `--apps`, and the Sprint 1 standalone aliases. CI output now uses the package Warden formatters directly, so GitHub annotations and JSON payloads follow the `@ontrails/warden` report shape instead of the retired `apps/ci` wrapper shape.
+
+- 82019a7: Export `wardenConfigSchema` for composing Warden options into `trails.config.ts`.
+- f6fdc62: Add structured Warden remediation guidance to rule metadata, diagnostics, report output, and the `trails warden` result schema.
+- a10ffa4: Add a Warden guide manifest projection and expose it through `trails warden guide` in markdown, agent-json, and manifest formats.
+- 7085f01: Add a Warden topo-aware rule that requires public MCP/HTTP surface-eligible trails to declare output schemas.
+- 8ddf5ff: Extend `runWarden` into the shared Warden orchestration entrypoint with effective config resolution, depth/fail thresholds, rule facets, and multi-topo report metadata.
+
+  Adapt the built-in `trails warden` wrapper to consume the readonly Warden report diagnostics contract without weakening its output schema.
+
+- f5b6112: Add an advisory Warden rule that prefers static resource helpers over dynamic context resource lookups when the resource definition is already in scope.
+
+### Patch Changes
+
+- c3fc5c3: Move previously root-exported helper contracts out of `src/internal/*` to stable core module homes, document their public boundary, and guard the public barrel against future internal re-exports.
+- e898cc4: Add repo-level Knip dead-code detection and remove stale internal exports and unused package dependencies surfaced by the new check.
+- 3395234: Move store adapter-binding helpers to `@ontrails/store/adapter-support` and topographer direct database/admin helpers to `@ontrails/topographer/backend-support`, keeping root exports focused on contract-level APIs.
+- d40430d: Remove the retired `@ontrails/logging` workspace from the prerelease package set. Use `@ontrails/observe` for log and trace sink contracts and `@ontrails/logtape` for LogTape forwarding.
+- de30d6c: Introduce `topo.compile` as the canonical trail for writing `.trails` lockfile
+  and surface artifacts, remove the `survey --generate` mode, and update drift
+  guidance to point at the compile command.
+- 331e3a9: Relocate the topo-store public API from `@ontrails/core` to `@ontrails/topographer` per ADR-0042. Generic `trails-db` helpers (`openReadTrailsDb`, `openWriteTrailsDb`, `ensureSubsystemSchema`, `deriveTrailsDbPath`, `deriveTrailsDir`) stay in core because tracing and other subsystems share them.
+
+  Breaking pre-1.0 beta change. Update consumer imports:
+
+  ```diff
+  - import { topoStore, createTopoStore, createMockTopoStore, createTopoSnapshot, listTopoSnapshots, pinTopoSnapshot, unpinTopoSnapshot, createStoredTopoSnapshot, getStoredTopoExport, countTopoSnapshots, countPinnedSnapshots, countPrunableSnapshots, pruneUnpinnedSnapshots } from '@ontrails/core';
+  + import { topoStore, createTopoStore, createMockTopoStore, createTopoSnapshot, listTopoSnapshots, pinTopoSnapshot, unpinTopoSnapshot } from '@ontrails/topographer';
+  + import { createStoredTopoSnapshot, getStoredTopoExport, countTopoSnapshots, countPinnedSnapshots, countPrunableSnapshots, pruneUnpinnedSnapshots } from '@ontrails/topographer/backend-support';
+  ```
+
+  The same root move applies to types `ReadOnlyTopoStore`, `MockTopoStoreSeed`, `TopoSnapshot`, `TopoStoreRef`, `TopoStoreExportRecord`, `TopoStoreResourceRecord`, `TopoStoreTrailRecord`, `TopoStoreTrailDetailRecord`, `CreateTopoSnapshotInput`, and `ListTopoSnapshotsOptions`. The direct DB helper type `StoredTopoExport` moves to `@ontrails/topographer/backend-support`.
+
+  Core newly exports `activationSourceKey`, `projectActivationSourceDeclaration`, `activationSourceDeclarationSignature`, and the `ActivationSourceProjection` type — these were already used internally and are now part of the public surface so `@ontrails/topographer` (the only consumer that needs them) can import them through normal package channels.
+
+- 4399fdb: Renamed `@ontrails/schema` to `@ontrails/topographer`. Mechanical rename only — no API changes. Update import sites from `@ontrails/schema` to `@ontrails/topographer`. See ADR-0042 for the durable graph substrate doctrine.
+- 2dd9cda: Promote ADR-0043 (Layer Evolution) from draft to accepted, amend it on 2026-05-04 to remove the briefly proposed `Middleware` split, and publish the Layer Evolution Migration Guide at `docs/migration/layer-evolution.md`.
+
+  Documentation-only change capturing the post-implementation state of the layer-evolution work shipped across TRL-471 through TRL-476: typed `Layer` primitive with optional `input` schema, three attachment scopes (trail, surface, topo), CLI/MCP/HTTP surface projection of layer inputs, removal of `authLayer`, `autoIterateLayer`, and `dateShortcutsLayer`, and warden coaching via `no-legacy-layer-imports` (error). The migration guide is the durable countermeasure to the vocabulary churn flagged in ADR-0043's tradeoffs.
+
+- fb10112: Polish Warden guidance projection by preserving labels in plain-text doc links
+  and reusing the shared diagnostic schema from the Trails CLI wrapper.
+- bfabe09: Suppress static resource accessor warnings when a string lookup resolves to a
+  resource variable name shadowed inside `blaze`.
+- 7a1d4a9: Rename the public resolved graph API from `SurfaceMap` to `TopoGraph`, including
+  the derive, hash, diff, and current graph artifact I/O helpers.
+- 84f595a: Add lock v3 manifest and `topo.lock` I/O. `trails.lock` now reads as a compact v3 manifest that points at the serialized TopoGraph artifact, and legacy v2/hash-only lock inputs fail with a regenerate instruction.
+- d2cb9ba: Rename topo-store export artifacts from surface-era names to TopoGraph names. The `topo_exports` table now stores `topo_graph`, `topo_graph_hash`, and `lock_manifest`, and backend-support export records expose `topoGraphJson`, `topoGraphHash`, and `lockManifestJson`.
+- 2cc05da: Harden Warden drift checks for lock v3 manifests. Malformed legacy lock files and manifests without the `topo.lock` artifact now report blocked drift with a regenerate instruction instead of throwing or silently passing.
+- df9a7d0: Add project-aware public export-map governance for @ontrails workspace docs,
+  imports, root barrels, and bin-only package surfaces.
+- 30a2c7e: Add the resolver-backed `resolved-import-boundary` Warden rule for cross-package import boundary enforcement.
+- 81bffec: Add Warden import-resolution substrate backed by `oxc-resolver`.
+- d675a53: Omit `topoNames` from Warden reports when no topo targets were governed, matching the optional report contract.
+- Updated dependencies [73622ae]
+- Updated dependencies [e991a5b]
+- Updated dependencies [25f3c5c]
+- Updated dependencies [6300f70]
+- Updated dependencies [d172013]
+- Updated dependencies [c3fc5c3]
+- Updated dependencies [20d7a5c]
+- Updated dependencies [be5fb46]
+- Updated dependencies [199304e]
+- Updated dependencies [e898cc4]
+- Updated dependencies [2bf239e]
+- Updated dependencies [200bece]
+- Updated dependencies [e4beec9]
+- Updated dependencies [3395234]
+- Updated dependencies [bcdc484]
+- Updated dependencies [6300f70]
+- Updated dependencies [3f678d4]
+- Updated dependencies [ed171d5]
+- Updated dependencies [49c2e7d]
+- Updated dependencies [de30d6c]
+- Updated dependencies [331e3a9]
+- Updated dependencies [c40865a]
+- Updated dependencies [4399fdb]
+- Updated dependencies [4b8d13b]
+- Updated dependencies [4b8d13b]
+- Updated dependencies [4b8d13b]
+- Updated dependencies [fbd42fc]
+- Updated dependencies [63d1aef]
+- Updated dependencies [6be2e95]
+- Updated dependencies [819de09]
+- Updated dependencies [be08686]
+- Updated dependencies [112b9f2]
+- Updated dependencies [893025e]
+- Updated dependencies [ed888e2]
+- Updated dependencies [2e05e27]
+- Updated dependencies [c8caa5e]
+- Updated dependencies [f4b90c9]
+- Updated dependencies [eec5e9d]
+- Updated dependencies [4e75129]
+- Updated dependencies [47505fe]
+- Updated dependencies [ebd4434]
+- Updated dependencies [863d473]
+- Updated dependencies [344f2f7]
+- Updated dependencies [26f9ffd]
+- Updated dependencies [66056ac]
+- Updated dependencies [b12e19b]
+- Updated dependencies [ed7f6f6]
+- Updated dependencies [0bad534]
+- Updated dependencies [7a1d4a9]
+- Updated dependencies [84f595a]
+- Updated dependencies [d2cb9ba]
+- Updated dependencies [10eae9a]
+- Updated dependencies [bbb1ea4]
+- Updated dependencies [22c6c06]
+- Updated dependencies [df9a7d0]
+  - @ontrails/core@1.0.0-beta.16
+  - @ontrails/cli@1.0.0-beta.16
+  - @ontrails/permits@1.0.0-beta.16
+  - @ontrails/store@1.0.0-beta.16
+  - @ontrails/topographer@1.0.0-beta.16
+
 ## 1.0.0-beta.15
 
 ### Minor Changes
@@ -16,7 +147,7 @@
 - Updated dependencies [4ad6b25]
   - @ontrails/core@1.0.0-beta.15
   - @ontrails/permits@1.0.0-beta.15
-  - @ontrails/schema@1.0.0-beta.15
+  - @ontrails/topographer@1.0.0-beta.15
 
 ## 1.0.0-beta.14
 

package/README.md

@@ -1,18 +1,23 @@
 # @ontrails/warden
 
-AST-based code convention rules for Trails. Built-in lint rules catch contract violations at development time, alongside lock drift detection and CI formatters.
+AST-based code convention rules for Trails. Built-in lint rules catch contract
+violations at development time, alongside lock drift detection and CI
+formatters.
 
-Structural checks (cross target existence, declared resource existence, recursive crossing, example schema validation) live in `validateTopo()` from `@ontrails/core`. Warden handles the code-level rules that need AST analysis.
+Structural checks (cross target existence, declared resource existence,
+recursive crossing, example schema validation) live in `validateTopo()` from
+`@ontrails/core`. Warden handles the code-level rules that need AST analysis.
+
+For rule-home boundaries and authoring doctrine, see the
+[Warden guide](../../docs/warden.md) and
+[Rule Design](../../docs/rule-design.md).
 
 ## Usage
 
 From the Trails CLI:
 
 ```bash
-trails warden              # Run all checks
-trails warden --exit-code  # Non-zero exit on errors or drift
-trails warden --lint-only  # Skip drift detection
-trails warden --drift-only # Skip lint rules
+bunx trails warden # Run all checks
 ```
 
 Or programmatically:
@@ -26,35 +31,33 @@ console.log(formatWardenReport(report));
 
 ## Rules
 
-| Rule | Severity | What it catches |
-| --- | --- | --- |
-| `no-throw-in-implementation` | error | `throw` inside blaze bodies |
-| `implementation-returns-result` | error | Blaze functions returning raw values instead of `Result` |
-| `context-no-surface-types` | error | Surface type imports (`Request`, `McpSession`) in trail files |
-| `no-sync-result-assumption` | error | Missing `await` on `.blaze()` results |
-| `valid-detour-contract` | error | Detours with non-constructor `on` values or non-callable `recover` values |
-| `no-throw-in-detour-recover` | error | `throw` inside detour `recover` functions |
-| `unreachable-detour-shadowing` | error | Later detours made unreachable by earlier same-or-broader `on:` error types |
-| `no-direct-implementation-call` | warn | Direct `.blaze()` calls bypassing `ctx.cross()` |
-| `no-direct-impl-in-route` | warn | Direct `.blaze()` calls inside trail bodies with `crosses` |
-| `prefer-schema-inference` | warn | Redundant field overrides already derivable from the schema |
-| `cross-declarations` | error/warn | `ctx.cross()` calls that drift from declared `crosses: [...]` |
-| `resource-declarations` | error/warn | `resource.from(ctx)` / `ctx.resource()` usage that drifts from declared `resources: [...]` |
-| `resource-exists` | error | Declared or referenced resource IDs that do not resolve in project context |
-| `valid-describe-refs` | warn | `@see` refs in `.describe()` that do not resolve |
-| `draft-file-marking` | error | Draft-bearing files missing `_draft.*` or `*.draft.*` filename markers |
-| `draft-visible-debt` | warn | Draft IDs remaining in source files that need promotion or removal |
+Built-in rules are registered in `wardenRules` and `wardenTopoRules`; use those
+registries or `wardenTopo.ids()` for the current rule list instead of copying a
+static table into docs.
+
+Rules cover several families:
+
+- blaze and `Result` contract checks
+- cross, fire, resource, and detour declaration drift
+- draft-state containment
+- source-static guardrails such as surface-type leakage
+- topo-aware checks that need the resolved graph or resource mock shape
+
+When adding or auditing rules, follow [Rule Design](../../docs/rule-design.md):
+name the invariant, import owner-held framework data, choose the narrowest
+Warden tier, and collapse families only when the data model, traversal, and
+diagnostic shape are shared.
 
 ## Drift detection
 
-Warden integrates with `@ontrails/schema` to detect when the topo has changed without updating the lock file:
+Warden integrates with `@ontrails/topographer` to detect when the topo has changed without updating the lock file:
 
 ```typescript
 import { checkDrift } from '@ontrails/warden';
 
 const drift = await checkDrift(process.cwd(), graph);
 if (drift.stale) {
-  console.log('lock file is stale -- regenerate with `trails topo export`');
+  console.log('lock file is stale -- regenerate with `trails topo compile`');
 }
 ```
 
@@ -66,19 +69,31 @@ Add to lefthook for pre-push enforcement:
 pre-push:
   commands:
     warden:
-      run: trails warden --exit-code
+      run: bunx trails warden
       tags: governance
 ```
 
 CI formatters for structured output:
 
 ```typescript
-import { formatGitHubAnnotations, formatJson, formatSummary } from '@ontrails/warden';
+import {
+  formatGitHubAnnotations,
+  formatJson,
+  formatSummary,
+} from '@ontrails/warden';
+```
+
+Parser helpers for rule authoring and repo-local tooling live on the dedicated
+AST entrypoint:
+
+```typescript
+import { findStringLiterals, parse, walk } from '@ontrails/warden/ast';
 ```
 
 ## Trail-based API
 
-Every built-in warden rule is also available as a composable trail. This makes rules queryable, testable, and invocable through any Trails surface.
+Every built-in warden rule is also available as a composable trail. This makes
+rules queryable, testable, and invocable through any Trails surface.
 
 ```typescript
 import {
@@ -100,7 +115,14 @@ const diagnostics = await runWardenTrails(filePath, sourceCode, {
 const topoDiagnostics = await runTopoAwareWardenTrails(myApp);
 ```
 
-To wrap a custom rule as a trail, use `wrapRule` (imported from `@ontrails/warden/trails/wrap-rule`). This is the same factory used internally to build all built-in rule trails.
+To wrap a custom rule as a trail, import `wrapRule` from the root package
+entrypoint:
+
+```typescript
+import { wrapRule } from '@ontrails/warden';
+```
+
+This is the same factory used internally to build all built-in rule trails.
 
 ## API
 
@@ -110,12 +132,24 @@ To wrap a custom rule as a trail, use `wrapRule` (imported from `@ontrails/warde
 | `formatWardenReport(report)` | Human-readable report |
 | `checkDrift(rootDir, topo?)` | Check if the lock file matches the current topo |
 | `wardenRules` | Registry of all built-in rules |
+| `builtinWardenRuleMetadata` | Tier, scope, lifecycle, and invariant metadata for built-in rules |
+| `getWardenRuleMetadata(ruleOrName)` | Resolve inline or built-in metadata for a Warden rule |
+| `listWardenRuleMetadata()` | List built-in rule metadata entries |
 | `wardenTopo` | `Topo` of all built-in rule trails (one per rule) |
 | `runWardenTrails(filePath, sourceCode, options?)` | Dispatch file-scoped rule trails for a file, collect diagnostics |
 | `runTopoAwareWardenTrails(topo)` | Dispatch built-in topo-aware rule trails once for a resolved topo |
 | `formatGitHubAnnotations(report)` | GitHub Actions annotation format |
 | `formatJson(report)` | Machine-readable JSON |
 | `formatSummary(report)` | Compact summary line |
+| `wrapRule(rule)` | Wrap a custom rule as a trail (same factory used for all built-in rule trails) |
+
+AST parser helpers are exported from `@ontrails/warden/ast`, not the root
+runtime barrel. The stable authoring surface includes `parse`, `walk`,
+`walkScope`, `offsetToLine`, `findTrailDefinitions`, `findBlazeBodies`,
+`findContourDefinitions`, `isBlazeCall`, and string-literal helpers.
+
+`runWarden({ tier })` can narrow a run to `source-static`, `project-static`,
+`topo-aware`, `drift`, or `advisory`. Omit `tier` for the default full run.
 
 See the [API Reference](../../docs/api-reference.md) for the full list.
 

package/bin/warden.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env bun
+/* oxlint-disable eslint-plugin-jest/require-hook -- CLI bin entrypoints execute at module scope */
+
+import { runWardenCommand } from '../src/command.js';
+
+const env = { ...process.env } as Record<string, string | undefined>;
+const result = await runWardenCommand({
+  args: Bun.argv.slice(2),
+  cwd: process.cwd(),
+  env,
+});
+
+if (result.output.length > 0) {
+  console.log(result.output);
+}
+
+const summaryPath = env['GITHUB_STEP_SUMMARY'];
+if (result.writeStepSummary && summaryPath !== undefined) {
+  await Bun.write(summaryPath, result.summary);
+}
+
+process.exit(result.exitCode);

package/package.json

@@ -1,9 +1,23 @@
 {
   "name": "@ontrails/warden",
-  "version": "1.0.0-beta.15",
+  "version": "1.0.0-beta.16",
+  "bin": {
+    "warden": "./bin/warden.ts"
+  },
+  "files": [
+    "bin/**/*.ts",
+    "src/**/*.ts",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
+    "./ast": "./src/ast.ts",
+    "./resolve": "./src/resolve.ts",
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -14,16 +28,19 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/permits": "^1.0.0-beta.14"
-  },
-  "devDependencies": {
-    "@ontrails/testing": "^1.0.0-beta.14",
-    "@oxc-project/types": "^0.122.0",
+    "@ontrails/cli": "^1.0.0-beta.15",
+    "@ontrails/permits": "^1.0.0-beta.15",
+    "@ontrails/store": "^1.0.0-beta.15",
     "oxc-parser": "^0.121.0",
+    "oxc-resolver": "11.19.1",
     "zod": "^4.3.5"
   },
+  "devDependencies": {
+    "@ontrails/config": "^1.0.0-beta.15",
+    "@ontrails/testing": "^1.0.0-beta.15"
+  },
   "peerDependencies": {
-    "@ontrails/core": "^1.0.0-beta.14",
-    "@ontrails/schema": "^1.0.0-beta.14"
+    "@ontrails/core": "^1.0.0-beta.15",
+    "@ontrails/topographer": "^1.0.0-beta.15"
   }
 }

package/src/ast.ts

@@ -0,0 +1,28 @@
+/**
+ * Public Warden AST helper surface.
+ *
+ * These helpers are the supported parser primitives for repo-local tooling and
+ * rule authoring. Broader Trails-aware discovery helpers stay internal to the
+ * built-in rule implementation until they have a stable public contract.
+ */
+export {
+  findBlazeBodies,
+  findContourDefinitions,
+  findStringLiterals,
+  findTrailDefinitions,
+  getStringValue,
+  isBlazeCall,
+  isStringLiteral,
+  offsetToLine,
+  parse,
+  walk,
+  walkScope,
+} from './rules/ast.js';
+export type {
+  AstNode,
+  ContourDefinition,
+  FindContourDefinitionsOptions,
+  FrameworkNamespaceContext,
+  StringLiteralMatch,
+  TrailDefinition,
+} from './rules/ast.js';