@ontrails/core 1.0.0-beta.30 → 1.0.0-beta.39

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # @ontrails/core
 
+## 1.0.0-beta.39
+
+### Patch Changes
+
+- [`f42ca6e`](https://github.com/outfitter-dev/trails/commit/f42ca6e40b29155acec446e5bf44e52e014466bd): Hard cutover: the CLI consumes `cli` bindings from the app-authored surfaces overlay. Scalar bindings behave identically to the removed cliAliases (parity-tested) — the binding name splits on `.` into a transparent synonym command path for exactly one trail. List bindings arrive as command groups: each expanded member trail gets a group-prefixed route that dispatches the member trail with its identity preserved, and a singleton list stays a group. Expansion is fail-fast boundary validation: a scalar binding resolving to zero or multiple trails, or a group with an empty member union, is a `ValidationError` naming the binding. `DeriveTopoGraphOptions.cliAliases`, the `cliAliases`/`trailsCliAliases` app-module export convention, and the per-kind compile lift are deleted; `deriveCliCommands`/`createProgram` take `overlays` instead of `aliases`, and both topo-graph derivation pipelines expand the same bindings through one shared helper so runtime CLI routes and lock routes come from one semantic. A leftover legacy export is now a Warden error (`no-legacy-cli-alias-export`) naming the `surfaceOverlay({ cli: { ... } })` rewrite.
+
+  This is a breaking API removal shipped under the lockstep beta patch convention (pre-1.0 hard-cutover posture, zero external adoption); the removed options have no deprecation window by design.
+
+- [`6b75a46`](https://github.com/outfitter-dev/trails/commit/6b75a46ab6210237d306cceade833bf9ce6e7431): The core barrel is now execution-portable: no eager `bun:`/`node:` builtin imports remain on its module graph (TRL-1198). `trails-db`, workspace discovery, and path security load `bun:sqlite`, `node:fs`, `node:os`, and `node:path` lazily through `process.getBuiltinModule` at first use, and signal payload summaries plus per-project store keys use a pure SHA-256 (output-identical to `node:crypto`). A Worker bundle no longer needs a `bun:sqlite` stub plugin or the `nodejs_compat` flag to serve trails; the Cloudflare adapter's miniflare lane now bundles without externals and boots workerd without `nodejs_compat` as the structural regression gate, and its README stub instructions are replaced with the portable posture. Tooling helpers throw a clear `InternalError` naming the missing builtin when called on runtimes without it.
+- [`81373bc`](https://github.com/outfitter-dev/trails/commit/81373bc5e980bb06d56fb06af4f0986f72e318c7): Wave-2 MCP cutover to the app-authored `surfaces` overlay. The overlay's `mcp` bindings are now the authored, lockable default for the MCP surface: a list binding derives one grouped trailhead tool (member selection in `{ trail, input }`, member identity preserved in `{ trail, output }`, deterministic derived description), and a scalar binding derives an additional tool synonym whose MCP-safe name is published verbatim and must expand to exactly one trail. `deriveMcpTools`/`createServer` accept the new `overlays` option; `@ontrails/core` gains `expandMcpSurfaceBindings` and `deriveMcpTrailheadDescription`.
+
+  The call-site `CreateServerOptions.trailheads` map survives as permanent override-in-context design, not a compatibility bridge: when both channels are present, the call-site map wins at runtime. Warden's new `trailhead-override-divergence` rule (warn) names both sides when a call-site map's binding names or member selectors diverge from the authored overlay default.
+
+  Topographer now derives `graph.trailheads` from the overlay's `mcp` list bindings in both `deriveTopoGraph` and the store-side graph build, so trailhead facts flow from compiled locks into Wayfinder reads for the first time. The never-wired `DeriveTopoGraphOptions.trailheads` option and the `TopoGraphTrailheadDeclaration`/`TopoGraphTrailheadTrailSelector` types are removed — a beta-window hard cutover of an option no caller could reach; author the equivalent `mcp` list binding in `surfaceOverlay({ mcp })` instead.
+
+- [`820b4ad`](https://github.com/outfitter-dev/trails/commit/820b4ad9c40ea383b3c489a05fe7e4b2328e324f): Add `surfaceOverlay` — the shared surface-naming schema (scalar binding = synonym, list binding = grouped entry, singleton list stays a group) with app-authored/adapter-derived overlay provenance enforced at collection and consumption, and the `surface-overlay-coherence` Warden rule. MCP tool-name derivation moves to `@ontrails/core` (`deriveMcpToolName`) so the surface and governance read one projection; `@ontrails/mcp`'s `deriveToolName` now delegates to it. The coherence rule activates on standard warden runs once fresh derivations collect app-module overlays through the shared compile channel (TRL-1209, next in this stack).
+- [`28d75fb`](https://github.com/outfitter-dev/trails/commit/28d75fbadecc62794f43957bc3aca11a4cf39c51): Add `forkVersion()` so fork version entries get typed blazes (TRL-1180). `TrailVersions` fixes every entry's generics to `unknown`, which left fork blazes with `unknown` input and forced authors to re-parse the already-validated value just to narrow it. `forkVersion({ input, output, blaze, ... })` threads the entry's own schemas into the blaze signature (including merged `composeInput` fields) and enforces the entry's output shape at compile time; the erasure back to `TrailVersionEntry` is sound because the fork pipeline validates raw input against the entry's own schema before dispatch. `TrailVersionForkSpec` is exported alongside it.
+- [`b9e82a3`](https://github.com/outfitter-dev/trails/commit/b9e82a33546356c93fbc302fb934a83f19f1c2c5): Webhook ingress v2 (TRL-1194, absorbing TRL-1174 and TRL-1175): store-verified, per-endpoint webhook ingress becomes framework-expressible. `webhook()` accepts dynamic path segments (`path: '/hooks/:endpoint'`) whose values are delivered as envelope fields, opt-in `rawBody: true` delivery (a non-JSON body is no longer a surface-level failure — the trail owns payload interpretation), an allowlisted `headers` list delivered lowercased, and `resources` that make `verify` resource-capable: the HTTP surface resolves the declared resources into a context for the verifier and releases them afterwards, so signature checks can reach stores holding per-endpoint secrets. Envelope-mode ingress responds 202 Accepted; classic static webhooks keep their exact-match, JSON-gated, 200 behavior. Core exports `parseWebhookPathParams`, `matchWebhookPath`, `webhookPathPatternsOverlap`, and `createResources`. The `webhook-route-collision` Warden rule now also flags dynamic patterns that overlap other webhook or derived routes, not just exact method/path duplicates.
+
+## 1.0.0-beta.38
+
+### Patch Changes
+
+- [`a105127`](https://github.com/outfitter-dev/trails/commit/a105127e5662ed9a6c245125f791fb0182da3f5e): Add the `@ontrails/cloudflare` adapter collection with its first two service subpaths. `@ontrails/cloudflare/workers` exports `createWorkersHandler`, a materializer producing the `{ fetch(request, env, ctx) }` Worker export on the shared HTTP fetch kernel, with an env bridge that re-resolves env-bound resources whenever a new Worker `env` arrives so no resource instance serves a request with a stale env. `@ontrails/cloudflare/kv` exports `cloudflareKv`, a resource definition wrapping a KV namespace binding (`get`/`put`/`delete`/`list` with TTL options) plus an in-memory `createMemoryKv` mock so `testAll` runs configuration-free.
+
+  `@ontrails/core` now guards the default trail context fields: `requestId` falls back to `crypto.randomUUID()` when the `Bun` global is absent, and `cwd`/`env` fall back to `'/'`/`{}` when `process` is absent, so trail execution works on runtimes like Cloudflare Workers.
+
+  `@ontrails/warden` registers the `@ontrails/cloudflare` public barrel in the repo-local `public-export-example-coverage` policy, requiring `@example` TSDoc coverage on `createWorkersHandler` and `cloudflareKv`.
+
+## 1.0.0-beta.37
+
+## 1.0.0-beta.36
+
+## 1.0.0-beta.35
+
+### Patch Changes
+
+- [`417bd84`](https://github.com/outfitter-dev/trails/commit/417bd8471d0f0f47ad5f33cd2ac1c606eccd72f8): Promote signal trace helpers from tracing compatibility code to core exports, and make tracing's memory sink wrapper use the observe-owned implementation.
+- [`a88114b`](https://github.com/outfitter-dev/trails/commit/a88114b4dd0772db6b58ecdb7671e4169e6bdca5): Expose stable typed topo diagnostics for missing references so downstream
+  migration tooling can consume validation results without parsing human messages.
+
+## 1.0.0-beta.34
+
+## 1.0.0-beta.33
+
+## 1.0.0-beta.32
+
+### Patch Changes
+
+- 3e5c0fc: Export shared diagnostic base types from core and align governance diagnostic
+  severity vocabulary across adapter checks, permits, and Warden.
+- f3c4fef: Export a shared `escapeRegExp` helper from core and migrate first-party callers off local copies.
+- cb0a9d8: Export shared workspace package discovery helpers from core and migrate first-party discovery callers.
+- 21c6dda: Rename topo and draft report types to `TopoDiagnostic` and `DraftDiagnostic`, with deprecated `TopoIssue` and `DraftFinding` aliases preserved for source compatibility.
+- fe72b84: Fold remaining Regrade and Warden scan-target surfaces onto the shared path-scope vocabulary.
+
+## 1.0.0-beta.31
+
+### Patch Changes
+
+- 4cd5d4e: Add shared glob, path-scope, and trail-id glob contracts for downstream Trails tooling.
+- 38907cc: Adopt the shared trail-id glob engine for surface filtering and Wayfinder entity filters so dotted `*`, `**`, and `?` patterns behave consistently across graph inspection and surface selection.
+
 ## 1.0.0-beta.30
 
 ## 1.0.0-beta.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/core",
-  "version": "1.0.0-beta.30",
+  "version": "1.0.0-beta.39",
   "files": [
     "src/**/*.ts",
     "!src/**/__tests__/**",

package/src/context.ts

@@ -21,11 +21,25 @@ export const passthroughTrace: TraceFn = async <T>(
   fn: () => T | Promise<T>
 ): Promise<T> => await fn();
 
+const defaultCwd = (): string =>
+  typeof process === 'undefined' ? '/' : process.cwd();
+
+const defaultEnv = (): Record<string, string | undefined> =>
+  typeof process === 'undefined'
+    ? {}
+    : (process.env as Record<string, string | undefined>);
+
+const defaultRequestId = (): string =>
+  typeof Bun === 'undefined' ? crypto.randomUUID() : Bun.randomUUIDv7();
+
 /**
  * Create a TrailContext with sensible defaults.
  *
- * - `requestId` defaults to `Bun.randomUUIDv7()` (sortable v7 UUID)
+ * - `requestId` defaults to `Bun.randomUUIDv7()` (sortable v7 UUID), falling
+ *   back to `crypto.randomUUID()` on runtimes without the `Bun` global
  * - `abortSignal` defaults to a fresh, non-aborted `AbortSignal`
+ * - `cwd`/`env` default to the `process` globals when available, and to
+ *   `'/'`/`{}` on runtimes without `process` (for example Cloudflare Workers)
  * - All other fields come from `overrides`
  */
 export const createTrailContext = (
@@ -33,10 +47,10 @@ export const createTrailContext = (
 ): TrailContext => {
   const ctx = {
     abortSignal: new AbortController().signal,
-    cwd: process.cwd(),
+    cwd: defaultCwd(),
     dryRun: false,
-    env: process.env as Record<string, string | undefined>,
-    requestId: Bun.randomUUIDv7(),
+    env: defaultEnv(),
+    requestId: defaultRequestId(),
     trace: passthroughTrace,
     ...overrides,
   } as MutableTrailContext;

package/src/derive.ts

@@ -145,7 +145,7 @@ const propagateDescription = (
   }
 };
 
-/** Step one level of optional/default unwrapping. Returns null if not a wrapper type. */
+/** Step one level of transparent wrapper unwrapping. Returns null if not a wrapper type. */
 const unwrapStep = (
   current: ZodInternals,
   state: {
@@ -155,10 +155,16 @@ const unwrapStep = (
   }
 ): ZodInternals | null => {
   const defType = current._zod.def['type'] as string;
-  if (defType !== 'optional' && defType !== 'default') {
+  if (
+    defType !== 'optional' &&
+    defType !== 'default' &&
+    defType !== 'readonly'
+  ) {
     return null;
   }
-  state.required = false;
+  if (defType !== 'readonly') {
+    state.required = false;
+  }
   if (defType === 'default') {
     state.defaultValue = current._zod.def['defaultValue'];
   }
@@ -376,6 +382,27 @@ const normalizeCliAlias = ({
   };
 };
 
+/**
+ * Convert app name + trail ID to an MCP-safe tool name.
+ *
+ * MCP tool names must be `[a-z0-9_]+`: the app name prefixes the trail id,
+ * dots and hyphens collapse to underscores, and everything lowercases. This
+ * is the one owner for the projection — the MCP surface renders tools with
+ * it and Warden checks binding-name collisions against it, so the two
+ * readers cannot drift.
+ *
+ * @example
+ * ```ts
+ * deriveMcpToolName('myapp', 'entity.show'); // "myapp_entity_show"
+ * deriveMcpToolName('dispatch', 'patch.search'); // "dispatch_patch_search"
+ * ```
+ */
+export const deriveMcpToolName = (appName: string, trailId: string): string => {
+  const prefix = appName.toLowerCase().replaceAll(/[.-]/g, '_');
+  const suffix = trailId.toLowerCase().replaceAll(/[.-]/g, '_');
+  return `${prefix}_${suffix}`;
+};
+
 /** Derive resolved CLI command routes for one trail. */
 export const deriveTrailCliCommandProjection = (
   trail: TrailCliProjectionInput,

package/src/diagnostics.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared diagnostic vocabulary for governance-style findings.
+ *
+ * Runtime side-channel records and field-state reports can still define their
+ * own shapes. This base exists for tools that report rule or check failures.
+ */
+
+export type DiagnosticSeverity = 'error' | 'warn';
+
+export interface DiagnosticBase<TCode extends string = string> {
+  readonly code?: TCode | undefined;
+  readonly message: string;
+  readonly severity: DiagnosticSeverity;
+}
+
+export interface RuleDiagnosticBase<
+  TCode extends string = string,
+  TRule extends string = string,
+> extends DiagnosticBase<TCode> {
+  readonly rule: TRule;
+}

package/src/draft.ts

@@ -25,7 +25,7 @@ export interface DraftDependency {
   readonly toId: string;
 }
 
-export interface DraftFinding {
+export interface DraftDiagnostic {
   readonly id: string;
   readonly kind: 'contour' | 'resource' | 'signal' | 'trail' | 'unknown';
   readonly message: string;
@@ -34,11 +34,19 @@ export interface DraftFinding {
   readonly dependsOn?: string | undefined;
 }
 
+/**
+ * @deprecated Use {@link DraftDiagnostic}. Kept as a source-compatible alias
+ * during the v1 vocabulary cutover.
+ */
+export interface DraftFinding extends DraftDiagnostic {
+  readonly id: DraftDiagnostic['id'];
+}
+
 export interface DraftReport {
   readonly contaminatedIds: ReadonlySet<string>;
   readonly declaredDraftIds: ReadonlySet<string>;
   readonly dependencies: readonly DraftDependency[];
-  readonly findings: readonly DraftFinding[];
+  readonly findings: readonly DraftDiagnostic[];
 }
 
 interface DraftReason {
@@ -120,7 +128,7 @@ const nodeKind = (
   trails: ReadonlyMap<string, AnyTrail>,
   signals: ReadonlyMap<string, AnySignal>,
   resources: ReadonlyMap<string, AnyResource>
-): DraftFinding['kind'] => {
+): DraftDiagnostic['kind'] => {
   if (contours.has(id)) {
     return 'contour';
   }
@@ -136,7 +144,7 @@ const nodeKind = (
   return 'unknown';
 };
 
-const displayKind = (kind: DraftFinding['kind']): string =>
+const displayKind = (kind: DraftDiagnostic['kind']): string =>
   kind === 'unknown' ? 'Node' : kind[0]?.toUpperCase() + kind.slice(1);
 
 const draftIdsFromKeys = (keys: Iterable<string>): string[] =>
@@ -152,8 +160,8 @@ const collectDeclaredDraftIds = (topo: Topo): ReadonlySet<string> =>
 
 const findingForDraftId = (
   id: string,
-  kind: DraftFinding['kind']
-): DraftFinding => ({
+  kind: DraftDiagnostic['kind']
+): DraftDiagnostic => ({
   id,
   kind,
   message: `${displayKind(id ? kind : 'unknown')} "${id}" is draft and cannot appear in the established graph.`,
@@ -162,9 +170,9 @@ const findingForDraftId = (
 
 const findingForContamination = (
   id: string,
-  kind: DraftFinding['kind'],
+  kind: DraftDiagnostic['kind'],
   reason: DraftReason
-): DraftFinding => {
+): DraftDiagnostic => {
   const dependencyLabel = isDraftId(reason.dependsOn)
     ? `draft "${reason.dependsOn}"`
     : `draft-contaminated "${reason.dependsOn}"`;
@@ -244,7 +252,7 @@ const contaminationFindingForId = (
   trails: ReadonlyMap<string, AnyTrail>,
   signals: ReadonlyMap<string, AnySignal>,
   resources: ReadonlyMap<string, AnyResource>
-): DraftFinding | undefined => {
+): DraftDiagnostic | undefined => {
   if (declaredDraftIds.has(id)) {
     return undefined;
   }
@@ -269,7 +277,7 @@ const collectFindings = (
   trails: ReadonlyMap<string, AnyTrail>,
   signals: ReadonlyMap<string, AnySignal>,
   resources: ReadonlyMap<string, AnyResource>
-): DraftFinding[] => [
+): DraftDiagnostic[] => [
   ...[...declaredDraftIds]
     .toSorted()
     .map((id) =>

package/src/glob.ts

@@ -0,0 +1,81 @@
+export interface GlobConfig {
+  readonly separator: '/' | '.';
+}
+
+/**
+ * Escape a literal string so it can be embedded safely in a RegExp source.
+ *
+ * @example
+ * ```ts
+ * const pattern = new RegExp(`^${escapeRegExp('@ontrails/core')}$`);
+ * ```
+ */
+export const escapeRegExp = (value: string): string =>
+  value.replaceAll(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+const separatorRegExp = (separator: GlobConfig['separator']): string =>
+  escapeRegExp(separator);
+
+export const globToRegExp = (pattern: string, config: GlobConfig): RegExp => {
+  const separator = separatorRegExp(config.separator);
+  const parts: string[] = ['^'];
+
+  for (let index = 0; index < pattern.length; index += 1) {
+    const char = pattern[index];
+    const next = pattern[index + 1];
+
+    if (char === '*' && next === '*') {
+      if (pattern[index + 2] === config.separator) {
+        parts.push(`(?:.*${separator})?`);
+        index += 2;
+      } else {
+        parts.push('.*');
+        index += 1;
+      }
+      continue;
+    }
+
+    if (char === '*') {
+      parts.push(`[^${separator}]*`);
+      continue;
+    }
+
+    if (char === '?') {
+      parts.push(`[^${separator}]`);
+      continue;
+    }
+
+    parts.push(escapeRegExp(char ?? ''));
+  }
+
+  parts.push('$');
+  return new RegExp(parts.join(''));
+};
+
+export const matchesGlob = (
+  value: string,
+  pattern: string,
+  config: GlobConfig
+): boolean => {
+  if (value === pattern) {
+    return true;
+  }
+
+  const terminalDoubleStar = `${config.separator}**`;
+  if (pattern.endsWith(terminalDoubleStar)) {
+    const parent = pattern.slice(0, -terminalDoubleStar.length);
+    if (value === parent) {
+      return true;
+    }
+  }
+
+  return globToRegExp(pattern, config).test(value);
+};
+
+export const matchesAnyGlob = (
+  value: string,
+  patterns: readonly string[] | undefined,
+  config: GlobConfig
+): boolean =>
+  patterns !== undefined &&
+  patterns.some((pattern) => matchesGlob(value, pattern, config));

package/src/index.ts

@@ -68,6 +68,11 @@ export {
   redactErrorString,
 } from './error-projection.js';
 export type { ErrorDiagnosticsProjection } from './error-projection.js';
+export type {
+  DiagnosticBase,
+  DiagnosticSeverity,
+  RuleDiagnosticBase,
+} from './diagnostics.js';
 
 // Types
 export type {
@@ -112,6 +117,25 @@ export type {
 // Context factory
 export { createTrailContext, passthroughTrace } from './context.js';
 
+// Glob and path scope
+export {
+  escapeRegExp,
+  globToRegExp,
+  matchesAnyGlob,
+  matchesGlob,
+} from './glob.js';
+export type { GlobConfig } from './glob.js';
+export {
+  includedByPathScope,
+  matchesAnyPathGlob,
+  matchesPathGlob,
+  normalizePathScopePath,
+  pathScopeSchema,
+} from './path-scope.js';
+export type { PathGlob, PathScope, ScanTargets } from './path-scope.js';
+export { matchesAnyTrailIdGlob, matchesTrailIdGlob } from './trail-id-glob.js';
+export type { TrailIdGlob } from './trail-id-glob.js';
+
 // Resource
 export {
   createResourceLookup,
@@ -119,8 +143,13 @@ export {
   isResource,
   resource,
 } from './resource.js';
-export { drainResources, resolveResourceConfig } from './resource-config.js';
+export {
+  createResources,
+  drainResources,
+  resolveResourceConfig,
+} from './resource-config.js';
 export type {
+  ResolvedResourceScope,
   ResourceConfigValues,
   ResourceDrainReport,
 } from './resource-config.js';
@@ -162,6 +191,7 @@ export {
 export type { ActivationSourceProjection } from './activation-source-projection.js';
 export {
   deriveSupportedTrailVersions,
+  forkVersion,
   getTrailVersionEntryKind,
   hasDeprecatedTrailVersionGuidance,
   intentValues,
@@ -200,6 +230,7 @@ export type {
   TrailVersionArchivedStatus,
   TrailVersionDeprecatedStatus,
   TrailVersionForkEntry,
+  TrailVersionForkSpec,
   TrailVersionRevisionEntry,
   TrailVersions,
   TrailVersionStatus,
@@ -278,10 +309,13 @@ export type {
 export {
   getWebhookHeader,
   getWebhookHeaders,
+  matchWebhookPath,
+  parseWebhookPathParams,
   validateWebhookSource,
   verifyWebhookRequest,
   webhook,
   webhookMethods,
+  webhookPathPatternsOverlap,
 } from './webhook.js';
 export type {
   WebhookMethod,
@@ -386,6 +420,31 @@ export type {
 export { topo } from './topo.js';
 export type { Topo, TopoIdentity } from './topo.js';
 
+// Surface overlay
+export {
+  SURFACES_OVERLAY_NAMESPACE,
+  classifySurfaceBinding,
+  deriveMcpTrailheadDescription,
+  expandCliSurfaceBindings,
+  expandMcpSurfaceBindings,
+  resolveSurfaceOverlayBindings,
+  surfaceBindingsFromLockOverlays,
+  surfaceOverlay,
+  surfaceOverlayBindingsSchema,
+} from './surface-overlay.js';
+export type {
+  CliSurfaceBindingAliases,
+  McpSurfaceBindingExpansion,
+  OverlayEnvelopeLike,
+  OverlayProvenance,
+  SurfaceBindingRef,
+  SurfaceBindingShape,
+  SurfaceBindingValue,
+  SurfaceBindings,
+  SurfaceOverlay,
+  SurfaceOverlayBindings,
+} from './surface-overlay.js';
+
 // Generic trails-db helpers (shared framework infrastructure per ADR-0014).
 // The topo-store public API that previously lived here moved to
 // `@ontrails/topographer` per ADR-0042.
@@ -417,13 +476,21 @@ export {
 export type {
   DraftDependency,
   DraftDependencyKind,
+  DraftDiagnostic,
   DraftFinding,
   DraftReport,
 } from './draft.js';
 
 // Topo validation
-export { validateTopo } from './validate-topo.js';
-export type { TopoIssue } from './validate-topo.js';
+export { getTopoDiagnostics, validateTopo } from './validate-topo.js';
+export type {
+  TopoDiagnostic,
+  TopoDiagnosticCode,
+  TopoIssue,
+  TopoMissingReference,
+  TopoReferenceKind,
+  TopoReferenceOwnerKind,
+} from './validate-topo.js';
 export { validateEstablishedTopo } from './validate-established-topo.js';
 
 // Layer
@@ -448,6 +515,7 @@ export type {
 export {
   deriveCliPath,
   deriveFields,
+  deriveMcpToolName,
   deriveTrailCliCommandProjection,
   normalizeCliCommandPath,
 } from './derive.js';
@@ -481,6 +549,7 @@ export type { ExecuteTrailOptions } from './execute.js';
 export {
   clearTraceSink,
   createActivationTraceRecord,
+  createSignalTraceRecord,
   createTraceRecord,
   getTraceContext,
   getTraceSink,
@@ -489,6 +558,7 @@ export {
   TRACE_CONTEXT_KEY,
   traceContextFromRecord,
   writeActivationTraceRecord,
+  writeSignalTraceRecord,
 } from './tracing.js';
 export type {
   ActivationTraceRecordName,
@@ -581,10 +651,15 @@ export { securePath, isPathSafe, deriveSafePath } from './path-security.js';
 
 // Workspace
 export {
+  deriveRelativePath,
+  findWorkspacePackage,
   findWorkspaceRoot,
   isInsideWorkspace,
-  deriveRelativePath,
+  listWorkspacePackageDirs,
+  listWorkspacePackages,
+  listWorkspacePatterns,
 } from './workspace.js';
+export type { WorkspacePackage, WorkspaceRootManifest } from './workspace.js';
 
 // Blob
 export {

package/src/path-scope.ts

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+
+import { matchesAnyGlob, matchesGlob } from './glob.js';
+
+declare const pathGlobBrand: unique symbol;
+
+export type PathGlob = string & {
+  readonly [pathGlobBrand]: 'PathGlob';
+};
+
+export const normalizePathScopePath = (value: string): string =>
+  value.replaceAll('\\', '/').replace(/^\.\//, '');
+
+export const matchesPathGlob = (path: string, pattern: string): boolean =>
+  matchesGlob(normalizePathScopePath(path), normalizePathScopePath(pattern), {
+    separator: '/',
+  });
+
+export const matchesAnyPathGlob = (
+  path: string,
+  patterns: readonly string[] | undefined
+): boolean =>
+  matchesAnyGlob(
+    normalizePathScopePath(path),
+    patterns?.map(normalizePathScopePath),
+    { separator: '/' }
+  );
+
+const pathGlobArraySchema = z.array(z.string()).readonly();
+
+export const pathScopeSchema = z
+  .object({
+    exclude: pathGlobArraySchema.optional(),
+    extensions: z.array(z.string()).readonly().optional(),
+    include: pathGlobArraySchema.optional(),
+  })
+  .strict();
+
+export type PathScope = z.output<typeof pathScopeSchema>;
+
+export type ScanTargets = Pick<PathScope, 'exclude' | 'extensions'>;
+
+const extensionOf = (path: string): string => {
+  const normalized = normalizePathScopePath(path);
+  const name = normalized.slice(normalized.lastIndexOf('/') + 1);
+  const dot = name.lastIndexOf('.');
+  return dot <= 0 ? '' : name.slice(dot);
+};
+
+const normalizeExtension = (extension: string): string =>
+  extension === '' || extension.startsWith('.') ? extension : `.${extension}`;
+
+const includedByExtension = (
+  path: string,
+  extensions: readonly string[] | undefined
+): boolean =>
+  extensions === undefined ||
+  extensions.length === 0 ||
+  extensions.map(normalizeExtension).includes(extensionOf(path));
+
+export const includedByPathScope = (path: string, scope?: PathScope): boolean =>
+  (scope?.include === undefined ||
+    scope.include.length === 0 ||
+    matchesAnyPathGlob(path, scope.include)) &&
+  !matchesAnyPathGlob(path, scope?.exclude) &&
+  includedByExtension(path, scope?.extensions);

package/src/path-security.ts

@@ -4,10 +4,14 @@
  * All functions are runtime-agnostic (Node / Bun compatible).
  */
 
-import { resolve, relative, normalize, isAbsolute } from 'node:path';
-
 import { PermissionError } from './errors.js';
 import { Result } from './result.js';
+// Path security guards filesystem access on tooling paths: node:path
+// loads lazily at first use so the core barrel's module graph stays
+// execution-portable on runtimes without node: builtins (TRL-1198).
+import { loadRuntimeBuiltin } from './runtime-builtins.js';
+
+const nodePath = () => loadRuntimeBuiltin('node:path');
 
 // ---------------------------------------------------------------------------
 // Internal
@@ -15,6 +19,7 @@ import { Result } from './result.js';
 
 /** Returns true when `target` is equal to or a descendant of `base`. */
 const isWithin = (base: string, target: string): boolean => {
+  const { isAbsolute, relative } = nodePath();
   const rel = relative(base, target);
   // Empty string means they are the same directory.
   // A relative path starting with ".." means it escapes.
@@ -39,6 +44,7 @@ export const securePath = (
   basePath: string,
   userPath: string
 ): Result<string, PermissionError> => {
+  const { resolve } = nodePath();
   const base = resolve(basePath);
   const resolved = resolve(base, userPath);
 
@@ -61,6 +67,7 @@ export const securePath = (
  * `basePath`.
  */
 export const isPathSafe = (basePath: string, userPath: string): boolean => {
+  const { resolve } = nodePath();
   const base = resolve(basePath);
   const resolved = resolve(base, userPath);
   return isWithin(base, resolved);
@@ -74,6 +81,7 @@ export const deriveSafePath = (
   basePath: string,
   ...segments: string[]
 ): Result<string, PermissionError> => {
+  const { normalize, resolve } = nodePath();
   const base = resolve(basePath);
   const joined = resolve(base, ...segments.map((s) => normalize(s)));