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

package/dist/store/accessor-protocol.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=accessor-protocol.js.map

package/dist/store/accessor-protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accessor-protocol.js","sourceRoot":"","sources":["../../src/store/accessor-protocol.ts"],"names":[],"mappings":""}

package/dist/store/index.d.ts

@@ -0,0 +1,2 @@
+export type { StoreAccessorProtocol, StoreAccessorRecord, } from './accessor-protocol.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/store/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/store/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,wBAAwB,CAAC"}

package/dist/store/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

package/dist/store/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/store/index.ts"],"names":[],"mappings":""}

package/dist/surface-filter.d.ts

@@ -0,0 +1,13 @@
+import type { Intent, Trail } from './trail.js';
+export interface SurfaceFilterOptions {
+    /** Glob patterns that keep only matching trail IDs when provided. */
+    readonly include?: readonly string[] | undefined;
+    /** Glob patterns that remove matching trail IDs. */
+    readonly exclude?: readonly string[] | undefined;
+    /** Allowed intents for exposed trailheads. Empty arrays act as no filter. */
+    readonly intent?: readonly Intent[] | undefined;
+}
+export declare const matchesTrailPattern: (trailId: string, pattern: string) => boolean;
+export declare const shouldIncludeTrailForSurface: (trail: Trail<unknown, unknown, unknown>, options?: SurfaceFilterOptions) => boolean;
+export declare const filterSurfaceTrails: (trails: readonly Trail<unknown, unknown, unknown>[], options?: SurfaceFilterOptions) => Trail<unknown, unknown, unknown>[];
+//# sourceMappingURL=surface-filter.d.ts.map

package/dist/surface-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-filter.d.ts","sourceRoot":"","sources":["../src/surface-filter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAMhD,MAAM,WAAW,oBAAoB;IACnC,qEAAqE;IACrE,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACjD,oDAAoD;IACpD,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACjD,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CACjD;AAuED,eAAO,MAAM,mBAAmB,GAC9B,SAAS,MAAM,EACf,SAAS,MAAM,KACd,OAKF,CAAC;AA+DF,eAAO,MAAM,4BAA4B,GACvC,OAAO,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EACvC,UAAS,oBAAyB,KACjC,OAiBF,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAC9B,QAAQ,SAAS,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,EACnD,UAAS,oBAAyB,KACjC,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EACqC,CAAC"}

package/dist/surface-filter.js

@@ -0,0 +1,76 @@
+// ---------------------------------------------------------------------------
+// Glob matching
+// ---------------------------------------------------------------------------
+const trailIdSegments = (trailId) => trailId.split('.');
+const patternSegments = (pattern) => pattern.split('.');
+const matchesDoubleStar = (trail, pattern, trailIndex, patternIndex, matchSegments) => patternIndex === pattern.length - 1 ||
+    Array.from({ length: trail.length - trailIndex + 1 }, (_, offset) => trailIndex + offset).some((index) => matchSegments(trail, pattern, index, patternIndex + 1));
+const matchesSingleSegment = (trail, pattern, trailIndex, patternIndex, current, matchSegments) => trailIndex < trail.length &&
+    (current === '*' || current === trail[trailIndex]) &&
+    matchSegments(trail, pattern, trailIndex + 1, patternIndex + 1);
+const matchesFrom = function matchesFrom(trail, pattern, trailIndex, patternIndex) {
+    if (patternIndex >= pattern.length) {
+        return trailIndex >= trail.length;
+    }
+    const current = pattern[patternIndex];
+    if (current === undefined) {
+        return false;
+    }
+    return current === '**'
+        ? matchesDoubleStar(trail, pattern, trailIndex, patternIndex, matchesFrom)
+        : matchesSingleSegment(trail, pattern, trailIndex, patternIndex, current, matchesFrom);
+};
+export const matchesTrailPattern = (trailId, pattern) => {
+    if (pattern === trailId) {
+        return true;
+    }
+    return matchesFrom(trailIdSegments(trailId), patternSegments(pattern), 0, 0);
+};
+// ---------------------------------------------------------------------------
+// Trailhead filtering
+// ---------------------------------------------------------------------------
+const matchesAnyPattern = (trailId, patterns) => patterns !== undefined &&
+    patterns.some((pattern) => matchesTrailPattern(trailId, pattern));
+const isExplicitInternalInclude = (trailId, include) => include !== undefined && include.includes(trailId);
+/**
+ * Resolve the effective visibility for a trail.
+ *
+ * Returns `'internal'` when either the explicit `visibility` field is
+ * `'internal'` or the legacy `meta.internal === true` convention is set.
+ * Honoring the legacy flag keeps trails authored before the visibility
+ * field was introduced (e.g. `meta: { internal: true }`) off trailheads.
+ *
+ * The runtime always fills in `visibility: 'public'` when the spec did not
+ * declare it, so we cannot distinguish explicit `'public'` from the default.
+ * This means a trail that sets both `meta.internal = true` and
+ * `visibility: 'public'` will still be treated as internal — that
+ * combination has never been a documented override and, if the author
+ * really means "public", they should remove the legacy flag.
+ */
+const effectiveVisibility = (trail) => {
+    if (trail.visibility === 'internal') {
+        return 'internal';
+    }
+    return trail.meta?.['internal'] === true ? 'internal' : 'public';
+};
+const isVisibleToTrailheads = (trail, include) => effectiveVisibility(trail) !== 'internal' ||
+    isExplicitInternalInclude(trail.id, include);
+const passesIncludeFilter = (trailId, include) => include === undefined ||
+    include.length === 0 ||
+    matchesAnyPattern(trailId, include);
+const passesIntentFilter = (trail, intent) => intent === undefined || intent.length === 0 || intent.includes(trail.intent);
+export const shouldIncludeTrailForSurface = (trail, options = {}) => {
+    if (trail.on.length > 0) {
+        return false;
+    }
+    const { exclude, include, intent } = options;
+    if (!isVisibleToTrailheads(trail, include)) {
+        return false;
+    }
+    if (matchesAnyPattern(trail.id, exclude)) {
+        return false;
+    }
+    return (passesIncludeFilter(trail.id, include) && passesIntentFilter(trail, intent));
+};
+export const filterSurfaceTrails = (trails, options = {}) => trails.filter((trail) => shouldIncludeTrailForSurface(trail, options));
+//# sourceMappingURL=surface-filter.js.map

package/dist/surface-filter.js.map

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

package/dist/topo-store.d.ts

@@ -0,0 +1,62 @@
+import type { SQLQueryBindings } from 'bun:sqlite';
+import type { Topo } from './topo.js';
+import { Result } from './result.js';
+import type { CreateTopoSnapshotInput, ListTopoSnapshotsOptions, TopoSnapshot } from './internal/topo-snapshots.js';
+import type { TopoStoreExportRecord, TopoStoreResourceRecord, TopoStoreRef, TopoStoreTrailDetailRecord, TopoStoreTrailRecord } from './internal/topo-store-read.js';
+import type { TrailsDbLocationOptions } from './internal/trails-db.js';
+/**
+ * Test-only instrumentation counters. Incremented by the read-path migration
+ * check to let tests assert that a current-schema store does not escalate to
+ * a write-mode open, and that cache invalidation re-runs the check when the
+ * underlying file is replaced.
+ *
+ * @internal
+ */
+export declare const __topoStoreMigrationStats: {
+    peekCalls: number;
+    writeEscalations: number;
+};
+export type { TopoStoreExportRecord, TopoStoreResourceRecord, TopoStoreRef, TopoStoreTrailDetailRecord, TopoStoreTrailRecord, } from './internal/topo-store-read.js';
+export type { CreateTopoSnapshotInput, ListTopoSnapshotsOptions, TopoSnapshot, } from './internal/topo-snapshots.js';
+export interface ReadOnlyTopoStore {
+    readonly exports: {
+        get(ref?: TopoStoreRef): TopoStoreExportRecord | undefined;
+    };
+    query<TRow extends Record<string, unknown>>(sql: string, bindings?: readonly SQLQueryBindings[]): readonly TRow[];
+    readonly resources: {
+        get(id: string, options?: {
+            readonly snapshot?: TopoStoreRef;
+        }): TopoStoreResourceRecord | undefined;
+        list(options?: {
+            readonly snapshot?: TopoStoreRef;
+        }): readonly TopoStoreResourceRecord[];
+    };
+    readonly snapshots: {
+        get(ref?: TopoStoreRef): TopoSnapshot | undefined;
+        latest(): TopoSnapshot | undefined;
+        list(options?: ListTopoSnapshotsOptions): readonly TopoSnapshot[];
+    };
+    readonly trails: {
+        get(id: string, options?: {
+            readonly snapshot?: TopoStoreRef;
+        }): TopoStoreTrailDetailRecord | undefined;
+        list(options?: {
+            readonly intent?: TopoStoreTrailRecord['intent'];
+            readonly snapshot?: TopoStoreRef;
+        }): readonly TopoStoreTrailRecord[];
+    };
+}
+export interface MockTopoStoreSeed {
+    readonly exports?: readonly TopoStoreExportRecord[];
+    readonly resources?: readonly TopoStoreResourceRecord[];
+    readonly snapshots?: readonly TopoSnapshot[];
+    readonly trails?: readonly TopoStoreTrailDetailRecord[];
+}
+export declare const createMockTopoStore: (seed?: MockTopoStoreSeed) => ReadOnlyTopoStore;
+export declare const createTopoStore: (options?: TrailsDbLocationOptions) => ReadOnlyTopoStore;
+export declare const createTopoSnapshot: (topo: Topo, options?: TrailsDbLocationOptions & CreateTopoSnapshotInput) => Result<TopoSnapshot, Error>;
+export declare const listTopoSnapshots: (options?: TrailsDbLocationOptions & ListTopoSnapshotsOptions) => readonly TopoSnapshot[];
+export declare const pinTopoSnapshot: (id: string, name: string, options?: TrailsDbLocationOptions) => TopoSnapshot | undefined;
+export declare const unpinTopoSnapshot: (nameOrId: string, options?: TrailsDbLocationOptions) => TopoSnapshot | undefined;
+export declare const topoStore: import("./resource.js").Resource<ReadOnlyTopoStore>;
+//# sourceMappingURL=topo-store.d.ts.map

package/dist/topo-store.d.ts.map

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

package/dist/topo-store.js

@@ -0,0 +1,319 @@
+import { existsSync, statSync } from 'node:fs';
+import { NotFoundError } from './errors.js';
+import { resource } from './resource.js';
+import { Result } from './result.js';
+import { TOPO_SCHEMA_VERSION, ensureTopoSnapshotSchema, listTopoSnapshots as listStoredTopoSnapshots, pinTopoSnapshot as pinStoredTopoSnapshot, unpinTopoSnapshot as unpinStoredTopoSnapshot, } from './internal/topo-snapshots.js';
+import { getTopoStoreExport, getTopoStoreResource, getTopoStoreTrail, listTopoStoreResources, listTopoStoreSnapshots, listTopoStoreTrails, queryTopoStore, readTopoStoreSnapshot, } from './internal/topo-store-read.js';
+import { createTopoSnapshot as storeTopoSnapshot } from './internal/topo-store.js';
+import { openReadTrailsDb, openWriteTrailsDb, deriveTrailsDbPath, } from './internal/trails-db.js';
+const migratedTopoDbPaths = new Map();
+/**
+ * Test-only instrumentation counters. Incremented by the read-path migration
+ * check to let tests assert that a current-schema store does not escalate to
+ * a write-mode open, and that cache invalidation re-runs the check when the
+ * underlying file is replaced.
+ *
+ * @internal
+ */
+export const __topoStoreMigrationStats = {
+    peekCalls: 0,
+    writeEscalations: 0,
+};
+const peekTopoSchemaVersion = (options) => {
+    let db;
+    try {
+        db = openReadTrailsDb(options);
+        const row = db
+            .query('SELECT version FROM meta_schema_versions WHERE subsystem = ?')
+            .get('topo');
+        return row?.version ?? 0;
+    }
+    catch {
+        // Table missing or unexpected shape: caller will escalate to a write-mode
+        // open and run the migration, which rebuilds the schema.
+        return undefined;
+    }
+    finally {
+        db?.close();
+    }
+};
+const statIdentity = (dbPath) => {
+    try {
+        const info = statSync(dbPath);
+        return { mtimeMs: info.mtimeMs, size: info.size };
+    }
+    catch {
+        return undefined;
+    }
+};
+const identitiesEqual = (a, b) => a.mtimeMs === b.mtimeMs && a.size === b.size;
+const runTopoMigrationEscalation = (options, dbPath, fallbackIdentity) => {
+    __topoStoreMigrationStats.writeEscalations += 1;
+    const db = openWriteTrailsDb(options);
+    try {
+        ensureTopoSnapshotSchema(db);
+    }
+    finally {
+        db.close();
+    }
+    // Re-stat after the migration so the cached identity matches the file we
+    // just touched, avoiding a spurious second escalation on the next read.
+    const postIdentity = statIdentity(dbPath) ?? fallbackIdentity;
+    migratedTopoDbPaths.set(dbPath, postIdentity);
+};
+const resolveIdentityIfFresh = (dbPath) => {
+    if (!existsSync(dbPath)) {
+        return undefined;
+    }
+    const identity = statIdentity(dbPath);
+    if (identity === undefined) {
+        return undefined;
+    }
+    const cached = migratedTopoDbPaths.get(dbPath);
+    if (cached !== undefined && identitiesEqual(cached, identity)) {
+        return undefined;
+    }
+    return identity;
+};
+/**
+ * Ensure the topo snapshot schema is at the current version before any
+ * read-only access. Peeks the version through a read-only handle first and
+ * only escalates to a write-mode open + migration when the store is stale.
+ *
+ * Memoized per resolved DB path keyed on file identity (mtime + size) so a
+ * long-running process that deletes and recreates `trails.db` re-runs the
+ * migration check against the fresh file.
+ *
+ * If the DB file does not yet exist, this is a no-op — the downstream read
+ * path will surface its own NotFoundError.
+ */
+const ensureTopoMigratedIfExists = (options) => {
+    const dbPath = deriveTrailsDbPath(options);
+    const identity = resolveIdentityIfFresh(dbPath);
+    if (identity === undefined) {
+        return;
+    }
+    __topoStoreMigrationStats.peekCalls += 1;
+    const version = peekTopoSchemaVersion(options);
+    if (version !== undefined && version >= TOPO_SCHEMA_VERSION) {
+        // Already current — record identity and skip the write-mode open entirely,
+        // preserving the read-only contract for callers whose filesystem mounts
+        // `trails.db` read-only.
+        migratedTopoDbPaths.set(dbPath, identity);
+        return;
+    }
+    runTopoMigrationEscalation(options, dbPath, identity);
+};
+const missingStoreMessage = 'No saved topo state found. Populate trails.db first or run a topo-backed surface.';
+const resolveStoreRootDir = (options) => options?.rootDir ?? process.cwd();
+const requireReadDb = (options) => {
+    const dbPath = deriveTrailsDbPath(options);
+    if (!existsSync(dbPath)) {
+        throw new NotFoundError(missingStoreMessage);
+    }
+    ensureTopoMigratedIfExists(options);
+    return openReadTrailsDb(options);
+};
+const requireSavedTopoState = (db) => {
+    if (readTopoStoreSnapshot(db) === undefined) {
+        throw new NotFoundError(missingStoreMessage);
+    }
+};
+const withStoredTopoState = (options, run) => {
+    const db = requireReadDb(options);
+    try {
+        requireSavedTopoState(db);
+        return run(db);
+    }
+    finally {
+        db.close();
+    }
+};
+const createSeedResolver = (seed) => {
+    const snapshots = [...(seed?.snapshots ?? [])];
+    const trails = [...(seed?.trails ?? [])];
+    const resources = [...(seed?.resources ?? [])];
+    const exports = [...(seed?.exports ?? [])];
+    const resolveSnapshot = (ref) => {
+        if (ref?.snapshotId !== undefined) {
+            return snapshots.find((snapshot) => snapshot.id === ref.snapshotId);
+        }
+        if (ref?.pin !== undefined) {
+            return snapshots.find((snapshot) => snapshot.pinnedAs === ref.pin);
+        }
+        return snapshots[0];
+    };
+    return {
+        exports,
+        resolveSnapshot,
+        resources,
+        snapshots,
+        trails,
+    };
+};
+export const createMockTopoStore = (seed) => {
+    const resolved = createSeedResolver(seed);
+    return {
+        exports: {
+            get(ref) {
+                const snapshot = resolved.resolveSnapshot(ref);
+                return snapshot === undefined
+                    ? undefined
+                    : resolved.exports.find((entry) => entry.snapshot.id === snapshot.id);
+            },
+        },
+        query() {
+            throw new NotFoundError('Mock topoStore.query() is unsupported. Seed typed accessors instead.');
+        },
+        resources: {
+            get(id, options) {
+                const snapshot = resolved.resolveSnapshot(options?.snapshot);
+                return resolved.resources.find((item) => item.id === id &&
+                    (snapshot === undefined || item.snapshotId === snapshot.id));
+            },
+            list(options) {
+                const snapshot = resolved.resolveSnapshot(options?.snapshot);
+                return snapshot === undefined
+                    ? []
+                    : resolved.resources.filter((item) => item.snapshotId === snapshot.id);
+            },
+        },
+        snapshots: {
+            get(ref) {
+                return resolved.resolveSnapshot(ref);
+            },
+            latest() {
+                return resolved.snapshots[0];
+            },
+            list(options) {
+                let snapshots = options?.pinned === undefined
+                    ? resolved.snapshots
+                    : resolved.snapshots.filter((snapshot) => options.pinned
+                        ? snapshot.pinnedAs !== undefined
+                        : snapshot.pinnedAs === undefined);
+                if (options?.before !== undefined) {
+                    const target = snapshots.find((s) => s.id === options.before);
+                    if (target !== undefined) {
+                        snapshots = snapshots.filter((s) => s.createdAt < target.createdAt ||
+                            (s.createdAt === target.createdAt && s.id < target.id));
+                    }
+                }
+                if (options?.limit !== undefined) {
+                    snapshots = snapshots.slice(0, options.limit);
+                }
+                return snapshots;
+            },
+        },
+        trails: {
+            get(id, options) {
+                const snapshot = resolved.resolveSnapshot(options?.snapshot);
+                if (snapshot === undefined) {
+                    return;
+                }
+                return resolved.trails.find((trail) => trail.id === id && trail.snapshotId === snapshot.id);
+            },
+            list(options) {
+                const snapshot = resolved.resolveSnapshot(options?.snapshot);
+                if (snapshot === undefined) {
+                    return [];
+                }
+                return resolved.trails.filter((trail) => trail.snapshotId === snapshot.id &&
+                    (options?.intent === undefined || trail.intent === options.intent));
+            },
+        },
+    };
+};
+export const createTopoStore = (options) => ({
+    exports: {
+        get(ref) {
+            return withStoredTopoState(options, (db) => getTopoStoreExport(db, ref));
+        },
+    },
+    query(sql, bindings) {
+        return withStoredTopoState(options, (db) => queryTopoStore(db, sql, bindings));
+    },
+    resources: {
+        get(id, queryOptions) {
+            return withStoredTopoState(options, (db) => getTopoStoreResource(db, id, queryOptions));
+        },
+        list(queryOptions) {
+            return withStoredTopoState(options, (db) => listTopoStoreResources(db, queryOptions));
+        },
+    },
+    snapshots: {
+        get(ref) {
+            return withStoredTopoState(options, (db) => readTopoStoreSnapshot(db, ref));
+        },
+        latest() {
+            return withStoredTopoState(options, (db) => readTopoStoreSnapshot(db));
+        },
+        list(snapshotOptions) {
+            return withStoredTopoState(options, (db) => listTopoStoreSnapshots(db, snapshotOptions));
+        },
+    },
+    trails: {
+        get(id, queryOptions) {
+            return withStoredTopoState(options, (db) => getTopoStoreTrail(db, id, queryOptions));
+        },
+        list(queryOptions) {
+            return withStoredTopoState(options, (db) => listTopoStoreTrails(db, queryOptions));
+        },
+    },
+});
+export const createTopoSnapshot = (topo, options) => {
+    const db = openWriteTrailsDb(options);
+    try {
+        return storeTopoSnapshot(db, topo, options);
+    }
+    finally {
+        db.close();
+    }
+};
+export const listTopoSnapshots = (options) => {
+    const dbPath = deriveTrailsDbPath(options);
+    if (!existsSync(dbPath)) {
+        return [];
+    }
+    ensureTopoMigratedIfExists(options);
+    const db = openReadTrailsDb(options);
+    try {
+        return listStoredTopoSnapshots(db, options);
+    }
+    finally {
+        db.close();
+    }
+};
+export const pinTopoSnapshot = (id, name, options) => {
+    const dbPath = deriveTrailsDbPath(options);
+    if (!existsSync(dbPath)) {
+        return undefined;
+    }
+    const db = openWriteTrailsDb(options);
+    try {
+        return pinStoredTopoSnapshot(db, { id, name });
+    }
+    finally {
+        db.close();
+    }
+};
+export const unpinTopoSnapshot = (nameOrId, options) => {
+    const dbPath = deriveTrailsDbPath(options);
+    if (!existsSync(dbPath)) {
+        return undefined;
+    }
+    const db = openWriteTrailsDb(options);
+    try {
+        return unpinStoredTopoSnapshot(db, nameOrId);
+    }
+    finally {
+        db.close();
+    }
+};
+export const topoStore = resource('topo.store', {
+    create: (svc) => Result.ok(createTopoStore({
+        rootDir: svc.workspaceRoot ?? svc.cwd ?? resolveStoreRootDir(),
+    })),
+    description: 'Read-only query access to saved topo state in trails.db',
+    mock: () => createMockTopoStore(),
+});
+//# sourceMappingURL=topo-store.js.map

package/dist/topo-store.js.map

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

package/dist/topo.d.ts

@@ -1,25 +1,39 @@
 /**
  * Application entry point — scans module exports to build a topology graph.
  */
-import type { AnySignal } from './event.js';
-import type { AnyProvision } from './provision.js';
+import type { AnyContour } from './contour.js';
+import type { AnySignal } from './signal.js';
+import type { AnyResource } from './resource.js';
 import type { AnyTrail } from './trail.js';
+export interface TopoIdentity {
+    readonly name: string;
+    readonly version?: string;
+    readonly description?: string;
+}
 export interface Topo {
     readonly name: string;
+    readonly version?: string;
+    readonly description?: string;
+    readonly contours: ReadonlyMap<string, AnyContour>;
     readonly trails: ReadonlyMap<string, AnyTrail>;
     readonly signals: ReadonlyMap<string, AnySignal>;
-    readonly provisions: ReadonlyMap<string, AnyProvision>;
+    readonly resources: ReadonlyMap<string, AnyResource>;
     readonly count: number;
-    readonly provisionCount: number;
+    readonly contourCount: number;
+    readonly resourceCount: number;
+    getContour(name: string): AnyContour | undefined;
     get(id: string): AnyTrail | undefined;
-    getProvision(id: string): AnyProvision | undefined;
+    getResource(id: string): AnyResource | undefined;
+    hasContour(name: string): boolean;
     has(id: string): boolean;
-    hasProvision(id: string): boolean;
+    hasResource(id: string): boolean;
+    contourIds(): string[];
     ids(): string[];
-    provisionIds(): string[];
+    resourceIds(): string[];
+    listContours(): AnyContour[];
     list(): AnyTrail[];
     listSignals(): AnySignal[];
-    listProvisions(): AnyProvision[];
+    listResources(): AnyResource[];
 }
-export declare const topo: (name: string, ...modules: Record<string, unknown>[]) => Topo;
+export declare const topo: (nameOrIdentity: string | TopoIdentity, ...modules: Record<string, unknown>[]) => Topo;
 //# sourceMappingURL=topo.d.ts.map

package/dist/topo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"topo.d.ts","sourceRoot":"","sources":["../src/topo.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAM3C,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC/C,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACjD,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;IACtC,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAAC;IACnD,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAClC,GAAG,IAAI,MAAM,EAAE,CAAC;IAChB,YAAY,IAAI,MAAM,EAAE,CAAC;IACzB,IAAI,IAAI,QAAQ,EAAE,CAAC;IACnB,WAAW,IAAI,SAAS,EAAE,CAAC;IAC3B,cAAc,IAAI,YAAY,EAAE,CAAC;CAClC;AA4ID,eAAO,MAAM,IAAI,GACf,MAAM,MAAM,EACZ,GAAG,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KACpC,IAUF,CAAC"}
+{"version":3,"file":"topo.d.ts","sourceRoot":"","sources":["../src/topo.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAM/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAM3C,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC/C,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACjD,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACrD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IACjD,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;IACtC,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;IACjD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAClC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IACjC,UAAU,IAAI,MAAM,EAAE,CAAC;IACvB,GAAG,IAAI,MAAM,EAAE,CAAC;IAChB,WAAW,IAAI,MAAM,EAAE,CAAC;IACxB,YAAY,IAAI,UAAU,EAAE,CAAC;IAC7B,IAAI,IAAI,QAAQ,EAAE,CAAC;IACnB,WAAW,IAAI,SAAS,EAAE,CAAC;IAC3B,aAAa,IAAI,WAAW,EAAE,CAAC;CAChC;AA4XD,eAAO,MAAM,IAAI,GACf,gBAAgB,MAAM,GAAG,YAAY,EACrC,GAAG,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KACpC,IAsBF,CAAC"}