@pikku/cli 0.12.103 → 0.12.105

package/dist/src/server/node-server-runner.js

@@ -5,14 +5,17 @@
  */
 import { LocalEventHubService } from '@pikku/core/channel/local';
 import { PikkuNodeHTTPServer } from '@pikku/node-http-server';
-import { pikkuWebsocketHandler } from '@pikku/ws';
+import { DEFAULT_WS_MAX_PAYLOAD, pikkuWebsocketHandler } from '@pikku/ws';
 import { WebSocketServer } from 'ws';
 export class NodeServerRunner {
     async createEventHub() {
         return new LocalEventHubService();
     }
     createServer(config, logger, options = {}) {
-        const wss = new WebSocketServer({ noServer: true });
+        const wss = new WebSocketServer({
+            noServer: true,
+            maxPayload: DEFAULT_WS_MAX_PAYLOAD,
+        });
         const server = new PikkuNodeHTTPServer(config, logger, {
             configureServer: (httpServer) => {
                 pikkuWebsocketHandler({ server: httpServer, wss, logger });

package/dist/src/services/cli-logger.service.js

@@ -1,6 +1,6 @@
 import chalk from 'chalk';
 import { LogLevel } from '@pikku/core/services';
-import { isExpectedError } from '@pikku/core';
+import { isExpectedError } from '@pikku/core/ecosystem/types';
 // Compact one-line wordmark — the old multi-line ASCII art got cropped in
 // short/narrow AI-agent panes. Coloured directly (not via the blue `info`
 // path) so the cyan/bold render correctly.

package/dist/src/utils/precise-coverage-map.d.ts

@@ -1,4 +1,4 @@
-import type { CoverageFunctionMeta, FunctionCoverageReport, ScriptCoverage as ScriptCoverageInput } from '@pikku/core/services';
+import type { CoverageFunctionMeta, FunctionCoverageReport, ScriptCoverage as ScriptCoverageInput } from '@pikku/core/ecosystem/services';
 export type { ScriptCoverageInput };
 export declare function mapPreciseCoverage(scripts: ScriptCoverageInput[], getScriptSource: (scriptId: string) => Promise<string>, functionsMeta: Record<string, CoverageFunctionMeta>): Promise<FunctionCoverageReport>;
 export declare function mapLineHitsToReport(lineHits: Map<string, Map<number, number>>, functionsMeta: Record<string, CoverageFunctionMeta>): FunctionCoverageReport;

package/dist/src/utils/remove-legacy-scaffold-file.d.ts

@@ -14,4 +14,18 @@ export declare const removeLegacyScaffoldFile: (file: string) => Promise<void>;
  * to write to, this removes a file pikku no longer writes at all.
  */
 export declare const removeRetiredScaffoldFiles: (config: PikkuCLIConfig) => Promise<void>;
+/**
+ * Delete agent scaffolds that import an entry point pikku no longer publishes.
+ *
+ * A scaffold is written once, when missing, and left alone afterwards so a
+ * project can edit it. That is the right default until the import at the top
+ * stops resolving: the file then fails to compile and pikku will not replace it,
+ * because it is still there. Deleting it puts it back in the missing set, so the
+ * same `pikku all` regenerates it against the current entry point.
+ *
+ * Only the two `@pikku/core` paths #596 renamed count as stale. Anything a
+ * project added to the file is lost with it — which is why this is keyed to an
+ * import that cannot compile rather than to the file simply being out of date.
+ */
+export declare const refreshScaffoldsImportingRemovedEntryPoints: (config: PikkuCLIConfig) => Promise<void>;
 export declare const pruneLegacyScaffoldFiles: (config: PikkuCLIConfig) => Promise<void>;

package/dist/src/utils/remove-legacy-scaffold-file.js

@@ -1,5 +1,5 @@
 import { rm } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
 const scaffoldFiles = (config) => {
     const authDir = config.authFile ? dirname(config.authFile) : undefined;
@@ -57,6 +57,33 @@ export const removeRetiredScaffoldFiles = async (config) => {
         }
     }
 };
+/**
+ * Entry points a scaffold may still import after #596 renamed them.
+ */
+const REMOVED_ENTRY_POINTS = ['@pikku/core/ai-agent', '@pikku/core/ai-scorer'];
+/**
+ * Delete agent scaffolds that import an entry point pikku no longer publishes.
+ *
+ * A scaffold is written once, when missing, and left alone afterwards so a
+ * project can edit it. That is the right default until the import at the top
+ * stops resolving: the file then fails to compile and pikku will not replace it,
+ * because it is still there. Deleting it puts it back in the missing set, so the
+ * same `pikku all` regenerates it against the current entry point.
+ *
+ * Only the two `@pikku/core` paths #596 renamed count as stale. Anything a
+ * project added to the file is lost with it — which is why this is keyed to an
+ * import that cannot compile rather than to the file simply being out of date.
+ */
+export const refreshScaffoldsImportingRemovedEntryPoints = async (config) => {
+    for (const file of [config.publicAgentFile, config.publicAgentSchemasFile]) {
+        if (!file || !existsSync(file))
+            continue;
+        const contents = readFileSync(file, 'utf-8');
+        if (REMOVED_ENTRY_POINTS.some((entry) => contents.includes(entry))) {
+            await rm(file, { force: true });
+        }
+    }
+};
 export const pruneLegacyScaffoldFiles = async (config) => {
     for (const file of scaffoldFiles(config)) {
         if (file) {

package/dist/src/utils/resolve-personas.d.ts

@@ -1,5 +1,5 @@
-import type { PersonaDefinitions } from '@pikku/core/persona';
-import type { ResolvedPersona } from '@pikku/core/services';
+import type { PersonaDefinitions } from '@pikku/core/ecosystem/persona';
+import type { ResolvedPersona } from '@pikku/core/ecosystem/services';
 /**
  * Where a persona's mail lands when the project has not said.
  *
@@ -24,4 +24,4 @@ export declare const resolvePersonas: (definitions: PersonaDefinitions, domain?:
  * needs the same expansion at runtime, so it lives in core beside
  * `prepareVirtualUserRun` and this keeps the CLI's existing import sites.
  */
-export { personaScopes } from '@pikku/core/virtual-user';
+export { personaScopes } from '@pikku/core/ecosystem/virtual-user';

package/dist/src/utils/resolve-personas.js

@@ -1,4 +1,4 @@
-import { personaEmails, validateAndBuildPersonasMeta, } from '@pikku/core/persona';
+import { personaEmails, validateAndBuildPersonasMeta, } from '@pikku/core/ecosystem/persona';
 /**
  * Where a persona's mail lands when the project has not said.
  *
@@ -32,4 +32,4 @@ export const resolvePersonas = (definitions, domain = DEFAULT_PERSONA_EMAIL_DOMA
  * needs the same expansion at runtime, so it lives in core beside
  * `prepareVirtualUserRun` and this keeps the CLI's existing import sites.
  */
-export { personaScopes } from '@pikku/core/virtual-user';
+export { personaScopes } from '@pikku/core/ecosystem/virtual-user';

package/dist/src/utils/schema-diff.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Field-level compatibility diff between two JSON Schemas.
+ *
+ * Whether a change breaks anyone depends on which way the data flows, so every
+ * comparison carries a `direction`. An input schema is contravariant — the
+ * caller writes it, so tightening (a new required field, a narrower enum) is
+ * what breaks. An output schema is covariant — the caller reads it, so
+ * loosening (a field that may now be absent, a new enum member the consumer
+ * never handled) is what breaks. Removing a field breaks in both directions.
+ */
+export type SchemaDirection = 'input' | 'output';
+export interface SchemaChange {
+    /** Dotted path from the schema root, `[]` marking array items. */
+    path: string;
+    breaking: boolean;
+    reason: string;
+}
+/**
+ * Diff two schemas, either of which may be absent — a function that gained or
+ * lost an input/output entirely is a real compatibility event, not a no-op.
+ */
+export declare function diffSchema(before: unknown, after: unknown, direction: SchemaDirection): SchemaChange[];

package/dist/src/utils/schema-diff.js

@@ -0,0 +1,190 @@
+/**
+ * Field-level compatibility diff between two JSON Schemas.
+ *
+ * Whether a change breaks anyone depends on which way the data flows, so every
+ * comparison carries a `direction`. An input schema is contravariant — the
+ * caller writes it, so tightening (a new required field, a narrower enum) is
+ * what breaks. An output schema is covariant — the caller reads it, so
+ * loosening (a field that may now be absent, a new enum member the consumer
+ * never handled) is what breaks. Removing a field breaks in both directions.
+ */
+const isSchema = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const joinPath = (parent, key) => parent ? `${parent}.${key}` : key;
+/**
+ * Resolve local `#/definitions/...` / `#/$defs/...` pointers against the root
+ * they were authored in. Anything non-local is left alone — an unresolvable
+ * `$ref` is compared as the opaque object it is rather than guessed at.
+ */
+function deref(schema, root, seen) {
+    let current = schema;
+    while (typeof current.$ref === 'string') {
+        const ref = current.$ref;
+        if (!ref.startsWith('#/') || seen.has(ref))
+            return current;
+        seen.add(ref);
+        let target = root;
+        for (const rawSegment of ref.slice(2).split('/')) {
+            const segment = rawSegment.replace(/~1/g, '/').replace(/~0/g, '~');
+            if (!isSchema(target))
+                return current;
+            target = target[segment];
+        }
+        if (!isSchema(target))
+            return current;
+        current = target;
+    }
+    return current;
+}
+const typeOf = (schema) => {
+    const type = schema.type;
+    if (typeof type === 'string')
+        return type;
+    if (Array.isArray(type))
+        return [...type].sort().join('|');
+    return undefined;
+};
+const requiredSet = (schema) => new Set(Array.isArray(schema.required) ? schema.required : []);
+const propertiesOf = (schema) => isSchema(schema.properties) ? schema.properties : {};
+/**
+ * `additionalProperties: false` is what makes an unknown key an error, so a
+ * removed input field only breaks callers when the schema is closed.
+ */
+const isClosed = (schema) => schema.additionalProperties === false;
+function compare(beforeRaw, afterRaw, direction, path, beforeRoot, afterRoot, depth, changes) {
+    // Deep enough to have left any sane generated schema behind; a cyclic pair of
+    // `$ref`s that dodges the per-branch guard stops here rather than recursing.
+    if (depth > 24)
+        return;
+    const before = deref(beforeRaw, beforeRoot, new Set());
+    const after = deref(afterRaw, afterRoot, new Set());
+    const beforeType = typeOf(before);
+    const afterType = typeOf(after);
+    if (beforeType !== afterType && (beforeType || afterType)) {
+        changes.push({
+            path,
+            breaking: true,
+            reason: `type changed from ${beforeType ?? 'unknown'} to ${afterType ?? 'unknown'}`,
+        });
+        return;
+    }
+    compareEnums(before, after, direction, path, changes);
+    const beforeProps = propertiesOf(before);
+    const afterProps = propertiesOf(after);
+    const beforeRequired = requiredSet(before);
+    const afterRequired = requiredSet(after);
+    for (const key of Object.keys(beforeProps)) {
+        const childPath = joinPath(path, key);
+        if (!(key in afterProps)) {
+            // Dropping an input field only breaks callers that still send it, which
+            // is only an error against a closed schema.
+            const breaking = direction === 'output' || isClosed(after);
+            changes.push({
+                path: childPath,
+                breaking,
+                reason: breaking
+                    ? 'field removed'
+                    : 'field removed (schema accepts additional properties)',
+            });
+            continue;
+        }
+        if (beforeRequired.has(key) && !afterRequired.has(key)) {
+            changes.push({
+                path: childPath,
+                breaking: direction === 'output',
+                reason: direction === 'output'
+                    ? 'field is no longer guaranteed to be present'
+                    : 'field became optional',
+            });
+        }
+        else if (!beforeRequired.has(key) && afterRequired.has(key)) {
+            changes.push({
+                path: childPath,
+                breaking: direction === 'input',
+                reason: direction === 'input'
+                    ? 'optional field became required'
+                    : 'field is now always present',
+            });
+        }
+        compare(beforeProps[key], afterProps[key], direction, childPath, beforeRoot, afterRoot, depth + 1, changes);
+    }
+    for (const key of Object.keys(afterProps)) {
+        if (key in beforeProps)
+            continue;
+        const childPath = joinPath(path, key);
+        const required = afterRequired.has(key);
+        const breaking = direction === 'input' && required;
+        changes.push({
+            path: childPath,
+            breaking,
+            reason: breaking
+                ? 'required field added'
+                : `${required ? 'required' : 'optional'} field added`,
+        });
+    }
+    if (isSchema(before.items) && isSchema(after.items)) {
+        compare(before.items, after.items, direction, `${path}[]`, beforeRoot, afterRoot, depth + 1, changes);
+    }
+}
+function compareEnums(before, after, direction, path, changes) {
+    if (!Array.isArray(before.enum) || !Array.isArray(after.enum))
+        return;
+    const beforeValues = before.enum.map((v) => JSON.stringify(v));
+    const afterValues = new Set(after.enum.map((v) => JSON.stringify(v)));
+    const beforeSet = new Set(beforeValues);
+    const removed = beforeValues.filter((v) => !afterValues.has(v));
+    const added = after.enum
+        .map((v) => JSON.stringify(v))
+        .filter((v) => !beforeSet.has(v));
+    if (removed.length > 0) {
+        changes.push({
+            path,
+            // A value the caller may still send is now rejected; a value the caller
+            // will simply never see again is not their problem.
+            breaking: direction === 'input',
+            reason: `enum values removed: ${removed.join(', ')}`,
+        });
+    }
+    if (added.length > 0) {
+        changes.push({
+            path,
+            // A new value in a response reaches consumers that never handled it.
+            breaking: direction === 'output',
+            reason: `enum values added: ${added.join(', ')}`,
+        });
+    }
+}
+/**
+ * Diff two schemas, either of which may be absent — a function that gained or
+ * lost an input/output entirely is a real compatibility event, not a no-op.
+ */
+export function diffSchema(before, after, direction) {
+    const hasBefore = isSchema(before);
+    const hasAfter = isSchema(after);
+    if (!hasBefore && !hasAfter)
+        return [];
+    if (!hasBefore && hasAfter) {
+        const required = requiredSet(after);
+        const breaking = direction === 'input' && required.size > 0;
+        return [
+            {
+                path: '',
+                breaking,
+                reason: breaking
+                    ? `${direction} schema added with required fields: ${[...required].join(', ')}`
+                    : `${direction} schema added`,
+            },
+        ];
+    }
+    if (hasBefore && !hasAfter) {
+        return [
+            {
+                path: '',
+                breaking: direction === 'output',
+                reason: `${direction} schema removed`,
+            },
+        ];
+    }
+    const changes = [];
+    compare(before, after, direction, '', before, after, 0, changes);
+    return changes;
+}

package/dist/src/utils/serialize-schemas.d.ts

@@ -1,4 +1,4 @@
-import type { JSONValue } from '@pikku/core';
+import type { JSONValue } from '@pikku/core/ecosystem/types';
 import type { CLILogger } from '../services/cli-logger.service.js';
 export declare function saveSchemas(logger: CLILogger, schemaParentDir: string, schemas: Record<string, JSONValue>, requiredSchemas: Set<string>, supportsImportAttributes: boolean, packageName?: string | null, 
 /** Names the set in log output — there is more than one now (app, scenario). */

package/dist/src/utils/serialize-schemas.js

@@ -125,7 +125,7 @@ addSchema('${schema}', ${identifier}${packageNameArg})
     })
         .join('\n');
     const importStatement = availableSchemas.length > 0
-        ? `import { addSchema } from '@pikku/core/schema'`
+        ? `import { addSchema } from '@pikku/core/ecosystem/schema'`
         : '// No schemas to register';
     await writeFileInDir(logger, `${schemaParentDir}/register.gen.ts`, `${importStatement}
 ${schemaImports}`, { logWrite: true });

package/dist/src/utils/surface-diff.d.ts

@@ -0,0 +1,35 @@
+import type { Surface, WiringCategory } from './surface.js';
+/**
+ * Turn two surfaces into the release verdict and the reasons behind it.
+ *
+ * The three rules, in order: anything a client depended on that is gone or
+ * tightened is **major**; anything new or compatibly loosened is **minor**;
+ * a surface that did not move at all is **patch** — the release is internal
+ * work, which is the only thing left for it to be.
+ */
+export type Verdict = 'major' | 'minor' | 'patch';
+export type ChangeKind = 'function' | WiringCategory;
+export type ChangeStatus = 'added' | 'removed' | 'modified';
+export interface SurfaceChange {
+    kind: ChangeKind;
+    id: string;
+    status: ChangeStatus;
+    breaking: boolean;
+    reasons: string[];
+}
+export interface SurfaceChanges {
+    schemaVersion: number;
+    generatedAt: string;
+    /** The `--against` value, recorded so the artifact says what it is relative to. */
+    baseline: string;
+    verdict: Verdict;
+    summary: {
+        breaking: number;
+        added: number;
+        removed: number;
+        modified: number;
+    };
+    changes: SurfaceChange[];
+}
+export declare const CHANGES_SCHEMA_VERSION = 1;
+export declare function computeSurfaceDiff(before: Surface, after: Surface, baseline: string): SurfaceChanges;

package/dist/src/utils/surface-diff.js

@@ -0,0 +1,183 @@
+import { diffSchema } from './schema-diff.js';
+export const CHANGES_SCHEMA_VERSION = 1;
+const STATUS_ORDER = {
+    removed: 0,
+    modified: 1,
+    added: 2,
+};
+const describe = (change, side) => `${side}${change.path ? `.${change.path}` : ''}: ${change.reason}`;
+/**
+ * Published versions are immutable, so a function id that vanished from the
+ * source is still being served while the manifest records it — that is a `@vN`
+ * bump, not a removal.
+ */
+function stillPublished(surface, key, version) {
+    return (surface.publishedVersions[key] ?? []).includes(version);
+}
+function diffFunctions(before, after, changes) {
+    const ids = new Set([
+        ...Object.keys(before.functions),
+        ...Object.keys(after.functions),
+    ]);
+    for (const id of [...ids].sort()) {
+        const previous = before.functions[id];
+        const current = after.functions[id];
+        if (previous && !current) {
+            const superseded = stillPublished(after, previous.key, previous.version);
+            changes.push({
+                kind: 'function',
+                id,
+                status: 'removed',
+                breaking: !superseded,
+                reasons: [
+                    superseded
+                        ? `no longer in the source, but v${previous.version} is still published in versions.pikku.json`
+                        : 'function removed',
+                ],
+            });
+            continue;
+        }
+        if (!previous && current) {
+            const priorVersions = before.publishedVersions[current.key] ?? [];
+            changes.push({
+                kind: 'function',
+                id,
+                status: 'added',
+                breaking: false,
+                reasons: [
+                    priorVersions.length > 0
+                        ? `new version of ${current.key} (previously v${priorVersions.join(', v')})`
+                        : 'function added',
+                ],
+            });
+            continue;
+        }
+        if (!previous || !current)
+            continue;
+        const reasons = [];
+        let breaking = false;
+        const pairs = [
+            {
+                side: 'input',
+                before: previous.inputSchemaName,
+                after: current.inputSchemaName,
+            },
+            {
+                side: 'output',
+                before: previous.outputSchemaName,
+                after: current.outputSchemaName,
+            },
+        ];
+        let unresolved = false;
+        for (const pair of pairs) {
+            const beforeSchema = pair.before ? before.schemas[pair.before] : undefined;
+            const afterSchema = pair.after ? after.schemas[pair.after] : undefined;
+            // A named schema whose body did not travel with the snapshot cannot be
+            // compared; fall through to the hash so it is never silently "unchanged".
+            if ((pair.before && beforeSchema === undefined) ||
+                (pair.after && afterSchema === undefined)) {
+                unresolved = true;
+                continue;
+            }
+            for (const change of diffSchema(beforeSchema, afterSchema, pair.side)) {
+                if (change.breaking)
+                    breaking = true;
+                reasons.push(describe(change, pair.side));
+            }
+        }
+        if (unresolved &&
+            previous.contractHash !== undefined &&
+            current.contractHash !== undefined &&
+            previous.contractHash !== current.contractHash) {
+            // The contract moved but the schemas were not available to say how.
+            // Treating that as compatible would be a guess in the unsafe direction.
+            breaking = true;
+            reasons.push('contract hash changed, and the schemas were not available to determine whether it is breaking');
+        }
+        if (reasons.length > 0) {
+            changes.push({
+                kind: 'function',
+                id,
+                status: 'modified',
+                breaking,
+                reasons,
+            });
+        }
+    }
+}
+const authRequired = (meta) => !!meta &&
+    typeof meta === 'object' &&
+    meta.auth === true;
+function diffWirings(before, after, changes) {
+    const categories = new Set([
+        ...Object.keys(before.wirings),
+        ...Object.keys(after.wirings),
+    ]);
+    for (const category of [...categories].sort()) {
+        const previous = before.wirings[category] ?? {};
+        const current = after.wirings[category] ?? {};
+        const ids = new Set([...Object.keys(previous), ...Object.keys(current)]);
+        for (const id of [...ids].sort()) {
+            const inBefore = id in previous;
+            const inAfter = id in current;
+            if (inBefore && !inAfter) {
+                changes.push({
+                    kind: category,
+                    id,
+                    status: 'removed',
+                    breaking: true,
+                    reasons: [`${category} wiring removed`],
+                });
+            }
+            else if (!inBefore && inAfter) {
+                changes.push({
+                    kind: category,
+                    id,
+                    status: 'added',
+                    breaking: false,
+                    reasons: [`${category} wiring added`],
+                });
+            }
+            else if (JSON.stringify(previous[id]) !== JSON.stringify(current[id])) {
+                // Requiring a session on something that did not is the one wiring-level
+                // change that shuts out existing callers outright.
+                const closed = !authRequired(previous[id]) && authRequired(current[id]);
+                changes.push({
+                    kind: category,
+                    id,
+                    status: 'modified',
+                    breaking: closed,
+                    reasons: [
+                        closed
+                            ? `${category} wiring now requires authentication`
+                            : `${category} wiring changed`,
+                    ],
+                });
+            }
+        }
+    }
+}
+export function computeSurfaceDiff(before, after, baseline) {
+    const changes = [];
+    diffFunctions(before, after, changes);
+    diffWirings(before, after, changes);
+    changes.sort((a, b) => Number(b.breaking) - Number(a.breaking) ||
+        STATUS_ORDER[a.status] - STATUS_ORDER[b.status] ||
+        a.kind.localeCompare(b.kind) ||
+        a.id.localeCompare(b.id));
+    const summary = {
+        breaking: changes.filter((c) => c.breaking).length,
+        added: changes.filter((c) => c.status === 'added').length,
+        removed: changes.filter((c) => c.status === 'removed').length,
+        modified: changes.filter((c) => c.status === 'modified').length,
+    };
+    const verdict = summary.breaking > 0 ? 'major' : changes.length > 0 ? 'minor' : 'patch';
+    return {
+        schemaVersion: CHANGES_SCHEMA_VERSION,
+        generatedAt: new Date().toISOString(),
+        baseline,
+        verdict,
+        summary,
+        changes,
+    };
+}

package/dist/src/utils/surface.d.ts

@@ -0,0 +1,51 @@
+import type { VersionManifest } from '@pikku/inspector';
+import { type MetaDiffCategoryName } from './meta-diff.js';
+/**
+ * A "surface" is everything about a build that a client can observe: the
+ * functions, the JSON Schemas of what they take and return, and the wirings
+ * that expose them. It is derived from `.pikku` rather than stored there, so a
+ * baseline can be a checkout on disk or a snapshot published from CI — the
+ * comparison is the same either way.
+ */
+export declare const SURFACE_SCHEMA_VERSION = 1;
+/** Meta categories that expose a function to a client. */
+export type WiringCategory = Exclude<MetaDiffCategoryName, 'functions'>;
+export interface SurfaceFunction {
+    /** Function id with any `@vN` suffix stripped. */
+    key: string;
+    version: number;
+    inputSchemaName: string | null;
+    outputSchemaName: string | null;
+    contractHash?: string;
+}
+export interface Surface {
+    schemaVersion: number;
+    generatedAt: string;
+    /** Keyed by function id exactly as the meta records it, `@vN` included. */
+    functions: Record<string, SurfaceFunction>;
+    /** Only the schemas some function actually references. */
+    schemas: Record<string, unknown>;
+    wirings: Partial<Record<WiringCategory, Record<string, unknown>>>;
+    /**
+     * `functionKey → published version numbers`, lifted from
+     * `versions.pikku.json`. Published versions are immutable, so a version the
+     * manifest still records is still being served even when the source has
+     * moved on — that is what stops a `@v2` bump reading as a removal.
+     */
+    publishedVersions: Record<string, number[]>;
+}
+/** Build a surface from a generated `.pikku` directory. */
+export declare function readSurface(pikkuDir: string, manifest?: VersionManifest | null): Surface;
+export type FetchLike = (url: string) => Promise<{
+    ok: boolean;
+    status: number;
+    statusText: string;
+    text(): Promise<string>;
+}>;
+/**
+ * Resolve a baseline. A URL fetches a published snapshot; a path is read as a
+ * `.pikku` directory when it is one, and as a snapshot file otherwise — so
+ * `--against ../other-app/.pikku` and `--against ./prod-surface.json` both work
+ * without a second flag to say which is which.
+ */
+export declare function loadSurface(source: string, fetchImpl?: FetchLike): Promise<Surface>;