@ontrails/trails 1.0.0-beta.42 → 1.0.0-beta.45

package/src/release/native-bun-registry.ts

@@ -43,6 +43,7 @@ export type RegistryResult =
       readonly status: 'published';
       readonly version: string;
       readonly versionPublished: boolean | undefined;
+      readonly versionProof?: RegistryVersionProof | undefined;
       readonly workspaceVersion: string;
     }
   | {
@@ -82,18 +83,20 @@ export interface PackageRegistryFacts {
   readonly error?: string | undefined;
 }
 
+/** Consumer-facing evidence for an exact package version. */
+export type RegistryVersionProof =
+  | { readonly kind: 'consumer-pack'; readonly published: true }
+  | { readonly kind: 'exact-metadata'; readonly published: true }
+  | { readonly kind: 'unavailable'; readonly published: false };
+
 /**
  * Classify a package's registry state from two orthogonal facts — whether the
  * target version is published, and where the dist-tag points relative to it —
  * plus reachability. Members are mutually exclusive by construction.
  *
- * `versionPublished` is read strictly only in the behind-tag case: a behind tag
- * becomes a `needs-tag-repair` only when the target is known published (`true`);
- * `undefined` or `false` route to `needs-publish`, preserving the conservative
- * release-policy behavior. When the tag already points at the target, an
- * unprobed (`undefined`) state counts as published and yields `complete`, which
- * matches the policy `versionPublished ?? true` default. `undefined` means the
- * exact-version probe was not run, including policy inputs and compatibility
+ * `complete` requires affirmative consumer proof. A matching dist-tag cannot
+ * substitute for exact-version metadata or an equivalent package fetch.
+ * `undefined` means the consumer probe was not run, including compatibility
  * callers that supply an injected registry view without a version probe.
  */
 export const classifyPackageRegistryState = (
@@ -120,9 +123,9 @@ export const classifyPackageRegistryState = (
     return { currentTagVersion: expectedTagVersion, kind: 'tag-points-ahead' };
   }
   if (tagAtTarget) {
-    return versionPublished === false
-      ? { kind: 'needs-publish' }
-      : { kind: 'complete' };
+    return versionPublished === true
+      ? { kind: 'complete' }
+      : { kind: 'needs-publish' };
   }
   if (versionPublished === true) {
     return { currentTagVersion: expectedTagVersion, kind: 'needs-tag-repair' };
@@ -131,13 +134,16 @@ export const classifyPackageRegistryState = (
 };
 
 /** Map a registry probe result into the classifier's fact shape. */
-const factsFromResult = (result: RegistryResult): PackageRegistryFacts => {
+export const factsFromRegistryResult = (
+  result: RegistryResult
+): PackageRegistryFacts => {
   if (result.status === 'published') {
     return {
       expectedTagVersion: result.expectedTagVersion,
       status: 'published',
       targetVersion: result.workspaceVersion,
-      versionPublished: result.versionPublished,
+      versionPublished:
+        result.versionProof?.published ?? result.versionPublished,
     };
   }
   if (result.status === 'inaccessible') {
@@ -165,7 +171,8 @@ Options:
   --tag <tag>            Expected npm dist-tag. Defaults to .changeset/pre.json
                          tag while in prerelease mode, otherwise "latest".
   --require-published    Fail when any workspace package is missing from npm.
-                         Use after publication to verify every package exists.
+                         Use after publication to require exact metadata or
+                         equivalent consumer package-fetch proof.
   -h, --help             Show this help and exit.
 
 Exit codes: 0 success, 1 registry posture failure, 2 arg-parse error.`;
@@ -459,12 +466,23 @@ export type RegistryVersionView = (
   version: string
 ) => Promise<boolean | undefined>;
 
+/** Probe with evidence that distinguishes metadata from package fetch proof. */
+export type RegistryVersionProofView = (
+  name: string,
+  version: string
+) => Promise<RegistryVersionProof>;
+
+export type RegistryVersionProbeView = (
+  name: string,
+  version: string
+) => Promise<boolean | RegistryVersionProof | undefined>;
+
 const UNKNOWN_REGISTRY_VERSION_STATE: { readonly published?: boolean } = {};
 const unknownRegistryVersionView: RegistryVersionView = async () =>
   UNKNOWN_REGISTRY_VERSION_STATE.published;
 
-export const createNpmRegistryVersionView =
-  (runNpm: NpmCommandRunner = runNpmCommand): RegistryVersionView =>
+export const createNpmRegistryVersionProofView =
+  (runNpm: NpmCommandRunner = runNpmCommand): RegistryVersionProofView =>
   async (name, version) => {
     const { exitCode, stderr, stdout } = await runNpm([
       'view',
@@ -474,12 +492,14 @@ export const createNpmRegistryVersionView =
     ]);
 
     if (exitCode === 0) {
-      return JSON.parse(stdout.trim()) === version;
+      return JSON.parse(stdout.trim()) === version
+        ? { kind: 'exact-metadata', published: true }
+        : { kind: 'unavailable', published: false };
     }
-    if (isNpmExactVersionMissingOutput(stdout, stderr)) {
-      return false;
-    }
-    if (!isNpmNotFoundOutput(stdout, stderr)) {
+    if (
+      !isNpmExactVersionMissingOutput(stdout, stderr) &&
+      !isNpmNotFoundOutput(stdout, stderr)
+    ) {
       throw new Error(
         stderr.trim() || `npm view failed for ${name}@${version}`
       );
@@ -496,21 +516,35 @@ export const createNpmRegistryVersionView =
         packResult.stdout,
         name,
         version
-      );
+      )
+        ? { kind: 'consumer-pack', published: true }
+        : { kind: 'unavailable', published: false };
     }
     if (isNpmExactVersionMissingOutput(packResult.stdout, packResult.stderr)) {
-      return false;
+      return { kind: 'unavailable', published: false };
     }
     if (isNpmNotFoundOutput(packResult.stdout, packResult.stderr)) {
-      return false;
+      return { kind: 'unavailable', published: false };
     }
     throw new Error(
       packResult.stderr.trim() || `npm pack failed for ${name}@${version}`
     );
   };
 
+export const createNpmRegistryVersionView = (
+  runNpm: NpmCommandRunner = runNpmCommand
+): RegistryVersionView => {
+  const proofView = createNpmRegistryVersionProofView(runNpm);
+  return async (name, version) => {
+    const proof = await proofView(name, version);
+    return proof.published;
+  };
+};
+
 export const npmRegistryVersionView: RegistryVersionView =
   createNpmRegistryVersionView();
+export const npmRegistryVersionProofView: RegistryVersionProofView =
+  createNpmRegistryVersionProofView();
 
 /** Run async tasks with a bounded number in flight, preserving input order. */
 const mapBounded = async <T, R>(
@@ -536,7 +570,7 @@ const mapBounded = async <T, R>(
 const checkWorkspaceRegistryPosture = async (
   workspace: RegistryWorkspace,
   view: RegistryView,
-  versionView: RegistryVersionView,
+  versionView: RegistryVersionProbeView,
   expectedTag: string
 ): Promise<RegistryResult> => {
   try {
@@ -549,13 +583,19 @@ const checkWorkspaceRegistryPosture = async (
       };
     }
     const distTags = registry['dist-tags'] ?? {};
+    const versionProbe = await versionView(workspace.name, workspace.version);
+    const versionProof =
+      typeof versionProbe === 'object' ? versionProbe : undefined;
+    const versionPublished =
+      typeof versionProbe === 'object' ? versionProbe.published : versionProbe;
     return {
       distTags,
       expectedTagVersion: distTags[expectedTag],
       name: workspace.name,
       status: 'published',
       version: registry.version ?? '(unknown)',
-      versionPublished: await versionView(workspace.name, workspace.version),
+      ...(versionProof === undefined ? {} : { versionProof }),
+      versionPublished,
       workspaceVersion: workspace.version,
     };
   } catch (error) {
@@ -569,14 +609,14 @@ const checkWorkspaceRegistryPosture = async (
 };
 
 type CheckRegistryPostureArgs =
-  | readonly [versionView: RegistryVersionView, expectedTag: string]
+  | readonly [versionView: RegistryVersionProbeView, expectedTag: string]
   | readonly [expectedTag: string];
 
 const normalizeCheckRegistryPostureArgs = (
   args: CheckRegistryPostureArgs
 ): {
   readonly expectedTag: string;
-  readonly versionView: RegistryVersionView;
+  readonly versionView: RegistryVersionProbeView;
 } => {
   if (args.length === 1) {
     return { expectedTag: args[0], versionView: unknownRegistryVersionView };
@@ -592,7 +632,7 @@ export function checkRegistryPosture(
 export function checkRegistryPosture(
   workspaces: readonly RegistryWorkspace[],
   view: RegistryView,
-  versionView: RegistryVersionView,
+  versionView: RegistryVersionProbeView,
   expectedTag: string
 ): Promise<RegistryResult[]>;
 export async function checkRegistryPosture(
@@ -624,6 +664,19 @@ const normalizeRegistryCheckPhase = (
   return phaseOrRequirePublished ? 'published' : 'ready';
 };
 
+const targetVersionFailure = (result: RegistryResult): string => {
+  if (result.status !== 'published') {
+    return 'is not published';
+  }
+  if (result.versionProof?.kind === 'unavailable') {
+    return 'lacks exact-version metadata and consumer pack proof';
+  }
+  if (result.versionPublished === undefined) {
+    return 'publish state was not probed';
+  }
+  return 'is not published';
+};
+
 export const registryPostureErrors = (
   results: readonly RegistryResult[],
   expectedTag: string,
@@ -632,7 +685,7 @@ export const registryPostureErrors = (
   const phase = normalizeRegistryCheckPhase(phaseOrRequirePublished);
   const errors: string[] = [];
   for (const result of results) {
-    const state = classifyPackageRegistryState(factsFromResult(result));
+    const state = classifyPackageRegistryState(factsFromRegistryResult(result));
     if (state.kind === 'registry-inaccessible') {
       errors.push(`${result.name}: registry probe failed: ${state.error}`);
       continue;
@@ -649,12 +702,8 @@ export const registryPostureErrors = (
     if (state.kind === 'first-time-package') {
       errors.push(`${result.name}: package is missing from the registry`);
     } else if (state.kind === 'needs-publish') {
-      const targetState =
-        result.status === 'published' && result.versionPublished === undefined
-          ? 'publish state was not probed'
-          : 'is not published';
       errors.push(
-        `${result.name}: target version ${result.workspaceVersion} ${targetState}`
+        `${result.name}: target version ${result.workspaceVersion} ${targetVersionFailure(result)}`
       );
     } else if (state.kind === 'needs-tag-repair') {
       errors.push(
@@ -673,8 +722,18 @@ export const formatDistTagSummary = (
   );
 
 const formatTargetVersionStatus = (
+  proof: RegistryVersionProof | undefined,
   versionPublished: boolean | undefined
 ): string => {
+  if (proof?.kind === 'exact-metadata') {
+    return 'exact-version metadata available';
+  }
+  if (proof?.kind === 'consumer-pack') {
+    return 'exact-version metadata unavailable, consumer pack available';
+  }
+  if (proof?.kind === 'unavailable') {
+    return 'exact-version metadata and consumer pack unavailable';
+  }
   if (versionPublished === true) {
     return 'target version published';
   }
@@ -691,7 +750,10 @@ const printResults = (
   console.log(`Registry preflight for dist-tag "${expectedTag}"`);
   for (const result of results) {
     if (result.status === 'published') {
-      const targetStatus = formatTargetVersionStatus(result.versionPublished);
+      const targetStatus = formatTargetVersionStatus(
+        result.versionProof,
+        result.versionPublished
+      );
       console.log(
         `✓ ${result.name}@${result.workspaceVersion}: package exists, ${targetStatus} (registry version ${result.version}, expected ${expectedTag}=${result.expectedTagVersion ?? 'missing'}, tags ${formatDistTagSummary(result.distTags)})`
       );
@@ -709,11 +771,14 @@ const normalizeRegistryPreflightViews = (
   view: RegistryView | undefined,
   versionView: RegistryVersionView | undefined
 ): {
-  readonly versionView: RegistryVersionView;
+  readonly versionView: RegistryVersionProbeView;
   readonly view: RegistryView;
 } => {
   if (view === undefined) {
-    return { versionView: npmRegistryVersionView, view: npmRegistryView };
+    return {
+      versionView: npmRegistryVersionProofView,
+      view: npmRegistryView,
+    };
   }
   return { versionView: versionView ?? unknownRegistryVersionView, view };
 };

package/src/release/package-route-facts.ts

@@ -0,0 +1,146 @@
+import { listGovernedVocabularyTransitions } from '@ontrails/warden';
+
+import type { WorkspaceInfo } from './check.js';
+
+export interface PackageRouteReleaseFact {
+  readonly kind: 'classified' | 'single';
+  readonly sourcePackage: string;
+  readonly targetPackage?: string;
+  readonly transitionId: string;
+}
+
+export interface PackageRouteReleaseDiagnostic {
+  readonly code:
+    | 'missing-governed-package-route'
+    | 'missing-governed-package-route-target';
+  readonly message: string;
+  readonly sourcePackage: string;
+}
+
+export interface PackageRouteReleaseIntent {
+  readonly eligiblePackages: readonly string[];
+  readonly sourcePackage: string;
+}
+
+const isPublishableTrailsPackage = (workspace: WorkspaceInfo): boolean =>
+  !workspace.isPrivate && workspace.name.startsWith('@ontrails/');
+
+const findPackageRouteTransition = (
+  transitions: ReturnType<typeof listGovernedVocabularyTransitions>,
+  sourcePackage: string
+) => {
+  const direct = transitions.find(
+    (transition) => transition.from === sourcePackage
+  );
+
+  if (direct) {
+    return { target: direct.target, transition: direct };
+  }
+
+  for (const transition of transitions) {
+    const moduleSpecifierRoute = transition.stringLiteralRenames.find(
+      (route) =>
+        route.from === sourcePackage &&
+        route.moduleSpecifier?.targetPackage !== undefined
+    );
+
+    if (moduleSpecifierRoute?.moduleSpecifier?.targetPackage) {
+      return {
+        target: {
+          kind: 'single' as const,
+          to: moduleSpecifierRoute.moduleSpecifier.targetPackage,
+        },
+        transition,
+      };
+    }
+  }
+
+  return null;
+};
+
+export const findPackageRouteReleaseFacts = ({
+  baseWorkspaces,
+  workspaces,
+}: {
+  readonly baseWorkspaces: readonly WorkspaceInfo[];
+  readonly workspaces: readonly WorkspaceInfo[];
+}): {
+  readonly diagnostics: readonly PackageRouteReleaseDiagnostic[];
+  readonly facts: readonly PackageRouteReleaseFact[];
+  readonly intents: readonly PackageRouteReleaseIntent[];
+} => {
+  const currentPackages = new Set(
+    workspaces
+      .filter(isPublishableTrailsPackage)
+      .map((workspace) => workspace.name)
+  );
+  const removedPackages = baseWorkspaces
+    .filter(isPublishableTrailsPackage)
+    .map((workspace) => workspace.name)
+    .filter((name) => !currentPackages.has(name))
+    .toSorted();
+  const transitions = listGovernedVocabularyTransitions();
+  const diagnostics: PackageRouteReleaseDiagnostic[] = [];
+  const facts: PackageRouteReleaseFact[] = [];
+  const intents: PackageRouteReleaseIntent[] = [];
+
+  for (const sourcePackage of removedPackages) {
+    const resolvedRoute = findPackageRouteTransition(
+      transitions,
+      sourcePackage
+    );
+
+    if (!resolvedRoute) {
+      diagnostics.push({
+        code: 'missing-governed-package-route',
+        message: `Public package removal '${sourcePackage}' requires an exact governed Regrade route. Add the route to the governed transition registry, then run trails regrade plan/check.`,
+        sourcePackage,
+      });
+      continue;
+    }
+
+    const { target, transition } = resolvedRoute;
+
+    if (target.kind === 'classified') {
+      const classifiedTarget = target;
+      const eligiblePackages = [...currentPackages]
+        .filter((packageName) =>
+          classifiedTarget.options.some(
+            (option) =>
+              option.to === packageName ||
+              option.to.startsWith(`${packageName}/`)
+          )
+        )
+        .toSorted();
+      facts.push({
+        kind: 'classified',
+        sourcePackage,
+        transitionId: transition.id,
+      });
+      intents.push({ eligiblePackages, sourcePackage });
+      continue;
+    }
+
+    if (!currentPackages.has(target.to)) {
+      diagnostics.push({
+        code: 'missing-governed-package-route-target',
+        message: `Governed Regrade route '${transition.id}' maps '${sourcePackage}' to '${target.to}', but that publishable target package is absent. Add the target package before applying the route, or use a classified transition with an explicit non-migratable reason for a multi-owner fold.`,
+        sourcePackage,
+      });
+      continue;
+    }
+
+    facts.push({
+      kind: 'single',
+      sourcePackage,
+      targetPackage: target.to,
+      transitionId: transition.id,
+    });
+    intents.push({
+      eligiblePackages: [target.to],
+      sourcePackage,
+    });
+  }
+
+  return { diagnostics, facts, intents };
+};

package/src/release/policy.ts

@@ -999,13 +999,13 @@ const registryPackagesFromResults = (
 const readRegistryPackages = async (
   distTag: string
 ): Promise<readonly ReleasePolicyRegistryPackage[]> => {
-  const { checkRegistryPosture, npmRegistryView, npmRegistryVersionView } =
+  const { checkRegistryPosture, npmRegistryView, npmRegistryVersionProofView } =
     await import('./native-bun-registry.js');
   const workspaces = await discoverRegistryWorkspaces(repoRoot);
   const results = await checkRegistryPosture(
     workspaces,
     npmRegistryView,
-    npmRegistryVersionView,
+    npmRegistryVersionProofView,
     distTag
   );
   return registryPackagesFromResults(results);

package/src/run-completions-install.ts

@@ -12,7 +12,7 @@ import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 
 import {
-  projectPublicSurfaceError,
+  renderPublicSurfaceError,
   Result,
   ValidationError,
 } from '@ontrails/core';
@@ -138,9 +138,9 @@ export const runCompletionsInstall = async (
 
 const handleCliError = (error: unknown): void => {
   const err = error instanceof Error ? error : new Error(String(error));
-  const projection = projectPublicSurfaceError('cli', err);
-  process.stderr.write(`Error: ${projection.message}\n`);
-  process.exit(projection.code);
+  const rendering = renderPublicSurfaceError('cli', err);
+  process.stderr.write(`Error: ${rendering.message}\n`);
+  process.exit(rendering.code);
 };
 
 const findCompletionsCommand = (program: Command): Command | undefined =>

package/src/run-trace.ts

@@ -5,7 +5,7 @@
  * intrinsic tracing pipeline in `@ontrails/core` records every trail-,
  * span-, signal-, and activation-level event during the invocation. After
  * the trail completes (success or failure), the records are rendered as a
- * tree to stderr via `renderTraceTree` from `@ontrails/observe`. Under
+ * tree to stderr via `renderTraceTree` from `@ontrails/observability`. Under
  * `--json`, the structured `TraceRecord[]` is also emitted on stdout as
  * the `tracing` field of a Result envelope.
  *
@@ -25,8 +25,8 @@
 
 import { getTraceSink, registerTraceSink } from '@ontrails/core';
 import type { TraceRecord, TraceSink } from '@ontrails/core';
-import { createMemorySink, renderTraceTree } from '@ontrails/observe';
-import type { MemoryTraceSink } from '@ontrails/observe';
+import { createMemorySink, renderTraceTree } from '@ontrails/observability';
+import type { MemoryTraceSink } from '@ontrails/observability';
 
 // ---------------------------------------------------------------------------
 // Argv detection
@@ -166,7 +166,7 @@ const errorFromUnknown = (
  * On success, the inner value is taken straight from the trail's
  * `Result.ok(...)` payload. On failure the envelope captures the error's
  * `name` and `message` -- both safe to serialize and consistent with how
- * other Trails surfaces project errors.
+ * other Trails surfaces render errors.
  */
 export const buildTraceJsonEnvelope = (
   result: ResultLike,

package/src/trails/dev-support.ts

@@ -18,7 +18,7 @@ import {
   applyTraceCleanup,
   countTraceRecords,
   previewTraceCleanup,
-} from '@ontrails/tracing';
+} from '@ontrails/observability/dev';
 
 import {
   removeFileIfPresent,