@ontrails/trails 1.0.0-beta.13 → 1.0.0-beta.15

package/dist/src/trails/topo-read-support.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Read-only topo store consumer helpers.
+ *
+ * Extracted from topo-support.ts to isolate read-only store consumer helpers,
+ * keeping module boundaries clean.
+ */
+import { Result } from '@ontrails/core';
+import type { Topo } from '@ontrails/core';
+import type { BriefReport, SurveyListReport } from './topo-reports.js';
+import type { TopoSummaryReport, TopoVerifyReport } from './topo-support.js';
+interface CurrentTrailDetail {
+    readonly crosses: string[];
+    readonly description: string | null;
+    readonly detours: readonly {
+        readonly on: string;
+        readonly maxAttempts: number;
+    }[] | null;
+    readonly examples: unknown[];
+    readonly id: string;
+    readonly intent: 'destroy' | 'read' | 'write';
+    readonly kind: string;
+    readonly pattern: string | null;
+    readonly resources: string[];
+    readonly safety: string;
+}
+interface CurrentResourceDetail {
+    readonly description: string | null;
+    readonly health: 'available' | 'none';
+    readonly id: string;
+    readonly kind: 'resource';
+    readonly lifetime: 'singleton';
+    readonly usedBy: string[];
+}
+export declare const buildTopoSummary: (app: Topo, options?: {
+    readonly rootDir?: string;
+}) => TopoSummaryReport;
+export declare const buildCurrentTopoBrief: (app: Topo, options?: {
+    readonly rootDir?: string;
+}) => BriefReport;
+export declare const buildCurrentTopoList: (app: Topo, options?: {
+    readonly rootDir?: string;
+}) => SurveyListReport;
+export declare const buildCurrentGuideEntries: (app: Topo, options?: {
+    readonly rootDir?: string;
+}) => readonly {
+    readonly description: string;
+    readonly exampleCount: number;
+    readonly id: string;
+    readonly kind: string;
+}[];
+export declare const buildCurrentTopoDetail: (app: Topo, id: string, options?: {
+    readonly rootDir?: string;
+}) => CurrentResourceDetail | CurrentTrailDetail | undefined;
+export declare const verifyCurrentTopo: (app: Topo, options?: {
+    readonly rootDir?: string;
+}) => Promise<Result<TopoVerifyReport, Error>>;
+export {};
+//# sourceMappingURL=topo-read-support.d.ts.map

package/dist/src/trails/topo-read-support.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topo-read-support.d.ts","sourceRoot":"","sources":["../../../src/trails/topo-read-support.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAML,MAAM,EACP,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,IAAI,EAAgB,MAAM,gBAAgB,CAAC;AAOzD,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAoB7E,UAAU,kBAAkB;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,OAAO,EACZ,SAAS;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;KAAE,EAAE,GAChE,IAAI,CAAC;IACT,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,UAAU,qBAAqB;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAAC;IACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;CAC3B;AA6ID,eAAO,MAAM,gBAAgB,GAC3B,KAAK,IAAI,EACT,UAAU;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,KACtC,iBAUF,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAChC,KAAK,IAAI,EACT,UAAU;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,KACtC,WAKF,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAC/B,KAAK,IAAI,EACT,UAAU;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,KACtC,gBAKF,CAAC;AAEF,eAAO,MAAM,wBAAwB,GACnC,KAAK,IAAI,EACT,UAAU;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,KACtC,SAAS;IACV,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,EAUA,CAAC;AAEF,eAAO,MAAM,sBAAsB,GACjC,KAAK,IAAI,EACT,IAAI,MAAM,EACV,UAAU;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,KACtC,qBAAqB,GAAG,kBAAkB,GAAG,SAa/C,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAC5B,KAAK,IAAI,EACT,UAAU;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,KACtC,OAAO,CAAC,MAAM,CAAC,gBAAgB,EAAE,KAAK,CAAC,CA0CzC,CAAC"}

package/dist/src/trails/topo-read-support.js

@@ -0,0 +1,167 @@
+/**
+ * Read-only topo store consumer helpers.
+ *
+ * Extracted from topo-support.ts to isolate read-only store consumer helpers,
+ * keeping module boundaries clean.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { ConflictError, createTopoStore, InternalError, listTopoSnapshots, NotFoundError, Result, } from '@ontrails/core';
+import { deriveTrailsDbPath, deriveTrailsDir, } from '@ontrails/core/internal/trails-db';
+import { readSurfaceLockData } from '@ontrails/schema';
+import { REPORT_CONTRACT_VERSION, REPORT_VERSION } from './topo-constants.js';
+import { createCurrentTopoSnapshot, deriveRootDir, LOCK_PATH, } from './topo-support.js';
+// ---------------------------------------------------------------------------
+// Store helpers
+// ---------------------------------------------------------------------------
+const topoStoreRef = (snapshotId) => ({ snapshotId });
+const hasCommittedLock = (trailsDir) => existsSync(join(trailsDir, 'trails.lock'));
+const readSurfaceEntries = (surfaceMapJson) => JSON.parse(surfaceMapJson).entries;
+const buildBriefReportFromStore = (app, store, ref, snapshot) => {
+    const trails = store.trails.list({ snapshot: ref });
+    const exportRecord = store.exports.get(ref);
+    const trailEntries = exportRecord === undefined
+        ? []
+        : readSurfaceEntries(exportRecord.surfaceMapJson).filter((entry) => entry.kind === 'trail');
+    return {
+        contractVersion: REPORT_CONTRACT_VERSION,
+        features: {
+            detours: trailEntries.some((entry) => (entry.detours ?? []).length > 0),
+            examples: trails.some((trail) => trail.hasExamples),
+            outputSchemas: trails.some((trail) => trail.hasOutput),
+            resources: snapshot.resourceCount > 0,
+            signals: snapshot.signalCount > 0,
+        },
+        name: app.name,
+        resources: snapshot.resourceCount,
+        signals: snapshot.signalCount,
+        trails: snapshot.trailCount,
+        version: REPORT_VERSION,
+    };
+};
+const buildSurveyListFromStore = (store, ref) => {
+    const trails = store.trails.list({ snapshot: ref });
+    const resources = store.resources.list({ snapshot: ref });
+    return {
+        count: trails.length,
+        entries: trails.map((trail) => ({
+            examples: trail.exampleCount,
+            id: trail.id,
+            kind: trail.kind,
+            safety: trail.safety,
+        })),
+        resourceCount: resources.length,
+        resources: resources.map((resource) => ({
+            description: resource.description,
+            health: resource.health,
+            id: resource.id,
+            kind: resource.kind,
+            lifetime: resource.lifetime,
+            usedBy: resource.usedBy,
+        })),
+    };
+};
+const buildTrailDetailFromStore = (detail) => ({
+    crosses: [...detail.crosses],
+    description: detail.description,
+    detours: detail.detours,
+    examples: [...detail.examples],
+    id: detail.id,
+    intent: detail.intent,
+    kind: detail.kind,
+    pattern: detail.pattern,
+    resources: [...detail.resources],
+    safety: detail.safety,
+});
+const buildResourceDetailFromStore = (resource) => ({
+    description: resource.description,
+    health: resource.health,
+    id: resource.id,
+    kind: resource.kind,
+    lifetime: resource.lifetime,
+    usedBy: [...resource.usedBy],
+});
+// ---------------------------------------------------------------------------
+// withCurrentTopoStore
+// ---------------------------------------------------------------------------
+/**
+ * Run a read callback against the latest topo store state.
+ *
+ * Uses the most recent existing snapshot when available, only creating a new
+ * snapshot when no prior snapshot exists. This avoids unbounded snapshot
+ * accumulation from
+ * read-only operations like survey, guide, and show.
+ */
+const withCurrentTopoStore = (app, rootDir, read) => {
+    const [existingSnapshot] = listTopoSnapshots({ limit: 1, rootDir });
+    const snapshot = existingSnapshot ?? createCurrentTopoSnapshot(app, { rootDir });
+    const store = createTopoStore({ rootDir });
+    return read(store, topoStoreRef(snapshot.id), snapshot);
+};
+// ---------------------------------------------------------------------------
+// Public read-only consumers
+// ---------------------------------------------------------------------------
+export const buildTopoSummary = (app, options) => {
+    const rootDir = deriveRootDir(options?.rootDir);
+    const trailsDir = deriveTrailsDir({ rootDir });
+    return withCurrentTopoStore(app, rootDir, (store, ref, snapshot) => ({
+        app: buildBriefReportFromStore(app, store, ref, snapshot),
+        dbPath: deriveTrailsDbPath({ rootDir }),
+        list: buildSurveyListFromStore(store, ref),
+        lockExists: hasCommittedLock(trailsDir),
+        lockPath: LOCK_PATH,
+    }));
+};
+export const buildCurrentTopoBrief = (app, options) => {
+    const rootDir = deriveRootDir(options?.rootDir);
+    return withCurrentTopoStore(app, rootDir, (store, ref, snapshot) => buildBriefReportFromStore(app, store, ref, snapshot));
+};
+export const buildCurrentTopoList = (app, options) => {
+    const rootDir = deriveRootDir(options?.rootDir);
+    return withCurrentTopoStore(app, rootDir, (store, ref) => buildSurveyListFromStore(store, ref));
+};
+export const buildCurrentGuideEntries = (app, options) => {
+    const rootDir = deriveRootDir(options?.rootDir);
+    return withCurrentTopoStore(app, rootDir, (store, ref) => store.trails.list({ snapshot: ref }).map((trail) => ({
+        description: trail.description ?? '(no description)',
+        exampleCount: trail.exampleCount,
+        id: trail.id,
+        kind: trail.kind,
+    })));
+};
+export const buildCurrentTopoDetail = (app, id, options) => {
+    const rootDir = deriveRootDir(options?.rootDir);
+    return withCurrentTopoStore(app, rootDir, (store, ref) => {
+        const trail = store.trails.get(id, { snapshot: ref });
+        if (trail !== undefined) {
+            return buildTrailDetailFromStore(trail);
+        }
+        const resource = store.resources.get(id, { snapshot: ref });
+        return resource === undefined
+            ? undefined
+            : buildResourceDetailFromStore(resource);
+    });
+};
+export const verifyCurrentTopo = async (app, options) => {
+    const rootDir = deriveRootDir(options?.rootDir);
+    const committedLock = await readSurfaceLockData({
+        dir: deriveTrailsDir({ rootDir }),
+    });
+    if (committedLock === null) {
+        return Result.err(new NotFoundError('No committed trails.lock found. Run `trails topo export` first.'));
+    }
+    const currentHash = withCurrentTopoStore(app, rootDir, (store, ref) => store.exports.get(ref)?.surfaceHash);
+    if (currentHash === undefined) {
+        return Result.err(new InternalError('No stored topo export found for the current topo snapshot'));
+    }
+    if (committedLock.hash !== currentHash) {
+        return Result.err(new ConflictError('trails.lock is stale. Run `trails topo export` to refresh it.'));
+    }
+    return Result.ok({
+        committedHash: committedLock.hash,
+        currentHash,
+        lockPath: LOCK_PATH,
+        stale: false,
+    });
+};
+//# sourceMappingURL=topo-read-support.js.map

package/dist/src/trails/topo-read-support.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"topo-read-support.js","sourceRoot":"","sources":["../../../src/trails/topo-read-support.ts"],"names":[],"mappings":"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"}

package/dist/src/trails/topo-reports.d.ts

@@ -0,0 +1,54 @@
+import type { Topo, Trail } from '@ontrails/core';
+export interface BriefReport {
+    readonly name: string;
+    readonly version: string;
+    readonly contractVersion: string;
+    readonly features: {
+        readonly resources: boolean;
+        readonly outputSchemas: boolean;
+        readonly examples: boolean;
+        readonly detours: boolean;
+        readonly signals: boolean;
+    };
+    readonly trails: number;
+    readonly signals: number;
+    readonly resources: number;
+}
+export interface SurveyListReport {
+    readonly count: number;
+    readonly entries: readonly {
+        readonly examples: number;
+        readonly id: string;
+        readonly kind: string;
+        readonly safety: string;
+    }[];
+    readonly resourceCount: number;
+    readonly resources: readonly {
+        readonly description: string | null;
+        readonly health: 'available' | 'none';
+        readonly id: string;
+        readonly kind: 'resource';
+        readonly lifetime: 'singleton';
+        readonly usedBy: readonly string[];
+    }[];
+}
+export interface TrailDetailReport {
+    readonly description: string | null;
+    readonly detours: readonly {
+        readonly on: string;
+        readonly maxAttempts: number;
+    }[] | null;
+    readonly examples: readonly unknown[];
+    readonly crosses: readonly string[];
+    readonly id: string;
+    readonly intent: 'read' | 'write' | 'destroy';
+    readonly kind: string;
+    readonly pattern: string | null;
+    readonly safety: string;
+    readonly resources: readonly string[];
+}
+export declare const deriveBriefReport: (app: Topo) => BriefReport;
+export declare const deriveResourceDetail: (app: Topo, resourceId: string) => object;
+export declare const deriveSurveyList: (app: Topo) => SurveyListReport;
+export declare const deriveTrailDetail: (item: Trail<unknown, unknown>) => TrailDetailReport;
+//# sourceMappingURL=topo-reports.d.ts.map

package/dist/src/trails/topo-reports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topo-reports.d.ts","sourceRoot":"","sources":["../../../src/trails/topo-reports.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAIlD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE;QACjB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;QAC5B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;QAChC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;QAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;QAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;KAC3B,CAAC;IACF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,SAAS;QACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;KACzB,EAAE,CAAC;IACJ,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,SAAS;QAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QACpC,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAAC;QACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;QAC1B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;QAC/B,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;KACpC,EAAE,CAAC;CACL;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,OAAO,EACZ,SAAS;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;KAAE,EAAE,GAChE,IAAI,CAAC;IACT,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAgCD,eAAO,MAAM,iBAAiB,GAAI,KAAK,IAAI,KAAG,WAmB7C,CAAC;AAwCF,eAAO,MAAM,oBAAoB,GAAI,KAAK,IAAI,EAAE,YAAY,MAAM,KAAG,MAYpE,CAAC;AAiBF,eAAO,MAAM,gBAAgB,GAAI,KAAK,IAAI,KAAG,gBA4B5C,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAC5B,MAAM,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,KAC5B,iBAuBF,CAAC"}

package/dist/src/trails/topo-reports.js

@@ -0,0 +1,128 @@
+import { REPORT_CONTRACT_VERSION, REPORT_VERSION } from './topo-constants.js';
+const trailHas = (raw, key) => {
+    if (key === 'examples' || key === 'detours') {
+        return Array.isArray(raw[key]) && raw[key].length > 0;
+    }
+    return Boolean(raw[key]);
+};
+const detectFeatures = (app) => {
+    const trails = [...app.trails.values()].map((item) => item);
+    return {
+        hasDetours: trails.some((r) => trailHas(r, 'detours')),
+        hasExamples: trails.some((r) => trailHas(r, 'examples')),
+        hasOutputSchemas: trails.some((r) => trailHas(r, 'output')),
+        hasResources: trails.some((r) => Array.isArray(r['resources']) &&
+            r['resources'].length > 0),
+    };
+};
+export const deriveBriefReport = (app) => {
+    const { hasDetours, hasExamples, hasOutputSchemas, hasResources } = detectFeatures(app);
+    return {
+        contractVersion: REPORT_CONTRACT_VERSION,
+        features: {
+            detours: hasDetours,
+            examples: hasExamples,
+            outputSchemas: hasOutputSchemas,
+            resources: hasResources,
+            signals: app.signals.size > 0,
+        },
+        name: app.name,
+        resources: app.resources.size,
+        signals: app.signals.size,
+        trails: app.trails.size,
+        version: REPORT_VERSION,
+    };
+};
+const safetyLabel = (entry) => {
+    if (entry.intent === 'destroy') {
+        return 'destroy';
+    }
+    if (entry.intent === 'write') {
+        return 'write';
+    }
+    if (entry.intent === 'read') {
+        return 'read';
+    }
+    return '-';
+};
+const buildResourceUsage = (app) => {
+    const usage = new Map();
+    for (const trailDef of app.list()) {
+        for (const declaredResource of trailDef.resources) {
+            const users = usage.get(declaredResource.id) ?? [];
+            users.push(trailDef.id);
+            usage.set(declaredResource.id, users);
+        }
+    }
+    return new Map([...usage.entries()].map(([id, users]) => [id, users.toSorted()]));
+};
+const resourceHealthStatus = (resource) => resource.health === undefined ? 'none' : 'available';
+export const deriveResourceDetail = (app, resourceId) => {
+    const item = app.getResource(resourceId);
+    const usedBy = buildResourceUsage(app).get(resourceId) ?? [];
+    return {
+        description: item?.description ?? null,
+        health: item ? resourceHealthStatus(item) : 'none',
+        id: resourceId,
+        kind: 'resource',
+        lifetime: 'singleton',
+        usedBy,
+    };
+};
+const formatResourceList = (app) => {
+    const usage = buildResourceUsage(app);
+    return app
+        .listResources()
+        .map((resource) => ({
+        description: resource.description ?? null,
+        health: resourceHealthStatus(resource),
+        id: resource.id,
+        kind: resource.kind,
+        lifetime: 'singleton',
+        usedBy: usage.get(resource.id) ?? [],
+    }))
+        .toSorted((a, b) => a.id.localeCompare(b.id));
+};
+export const deriveSurveyList = (app) => {
+    const items = app.list();
+    const entries = items.map((item) => {
+        const safety = safetyLabel(item);
+        const examples = Array.isArray(item.examples)
+            ? item.examples.length
+            : 0;
+        return {
+            examples,
+            id: item.id,
+            kind: item.kind,
+            safety,
+        };
+    });
+    const resources = formatResourceList(app);
+    return {
+        count: items.length,
+        entries,
+        resourceCount: resources.length,
+        resources,
+    };
+};
+export const deriveTrailDetail = (item) => {
+    const safety = safetyLabel(item);
+    return {
+        crosses: item.crosses.toSorted(),
+        description: item.description ?? null,
+        detours: item.detours.length > 0
+            ? item.detours.map((d) => ({
+                maxAttempts: d.maxAttempts ?? 1,
+                on: d.on.name,
+            }))
+            : null,
+        examples: item.examples ?? [],
+        id: item.id,
+        intent: item.intent,
+        kind: item.kind,
+        pattern: item.pattern ?? null,
+        resources: item.resources.map((resource) => resource.id).toSorted(),
+        safety,
+    };
+};
+//# sourceMappingURL=topo-reports.js.map

package/dist/src/trails/topo-reports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"topo-reports.js","sourceRoot":"","sources":["../../../src/trails/topo-reports.ts"],"names":[],"mappings":"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"}

package/dist/src/trails/topo-show.d.ts

@@ -0,0 +1,23 @@
+export declare const topoShowTrail: import("@ontrails/core").Trail<{
+    id: string;
+    module?: string | undefined;
+    rootDir?: string | undefined;
+}, {
+    crosses: string[];
+    description: unknown;
+    detours: unknown;
+    examples: unknown[];
+    id: string;
+    intent: "read" | "write" | "destroy";
+    kind: string;
+    resources: string[];
+    safety: string;
+} | {
+    description: string | null;
+    health: "available" | "none";
+    id: string;
+    kind: "resource";
+    lifetime: "singleton";
+    usedBy: string[];
+}, never>;
+//# sourceMappingURL=topo-show.d.ts.map

package/dist/src/trails/topo-show.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topo-show.d.ts","sourceRoot":"","sources":["../../../src/trails/topo-show.ts"],"names":[],"mappings":"AA2BA,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;SA0BxB,CAAC"}

package/dist/src/trails/topo-show.js

@@ -0,0 +1,49 @@
+import { NotFoundError, Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+import { loadApp } from './load-app.js';
+import { buildCurrentTopoDetail } from './topo-read-support.js';
+const trailDetailOutput = z.object({
+    crosses: z.array(z.string()),
+    description: z.unknown().nullable(),
+    detours: z.unknown().nullable(),
+    examples: z.array(z.unknown()),
+    id: z.string(),
+    intent: z.enum(['read', 'write', 'destroy']),
+    kind: z.string(),
+    resources: z.array(z.string()),
+    safety: z.string(),
+});
+const resourceDetailOutput = z.object({
+    description: z.string().nullable(),
+    health: z.enum(['available', 'none']),
+    id: z.string(),
+    kind: z.literal('resource'),
+    lifetime: z.literal('singleton'),
+    usedBy: z.array(z.string()),
+});
+export const topoShowTrail = trail('topo.show', {
+    blaze: async (input, ctx) => {
+        const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
+        const app = await loadApp(input.module, rootDir);
+        const detail = buildCurrentTopoDetail(app, input.id, { rootDir });
+        if (detail !== undefined) {
+            return Result.ok(detail);
+        }
+        return Result.err(new NotFoundError(`Trail or resource not found: ${input.id}`));
+    },
+    description: 'Show detail for a current trail or resource',
+    examples: [
+        {
+            input: { id: 'topo' },
+            name: 'Show current trail detail',
+        },
+    ],
+    input: z.object({
+        id: z.string().describe('Trail or resource ID to inspect'),
+        module: z.string().optional().describe('Path to the app module'),
+        rootDir: z.string().optional().describe('Workspace root directory'),
+    }),
+    intent: 'read',
+    output: z.union([trailDetailOutput, resourceDetailOutput]),
+});
+//# sourceMappingURL=topo-show.js.map

package/dist/src/trails/topo-show.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"topo-show.js","sourceRoot":"","sources":["../../../src/trails/topo-show.ts"],"names":[],"mappings":"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"}

package/dist/src/trails/topo-store-support.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Stored-export pipeline for topo persistence.
+ *
+ * Extracted from topo-support.ts to isolate store persistence concerns,
+ * keeping module boundaries clean.
+ */
+import type { Topo } from '@ontrails/core';
+import { Result } from '@ontrails/core';
+import type { TopoExportReport } from './topo-support.js';
+export declare const exportCurrentTopo: (app: Topo, options?: {
+    readonly rootDir?: string;
+}) => Promise<Result<TopoExportReport, Error>>;
+//# sourceMappingURL=topo-store-support.d.ts.map

package/dist/src/trails/topo-store-support.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topo-store-support.d.ts","sourceRoot":"","sources":["../../../src/trails/topo-store-support.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAgB,MAAM,gBAAgB,CAAC;AACzD,OAAO,EAAiB,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAavD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AA4D1D,eAAO,MAAM,iBAAiB,GAC5B,KAAK,IAAI,EACT,UAAU;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,KACtC,OAAO,CAAC,MAAM,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAmBzC,CAAC"}

package/dist/src/trails/topo-store-support.js

@@ -0,0 +1,55 @@
+/**
+ * Stored-export pipeline for topo persistence.
+ *
+ * Extracted from topo-support.ts to isolate store persistence concerns,
+ * keeping module boundaries clean.
+ */
+import { InternalError, Result } from '@ontrails/core';
+import { createTopoSnapshot, getStoredTopoExport, } from '@ontrails/core/internal/topo-store';
+import { openWriteTrailsDb, deriveTrailsDir, } from '@ontrails/core/internal/trails-db';
+import { writeSurfaceLock, writeSurfaceMap } from '@ontrails/schema';
+import { deriveRootDir, deriveTopoCounts, readGitState, } from './topo-support.js';
+const persistAndReadStoredExport = (app, db, rootDir) => {
+    const snapshotResult = createTopoSnapshot(db, app, {
+        ...readGitState(rootDir),
+        ...deriveTopoCounts(app),
+    });
+    if (snapshotResult.isErr()) {
+        return snapshotResult;
+    }
+    const snapshot = snapshotResult.value;
+    const storedExport = getStoredTopoExport(db, snapshot.id);
+    if (storedExport === undefined) {
+        return Result.err(new InternalError(`Missing stored topo export for snapshot "${snapshot.id}"`));
+    }
+    return Result.ok({
+        snapshot,
+        storedExport,
+    });
+};
+const writeStoredExportArtifacts = async (storedExport, trailsDir) => {
+    const mapPath = await writeSurfaceMap(JSON.parse(storedExport.surfaceMapJson), { dir: trailsDir });
+    const lockPath = await writeSurfaceLock(JSON.parse(storedExport.lockContent), { dir: trailsDir });
+    return {
+        hash: storedExport.surfaceHash,
+        lockPath,
+        mapPath,
+    };
+};
+export const exportCurrentTopo = async (app, options) => {
+    const rootDir = deriveRootDir(options?.rootDir);
+    const db = openWriteTrailsDb({ rootDir });
+    try {
+        const persisted = persistAndReadStoredExport(app, db, rootDir);
+        if (persisted.isErr()) {
+            return persisted;
+        }
+        const { snapshot, storedExport } = persisted.value;
+        const artifacts = await writeStoredExportArtifacts(storedExport, deriveTrailsDir({ rootDir }));
+        return Result.ok({ ...artifacts, snapshot });
+    }
+    finally {
+        db.close();
+    }
+};
+//# sourceMappingURL=topo-store-support.js.map

package/dist/src/trails/topo-store-support.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"topo-store-support.js","sourceRoot":"","sources":["../../../src/trails/topo-store-support.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAEvD,OAAO,EACL,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACL,iBAAiB,EACjB,eAAe,GAChB,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGrE,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,YAAY,GACb,MAAM,mBAAmB,CAAC;AAE3B,MAAM,0BAA0B,GAAG,CACjC,GAAS,EACT,EAAwC,EACxC,OAAe,EAIf,EAAE;IACF,MAAM,cAAc,GAAG,kBAAkB,CAAC,EAAE,EAAE,GAAG,EAAE;QACjD,GAAG,YAAY,CAAC,OAAO,CAAC;QACxB,GAAG,gBAAgB,CAAC,GAAG,CAAC;KACzB,CAAC,CAAC;IACH,IAAI,cAAc,CAAC,KAAK,EAAE,EAAE,CAAC;QAC3B,OAAO,cAAc,CAAC;IACxB,CAAC;IAED,MAAM,QAAQ,GAAG,cAAc,CAAC,KAAK,CAAC;IACtC,MAAM,YAAY,GAAG,mBAAmB,CAAC,EAAE,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;IAE1D,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,MAAM,CAAC,GAAG,CACf,IAAI,aAAa,CACf,4CAA4C,QAAQ,CAAC,EAAE,GAAG,CAC3D,CACF,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC,EAAE,CAAC;QACf,QAAQ;QACR,YAAY;KACb,CAAC,CAAC;AACL,CAAC,CAAC;AAEF,MAAM,0BAA0B,GAAG,KAAK,EACtC,YAA8B,EAC9B,SAAiB,EACiD,EAAE;IACpE,MAAM,OAAO,GAAG,MAAM,eAAe,CACnC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,cAAc,CAAe,EACrD,EAAE,GAAG,EAAE,SAAS,EAAE,CACnB,CAAC;IACF,MAAM,QAAQ,GAAG,MAAM,gBAAgB,CACrC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,WAAW,CAAgB,EACnD,EAAE,GAAG,EAAE,SAAS,EAAE,CACnB,CAAC;IAEF,OAAO;QACL,IAAI,EAAE,YAAY,CAAC,WAAW;QAC9B,QAAQ;QACR,OAAO;KACR,CAAC;AACJ,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,EACpC,GAAS,EACT,OAAuC,EACG,EAAE;IAC5C,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAChD,MAAM,EAAE,GAAG,iBAAiB,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;IAE1C,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,0BAA0B,CAAC,GAAG,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;QAC/D,IAAI,SAAS,CAAC,KAAK,EAAE,EAAE,CAAC;YACtB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,GAAG,SAAS,CAAC,KAAK,CAAC;QACnD,MAAM,SAAS,GAAG,MAAM,0BAA0B,CAChD,YAAY,EACZ,eAAe,CAAC,EAAE,OAAO,EAAE,CAAC,CAC7B,CAAC;QACF,OAAO,MAAM,CAAC,EAAE,CAAC,EAAE,GAAG,SAAS,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC/C,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,KAAK,EAAE,CAAC;IACb,CAAC;AACH,CAAC,CAAC"}