@aisy/core 0.1.0

package/dist/observability/index.js

@@ -0,0 +1,396 @@
+import { createHash } from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Hashing helper — node:crypto, deterministic over canonical JSON.
+// ---------------------------------------------------------------------------
+function sha256(input) {
+    return createHash('sha256').update(input).digest('hex');
+}
+/** Stable JSON: sorts object keys recursively so the hash is order-insensitive. */
+function canonical(value) {
+    return JSON.stringify(sortKeys(value));
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value !== null && typeof value === 'object') {
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            out[key] = sortKeys(value[key]);
+        }
+        return out;
+    }
+    return value;
+}
+// ---------------------------------------------------------------------------
+// Trace verifier / VerificationRunner (§5.1, ADR-0017, ADR-0026)
+//
+// Deterministic effect matching. The model is never on this path: a step
+// closes only when the injected EffectProbe confirms the declared criterion
+// against the real world. Every failure mode (absent effect, probe throw,
+// unbound probe) is fail-closed → pass:false, never "pass on error" (§7).
+// ---------------------------------------------------------------------------
+export function makeVerificationRunner() {
+    return {
+        async verify(trace, probe) {
+            // Cold start / unbound probe seam (AC-12-23): fail-closed. With no probe
+            // bound there is no effect to confirm, so verify() refuses (throws) rather
+            // than fabricating a verdict — no step can close. Both throw and pass:false
+            // are fail-closed; the contract here is a hard refusal.
+            if (probe === null || probe === undefined) {
+                throw new Error('effect probe not bound (cold start) — verification fail-closed');
+            }
+            try {
+                switch (trace.kind) {
+                    case 'file': {
+                        // pass iff exists === existsExpected AND, when sha256 declared, the
+                        // content hash matches — content is the effect, not mere presence.
+                        const observed = await probe.file(trace.path);
+                        if (observed.exists !== trace.existsExpected) {
+                            return { pass: false, kind: 'file', observed, reason: `file exists=${observed.exists}, expected ${trace.existsExpected}` };
+                        }
+                        if (trace.sha256 !== undefined && observed.sha256 !== trace.sha256) {
+                            return { pass: false, kind: 'file', observed, reason: `sha256 ${observed.sha256 ?? '<none>'} != declared ${trace.sha256}` };
+                        }
+                        return { pass: true, kind: 'file', observed };
+                    }
+                    case 'sql': {
+                        // pass iff the returned row count satisfies the predicate.
+                        const observed = await probe.sql(trace.query);
+                        const ok = matchRows(observed.rows, trace.expectRows);
+                        return ok
+                            ? { pass: true, kind: 'sql', observed }
+                            : { pass: false, kind: 'sql', observed, reason: `rows ${observed.rows} fails predicate ${JSON.stringify(trace.expectRows)}` };
+                    }
+                    case 'http': {
+                        // pass iff response status equals the expected status.
+                        const observed = await probe.http(trace.method, trace.url);
+                        return observed.status === trace.expectStatus
+                            ? { pass: true, kind: 'http', observed }
+                            : { pass: false, kind: 'http', observed, reason: `status ${observed.status} != expected ${trace.expectStatus}` };
+                    }
+                    case 'exit': {
+                        // pass iff the process exit code equals the expected code.
+                        const observed = await probe.exit(trace.argv);
+                        return observed.code === trace.expectCode
+                            ? { pass: true, kind: 'exit', observed }
+                            : { pass: false, kind: 'exit', observed, reason: `exit ${observed.code} != expected ${trace.expectCode}` };
+                    }
+                }
+            }
+            catch (err) {
+                // §7 dependency-unavailable: probe raised/timed out → trace failed.
+                const reason = err instanceof Error ? err.message : String(err);
+                return { pass: false, kind: trace.kind, observed: null, reason: `probe error: ${reason}` };
+            }
+        },
+    };
+}
+function matchRows(rows, expect) {
+    if (typeof expect === 'number')
+        return rows === expect;
+    switch (expect.op) {
+        case '=': return rows === expect.n;
+        case '>': return rows > expect.n;
+        case '>=': return rows >= expect.n;
+    }
+}
+// ---------------------------------------------------------------------------
+// Trace linter R1–R5 (§4 data structures, ADR-0026, Eng-5)
+//
+// Runs at plan time, before the gate. The first failing step short-circuits.
+// The gate is never downgraded: a broken plan is a hard rejection (§7).
+// ---------------------------------------------------------------------------
+const VALID_TRACE_KINDS = new Set(['file', 'sql', 'http', 'exit']);
+/** Tier ≥ 2 tools (ADR-0011): any write/send/exec/db/git tool is irreversible. */
+function isTier2Tool(tool) {
+    return (/write|send|delete|exec|drop|push/i.test(tool) ||
+        /^(git|db|telegram|http|fs)[._]/i.test(tool) ||
+        tool === 'bash');
+}
+/** R3 no-op argv: the exit trace asserts nothing about the world. */
+function isNoOpArgv(argv) {
+    const cmd = argv[0];
+    if (cmd === undefined)
+        return true;
+    return cmd === 'echo' || cmd === 'true' || cmd === ':' || cmd === 'printf';
+}
+/** R4 self-referential: a file trace pointing at the model's own plan artifact. */
+function isSelfReferentialPath(path) {
+    const base = path.split('/').pop() ?? path;
+    return base === 'PLAN.md' || base === 'TODO.md';
+}
+export function makeTraceLinter() {
+    return {
+        lint(plan) {
+            // Set of paths produced by some step in the plan. A file trace whose
+            // target is in this set asserts a real effect the plan created; a trace
+            // whose target is NOT produced by any step only re-asserts a pre-existing
+            // file, which proves nothing (R3 vacuous, §4.4).
+            const producedPaths = new Set();
+            for (const s of plan.steps) {
+                if (s.producesPath !== undefined)
+                    producedPaths.add(s.producesPath);
+            }
+            for (let i = 0; i < plan.steps.length; i++) {
+                const step = plan.steps[i];
+                const trace = step.trace;
+                // R1 missing — a step has no trace.
+                if (trace === undefined || trace === null) {
+                    return { ok: false, rule: 'R1', stepIndex: i };
+                }
+                // R5 out-of-enum — kind outside file | sql | http | exit.
+                if (!VALID_TRACE_KINDS.has(trace.kind)) {
+                    return { ok: false, rule: 'R5', stepIndex: i };
+                }
+                // R2 unflagged-irreversible — Tier ≥ 2 tool but irreversible !== true.
+                if (step.irreversible !== true && step.tools.some(isTier2Tool)) {
+                    return { ok: false, rule: 'R2', stepIndex: i };
+                }
+                // R4 self-referential — file trace pointing at PLAN.md/TODO.md.
+                if (trace.kind === 'file' && isSelfReferentialPath(trace.path)) {
+                    return { ok: false, rule: 'R4', stepIndex: i };
+                }
+                // R3 vacuous — the trace asserts nothing about the world.
+                if (trace.kind === 'exit' && isNoOpArgv(trace.argv)) {
+                    return { ok: false, rule: 'R3', stepIndex: i };
+                }
+                if (trace.kind === 'http' && isLoopback(trace.url) && isReadMethod(trace.method)) {
+                    return { ok: false, rule: 'R3', stepIndex: i };
+                }
+                // R3 pre-existing target — a file trace whose path is not produced by any
+                // step in the plan re-asserts a file that already existed; verifying
+                // something already true proves no effect (§4.4).
+                if (trace.kind === 'file' && !producedPaths.has(trace.path)) {
+                    return { ok: false, rule: 'R3', stepIndex: i };
+                }
+            }
+            return { ok: true };
+        },
+    };
+}
+function isLoopback(url) {
+    return /^https?:\/\/(localhost|127\.0\.0\.1|\[::1\])/i.test(url);
+}
+function isReadMethod(method) {
+    return ['GET', 'HEAD'].includes(method.toUpperCase());
+}
+// ---------------------------------------------------------------------------
+// Cycle detector (§4 tool-call signature; ADR-0020)
+//
+// Detects a period-1/2/3 cycle in the trailing window. A cycle "trips" only
+// when it repeats strictly more than `threshold` times (default 3, configurable
+// per §4/§10 and GuardianDeps.tripThreshold) — i.e. the trailing run forming a
+// period-p block is at least p*threshold + 1 long. Shorter periods win first so
+// A-A-A-A is period 1, not a degenerate period-2/3 reading.
+// ---------------------------------------------------------------------------
+const DEFAULT_TRIP_THRESHOLD = 3;
+export function makeCycleDetector(threshold = DEFAULT_TRIP_THRESHOLD) {
+    return {
+        detect(window) {
+            for (const period of [1, 2, 3]) {
+                if (matchesPeriod(window, period, threshold))
+                    return { period };
+            }
+            return null;
+        },
+    };
+}
+/** True when the tail of `window` is a period-`p` cycle repeating > `threshold` times. */
+function matchesPeriod(window, p, threshold) {
+    // > `threshold` repeats of a length-p block means at least p*threshold + 1
+    // trailing elements that are consistent with period p (w[i] === w[i - p]).
+    const needed = p * threshold + 1;
+    if (window.length < needed)
+        return false;
+    const start = window.length - needed;
+    for (let i = start + p; i < window.length; i++) {
+        if (window[i] !== window[i - p])
+            return false;
+    }
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Tool-call signature (§4) — order-insensitive, canonicalized.
+// ---------------------------------------------------------------------------
+function signature(call) {
+    return sha256(`${call.name}${canonical(call.args)}`);
+}
+// ---------------------------------------------------------------------------
+// Loop Guardian (§5.2, ADR-0020, Eng-12)
+//
+// Consulted on every tool dispatch. Pushes a signature into a bounded ring
+// window tagged with the current re-plan epoch, then trips on a period-1/2/3
+// cycle repeating > 3 times WITHIN the current epoch. note("replan") advances
+// the epoch (clearing the live window) but never resets a budget — Core owns
+// the monotonic cap (§5.2). On trip the run halts and stays halted; work is
+// never deleted and the Guardian never auto-resumes (AC-12-17). A window that
+// cannot be rebuilt (windowSize 0) fails safe by tripping (AC-12-27).
+// ---------------------------------------------------------------------------
+export function makeLoopGuardian(deps) {
+    const windowSize = deps.windowSize ?? 12;
+    // Wire the injected trip threshold (cap on full cycle repeats) into the
+    // detector; falls back to the default when unset (§4, §10, GuardianDeps).
+    const detector = makeCycleDetector(deps.tripThreshold ?? DEFAULT_TRIP_THRESHOLD);
+    let window = [];
+    let tripped = false;
+    // windowSize 0 means the window cannot be rebuilt after a crash; fail-safe.
+    const cannotRebuild = windowSize <= 0;
+    return {
+        observe(call) {
+            if (cannotRebuild) {
+                // §7 crash recovery: no window to protect with → pause unattended runs.
+                return { trip: true };
+            }
+            // Once halted the Guardian stays halted; it does not auto-resume.
+            if (tripped)
+                return { trip: true };
+            window.push(signature(call));
+            if (window.length > windowSize)
+                window = window.slice(window.length - windowSize);
+            const cycle = detector.detect(window);
+            if (cycle !== null) {
+                tripped = true;
+                // journal `guardian.tripped` with the offending window (best-effort:
+                // the journal write is fire-and-forget; the trip verdict is the gate).
+                // Swallow the rejection: when the journal is fail-closed (secret set not
+                // yet loaded) the forensic note is dropped on purpose — the synchronous
+                // trip verdict already halts the loop, and a leaked unhandled rejection
+                // would be worse than a missing best-effort log line.
+                void deps.journal
+                    .append('12', 'guardian.tripped', { window: [...window], period: cycle.period })
+                    .catch(() => { });
+                return { trip: true, period: cycle.period };
+            }
+            return { trip: false };
+        },
+        note(event) {
+            if (event !== 'replan')
+                return;
+            // Advance the re-plan epoch: clear the live window so signatures from the
+            // prior attempt do not count toward a cycle in the new epoch (Eng-12).
+            // This is NOT a budget reset and never widens the trip threshold.
+            // A latched trip is a permanent STOP signal (ADR-0020, §5.2): once halted
+            // the Guardian never auto-resumes, so a re-plan must NOT clear `tripped` —
+            // resuming requires an explicit human-confirmation path outside this gate.
+            window = [];
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Secret redactor (§5.3, CSO-M3)
+//
+// Strips every known vault secret VALUE from arbitrary structures before the
+// journal persists them. Safe to call before the vault is loaded — it returns
+// the value unchanged but reports isLoaded:false, which makes append()
+// fail-closed so nothing unredacted is ever written (§7).
+// ---------------------------------------------------------------------------
+export function makeSecretRedactor() {
+    let loaded = false;
+    // The literal value plus every value-derived encoding we strip (§4, §5.3,
+    // CSO-M3): raw, base64, URL-encoded, and hex. Precomputed at load time so the
+    // redact hot-path is a flat substring sweep, not a per-string re-derivation.
+    let needles = [];
+    // Derive the strippable encodings for a single secret VALUE. A secret echoed
+    // as base64 / URL-encoded / hex must never reach the journal in the clear.
+    const encodingsOf = (secret) => [
+        secret,
+        Buffer.from(secret).toString('base64'),
+        encodeURIComponent(secret),
+        Buffer.from(secret).toString('hex'),
+    ];
+    const redactString = (s) => {
+        let out = s;
+        for (const needle of needles) {
+            if (needle.length === 0)
+                continue;
+            out = out.split(needle).join('«redacted»');
+        }
+        return out;
+    };
+    const walk = (value) => {
+        if (typeof value === 'string')
+            return redactString(value);
+        if (Array.isArray(value))
+            return value.map(walk);
+        if (value !== null && typeof value === 'object') {
+            const out = {};
+            for (const [k, v] of Object.entries(value)) {
+                out[k] = walk(v);
+            }
+            return out;
+        }
+        return value;
+    };
+    return {
+        redact(value) {
+            return walk(value);
+        },
+        loadVaultValues(next) {
+            const acc = [];
+            for (const secret of next) {
+                if (secret.length === 0)
+                    continue;
+                acc.push(...encodingsOf(secret));
+            }
+            needles = acc;
+            loaded = true;
+        },
+        get isLoaded() {
+            return loaded;
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Append-only journal / AuditLog (§5.3, ADR-0021, CSO-M3)
+//
+// Each append: (1) refuses if the secret set is not loaded (fail-closed,
+// AC-12-21/§7); (2) redacts the payload BEFORE persistence; (3) assigns a
+// gap-free monotonic seq; (4) chains prevHash for tamper-evidence; (5) "fsyncs"
+// — here, commits to the in-memory durable log (the disk lineage is the same
+// shape, ADR-0021). read() verifies the prevHash chain and throws if a tamper
+// breaks it, flagging the run unverifiable (AC-12-22).
+// ---------------------------------------------------------------------------
+const GENESIS_HASH = '0'.repeat(64);
+export function makeAuditLog(deps) {
+    const entries = [];
+    const entryHash = (e) => sha256(canonical({ seq: e.seq, ts: e.ts, source: e.source, kind: e.kind, prevHash: e.prevHash, payloadHash: e.payloadHash }));
+    return {
+        async append(source, kind, payload) {
+            // Fail-closed: never persist before the known-secret set is loaded, so an
+            // unredacted value can never touch the log (CSO-M3, AC-12-21, AC-12-23).
+            if (!deps.secretRedactor.isLoaded) {
+                throw new Error('journal append refused: secret set not loaded (fail-closed)');
+            }
+            // Redact BEFORE persistence — an unredacted payload never reaches storage.
+            const redacted = deps.secretRedactor.redact(payload);
+            const seq = entries.length + 1; // monotonic, gap-free per session
+            const prev = entries[entries.length - 1];
+            const prevHash = prev ? entryHash(prev) : GENESIS_HASH;
+            const entry = {
+                seq,
+                ts: deps.clock.now(),
+                source,
+                kind,
+                prevHash,
+                payloadHash: sha256(canonical(redacted)),
+                payload: redacted,
+            };
+            entries.push(entry); // commit (fsync in the disk lineage)
+            return entry;
+        },
+        read(filter) {
+            // Tamper-evidence: verify the prevHash chain on read. A broken link flags
+            // the run unverifiable rather than silently accepting it (AC-12-22, §7).
+            let expectedPrev = GENESIS_HASH;
+            for (const e of entries) {
+                if (e.prevHash !== expectedPrev) {
+                    throw new Error(`journal chain broken at seq ${e.seq}: run is unverifiable from this point`);
+                }
+                expectedPrev = entryHash(e);
+            }
+            return entries.filter(e => (filter.kind === undefined || e.kind === filter.kind) &&
+                (filter.since === undefined || e.seq >= filter.since));
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/observability/index.js.map

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

package/dist/observability/types.d.ts

@@ -0,0 +1,139 @@
+export type { VerificationTrace, VerificationTraceFile, VerificationTraceSQL, VerificationTraceHTTP, VerificationTraceExit, ToolCall, LoopGuardian, Clock, } from '../agent-loop/types.js';
+export interface TraceResult {
+    pass: boolean;
+    kind: "file" | "sql" | "http" | "exit";
+    /** The real observed value (hash, row count, status, exit code) — redacted at journal sink */
+    observed: unknown;
+    /** Why it failed, for the human-facing card */
+    reason?: string;
+}
+/**
+ * Deterministic effect probe.
+ * Production: touches the real world.
+ * Tests: fake implementation scripted to report an absent effect (Eng-11 seam).
+ */
+export interface EffectProbe {
+    file(path: string): Promise<{
+        exists: boolean;
+        sha256?: string;
+    }> | {
+        exists: boolean;
+        sha256?: string;
+    };
+    sql(query: string): Promise<{
+        rows: number;
+    }> | {
+        rows: number;
+    };
+    http(method: string, url: string): Promise<{
+        status: number;
+    }> | {
+        status: number;
+    };
+    exit(argv: string[]): Promise<{
+        code: number;
+    }> | {
+        code: number;
+    };
+}
+export interface TraceVerifier {
+    /** Runs the probe via the injected EffectProbe and matches against the declared trace. */
+    verify(trace: import('../agent-loop/types.js').VerificationTrace, probe: EffectProbe): Promise<TraceResult>;
+}
+export type LintRule = "R1" | "R2" | "R3" | "R4" | "R5";
+export type LintResult = {
+    ok: true;
+} | {
+    ok: false;
+    rule: LintRule;
+    stepIndex: number;
+};
+export interface LintablePlanStep {
+    trace?: import('../agent-loop/types.js').VerificationTrace;
+    irreversible: boolean;
+    tools: string[];
+    producesPath?: string;
+}
+export interface TraceLinter {
+    /**
+     * Returns { ok: true } when all steps pass R1–R5.
+     * Returns { ok: false, rule, stepIndex } on the first failing step.
+     *   R1 – missing trace
+     *   R2 – Tier ≥ 2 tool but irreversible !== true
+     *   R3 – vacuous trace (no-op argv, loopback http, already-existing non-produced path)
+     *   R4 – self-referential trace (points at PLAN.md/TODO.md or the step's own prose)
+     *   R5 – out-of-enum kind
+     */
+    lint(plan: {
+        steps: LintablePlanStep[];
+    }): LintResult;
+}
+export interface JournalEntry {
+    /** Monotonic, gap-free per session */
+    seq: number;
+    /** ISO timestamp from injected Clock; never on any cached prefix */
+    ts: string;
+    /** Component id: "01".."12" */
+    source: string;
+    /** e.g. "step.verified" | "guardian.tripped" | "decision" | "verify.pass" | "verify.fail" */
+    kind: string;
+    /** Hash of previous entry for tamper-evidence chaining */
+    prevHash: string;
+    /** Hash of the payload */
+    payloadHash: string;
+    /** Already secret-redacted before append() returns */
+    payload: unknown;
+}
+export interface JournalFilter {
+    sessionId?: string;
+    kind?: string;
+    /** Inclusive lower bound on seq */
+    since?: number;
+}
+export interface Journal {
+    /** Redacts payload, chains prevHash, fsyncs. Throws when secret set not loaded. */
+    append(source: string, kind: string, payload: unknown): Promise<JournalEntry>;
+    read(filter: JournalFilter): JournalEntry[];
+}
+export interface AuditLogDeps {
+    clock: import('../agent-loop/types.js').Clock;
+    secretRedactor: SecretRedactor;
+}
+/** Alias for external callers that prefer the AuditLog name */
+export type AuditLog = Journal;
+export interface SecretRedactor {
+    /**
+     * Strips every known vault secret VALUE (and value-derived encodings) from arbitrary structures.
+     * Safe to call before the vault is loaded — returns value unchanged but tracks that
+     * no vault set is loaded, causing append() to fail-closed.
+     */
+    redact<T>(value: T): T;
+    /** Called by Safety (05) at start and on vault changes */
+    loadVaultValues(values: ReadonlySet<string>): void;
+    /** True once loadVaultValues has been called at least once */
+    readonly isLoaded: boolean;
+}
+export interface GuardianDeps {
+    /** Size of the bounded sliding window (default 12) */
+    windowSize?: number;
+    /** Trip threshold — how many full cycle repeats trigger a halt (default 3) */
+    tripThreshold?: number;
+    journal: Journal;
+}
+export interface VerificationRunner {
+    verify(trace: import('../agent-loop/types.js').VerificationTrace, probe: EffectProbe): Promise<TraceResult>;
+}
+export interface TraceEntry {
+    traceId: string;
+    stepIndex: number;
+    trace: import('../agent-loop/types.js').VerificationTrace;
+    result: TraceResult;
+    ts: string;
+}
+export interface CycleDetector {
+    /** Returns the detected period (1, 2, or 3) if a cycle of that length repeats > threshold times, else null */
+    detect(window: string[]): {
+        period: 1 | 2 | 3;
+    } | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/observability/types.d.ts.map

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

package/dist/observability/types.js

@@ -0,0 +1,4 @@
+// §3 interfaces — pure types, no implementation
+// Shared contract between Core (01) and Observability (12).
+export {};
+//# sourceMappingURL=types.js.map

package/dist/observability/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/observability/types.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,4DAA4D"}

package/dist/onboarding/index.d.ts

@@ -0,0 +1,16 @@
+import type { OnboardingOps, OnboardingDeps, InSessionCommands, InSessionDeps, BootstrapFlow, CardPort, Clock } from './types.js';
+export type { OnboardingOps, OnboardingDeps, InSessionCommands, InSessionDeps, InitResult, InitOutcome, InitStep, DoctorReport, DoctorCheck, DoctorDomain, CheckStatus, CheckSeverity, StatusReport, UsageReport, UsagePeriod, ContextBreakdown, ContextItem, BootstrapFlow, BootstrapState, BootstrapSpan, RouteTier, CostChargedEvent, PendingAction, Clock, FsPort, PrereqPort, CredentialValidators, MemoryPort, VaultPort, SandboxProbe, McpProbe, NightlyPort, CostTelemetryPort, ContextInventoryPort, EventSink, CardPort, ProviderCatalogEntry, ProviderSelection, ProvidersConfig, ProvidersOutPort, ProvidersInPort, } from './types.js';
+export { REQUIRED_ENV_KEYS, SCAFFOLD_FILES, MEMORY_TREE_FILES, MEMORY_TREE_DIRS, } from './types.js';
+export declare function makeOnboardingOps(deps: OnboardingDeps): OnboardingOps;
+export declare function makeInSessionCommands(deps: InSessionDeps): InSessionCommands;
+export interface BootstrapFlowDeps {
+    card: CardPort;
+    clock: Clock;
+    /** Ordered required setup steps (e.g. agent-name, persona, autonomy, budget). */
+    steps: string[];
+    events?: {
+        emit(event: string, payload?: unknown): void;
+    };
+}
+export declare function makeBootstrapFlow(deps: BootstrapFlowDeps): BootstrapFlow;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/onboarding/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,aAAa,EAWb,aAAa,EAGb,QAAQ,EACR,KAAK,EAKN,MAAM,YAAY,CAAA;AAKnB,YAAY,EACV,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,UAAU,EACV,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,WAAW,EACX,aAAa,EACb,YAAY,EACZ,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,aAAa,EACb,cAAc,EACd,aAAa,EACb,SAAS,EACT,gBAAgB,EAChB,aAAa,EAEb,KAAK,EACL,MAAM,EACN,UAAU,EACV,oBAAoB,EACpB,UAAU,EACV,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,WAAW,EACX,iBAAiB,EACjB,oBAAoB,EACpB,SAAS,EACT,QAAQ,EACR,oBAAoB,EACpB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,eAAe,GAChB,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,YAAY,CAAA;AAuBnB,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,cAAc,GAAG,aAAa,CA8oBrE;AAiBD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,aAAa,GAAG,iBAAiB,CAiF5E;AAQD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,QAAQ,CAAA;IACd,KAAK,EAAE,KAAK,CAAA;IACZ,iFAAiF;IACjF,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAA;KAAE,CAAA;CAC1D;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,iBAAiB,GAAG,aAAa,CAmDxE"}