@fougere/core 0.2.0-alpha.2 → 0.3.0-alpha.0

package/dist/boot/types.d.ts

@@ -0,0 +1,260 @@
+/**
+ * The boot's two ends: what `createApp` takes, and what it hands back.
+ *
+ * The scan's descriptors moved to `frond.ts` and the auth contract to `auth.ts` — this
+ * file was named after a role ("the types"), so everything with nowhere else to be
+ * landed in it, seventeen notions deep.
+ */
+import type { Container } from '@fougere/container';
+import type { Fronds } from '../scan/Fronds.js';
+import type { ScanResult } from '../scan/frond.js';
+import type { SchemaView } from '@fougere/schema';
+import type { OrmFactory } from '../orm.js';
+import type { AppMiddleware } from '../wire/middleware.js';
+import type { RpcAnswer, Transport } from '../wire/call.js';
+import type { Extension } from './AppLifecycle.js';
+import type { AuthConfig, AuthRuntime } from './auth.js';
+import type { EffectiveOperationsMap } from '../effective-operation.js';
+import type { DispatchObserver } from '../dispatch/DispatchEvent.js';
+import type { DispatchPort } from '../dispatch/DispatchPort.js';
+/** Options for createApp(). */
+export interface CreateAppOptions {
+    /** Factory function to create the container. Required. */
+    createContainer: () => Container;
+    /** Factory to auto-generate EntityOrm for each scanned entity. */
+    ormFactory?: OrmFactory;
+    /**
+     * Which source an entity's rows live in, and how to open a transaction on one — the two
+     * questions that decide whether `Together<[…]>` gets the engine's own unwind or replays
+     * inverses itself.
+     *
+     * Optional together, because a host may hand in a bare `ormFactory` and know neither. A
+     * frame then compensates: not knowing where the rows are and promising atomicity over
+     * them are two different things, and only one of them is honest.
+     */
+    sourceOf?: (entityName: string) => string;
+    transacted?: <R>(source: string, fn: (ormFactory: OrmFactory) => Promise<R>) => Promise<R>;
+    /**
+     * Builds the cross-source reader a frond gets when it declares `reads:`.
+     *
+     * A factory rather than a value, for the same reason `ormFactory` is one: core must
+     * not name a storage package, and this one costs 71 MB of downloaded extensions and a
+     * native module — nothing a first run that only wanted sqlite should carry. The host
+     * decides what backs it; `@fougere/adapter-duckdb` is one answer, not the contract.
+     *
+     * Called once per frond that asks, with the entity CLASSES its `reads:` named — a
+     * name would make the reader resolve the schema a second time.
+     */
+    sourcesFactory?: (reads: unknown[], frond: string) => Promise<unknown> | unknown;
+    /**
+     * What this app is built from — required, because producing it is what reads a disk.
+     *
+     * `scanProject` (`@fougere/core/node`) reads the fronds off the filesystem; a module a
+     * build wrote holds the same value with no disk at all. `createApp` cannot tell them
+     * apart, and that is the point: it names no builtin, so a runtime without `node:fs`
+     * runs it. `root` and `fronds` used to live here — both were arguments to the scan.
+     */
+    scan: ScanResult | (() => Promise<ScanResult> | ScanResult);
+    /**
+     * Remote fronds — label → address. What each remote hosts is discovered
+     * at the first miss (rpc.discover), never declared here.
+     */
+    remotes?: Record<string, string>;
+    /**
+     * Builds the transport used to reach `remotes` addresses. Wired by
+     * layer-2 packages (e.g. @fougere/transport-http); required when
+     * `remotes` is non-empty.
+     */
+    remoteTransport?: (url: string) => Transport;
+    /**
+     * Which realization answers which port — see `FougereConfig.ports`. Needed only
+     * when two classes extend the same port; one is resolved by convention.
+     */
+    ports?: Record<string, string>;
+    /**
+     * What this app takes on beyond its fronds, each stating what it does and what it undoes.
+     *
+     * `up` runs before `createApp` returns, in this order; `down` runs inside `dispose()`,
+     * in reverse. Three levels release in reverse of construction, which is the container's
+     * own rule read one level out: extensions first (built last), then the container, then
+     * `onDispose` — a resource opened before any of this existed.
+     *
+     * A member may be `undefined`, so a host writes a conditional one inline rather than a
+     * spread over a ternary. The framework's own two are always declared, `migrate` as an
+     * empty slot when nothing migrates: a host filling it later REPLACES that member in
+     * place instead of adding one after the seeds.
+     */
+    extensions?: ReadonlyArray<Extension | undefined>;
+    /**
+     * Released by `app.dispose()` AFTER the container, for a resource handed in rather
+     * than built here — a storage connection is the one case today.
+     *
+     * NOT an extension, and the difference is a time: this was opened BEFORE the container,
+     * so it closes after it, while an extension's `up` runs after the container and its
+     * `down` therefore runs before. A storage's migration is an extension; its connection
+     * is not, and `ResolvedStorage` declares the two beside each other.
+     */
+    onDispose?: () => Promise<void> | void;
+    /**
+     * Which protocol adapters this app serves — see `FougereConfig.adapters`.
+     * Carried onto the App so every door reads one answer instead of each host
+     * deciding for itself.
+     */
+    adapters?: Record<string, boolean | undefined>;
+    /**
+     * Carries an announced fact out of this process — a broker, a queue, a log.
+     *
+     * Called for every emission, ALONGSIDE the local dispatch and never instead of it: a
+     * listener in this process is reached directly, and this is how the others hear.
+     *
+     * It exists because the local dispatch finds its listeners by having READ their code,
+     * which stops at the repository boundary. A carrier hands the fact to a NAME; the far
+     * side subscribes to that same name from its own code, and neither ever reads the other.
+     *
+     * Its failure never reaches the emitter — same rule as a subscriber's.
+     */
+    onEmit?: (fact: string, payload: unknown) => void | Promise<void>;
+    /** Passive observers of every dispatch transition. */
+    dispatchObservers?: readonly DispatchObserver[];
+    /**
+     * Storage handle to expose to the auth provider via AuthContext.db.
+     * Required when `auth` is set.
+     */
+    db?: unknown;
+    /** Auth declaration to wire into the app at boot. */
+    auth?: AuthConfig;
+}
+/** The App object returned by createApp(). */
+export interface App extends DispatchPort {
+    /** Process-only dispatch capability used by incoming transports. */
+    local: DispatchPort;
+    /** Root container with builtins + frond scopes. */
+    container: Container;
+    /**
+     * Which protocol adapters this app declared, from `fougere.config.ts`.
+     *
+     * Read by the doors themselves, so an undeclared adapter serves nothing whatever
+     * the host mounted — the route file may exist, the middleware may be installed, and
+     * the answer is still "not here".
+     */
+    adapters: Record<string, boolean | undefined>;
+    /** Discovered fronds metadata. */
+    fronds: Fronds;
+    /** Resolve from root container (shortcut). */
+    resolve<T>(name: string): T;
+    /**
+     * Resolve an entity's schema — the local `entityClass` when it's hosted or
+     * scanned here, else reconstructed from the remote's identity card
+     * (rpc.discover → reconstruct()). The one way to get a live schema for an
+     * entity whose class may not be importable at all (another repo, another
+     * language) — a card travelled, but until now its `schema` was thrown away.
+     */
+    schemaFor(entity: string): Promise<SchemaView>;
+    /**
+     * The door a name exposes to one audience, or `undefined` when it exposes
+     * none. A named surface is CLOSED: a name with no door of its own under that
+     * surface is not in it — it never falls back to the full one.
+     *
+     * **Not always a façade**, despite the name: when the owning frond is declared
+     * remote, nothing is registered locally (`bootstrap.ts`, `declaredRemotes`) and
+     * this resolves to a doublure — a façade-shaped stand-in (`remote.ts`). The
+     * caller cannot tell, which is the point; the word here was simply wrong.
+     *
+     * The one way an adapter reaches that door. It exists so the key format stays
+     * inside core (see `facadeKeyOf`), which is what lets a projection package
+     * stay structurally typed and depend on nothing.
+     */
+    facadeFor(entity: string, surface?: string): Record<string, Function> | undefined;
+    /**
+     * The canonical contracts served beside a facade, after prefab + scan + config,
+     * binding, kind, topology and surface resolution. Check, explain and adapters read
+     * this table instead of replaying those decisions.
+     */
+    operationsFor(entity: string, surface?: string): EffectiveOperationsMap | undefined;
+    /**
+     * The facts this app has a listener for — what a carrier must subscribe to on its behalf.
+     *
+     * Derived from the signatures it scanned (`Fact<T>` in an op's parameters), so a process
+     * states what it listens to without anyone declaring it twice. The dual of `onEmit`: one
+     * says what leaves, this says what should be brought in.
+     */
+    listensTo(): string[];
+    /**
+     * Hand a fact that came from OUTSIDE to the listeners in this process — and stop there.
+     *
+     * The dual of `onEmit`, and deliberately not the same thing as announcing: resolving the
+     * emission value to deliver an inbound fact would carry it straight back out through
+     * `onEmit`, so a hub echoed every reading it received to the whole fleet. Receiving and
+     * announcing are two operations; only one of them leaves.
+     *
+     * The local dispatch is identical either way — same judge, same binding, same
+     * middlewares — so a fact off a wire is no less checked than one raised next door.
+     *
+     * **It waits, and it tells** — the opposite of announcing, on purpose. It resolves once
+     * every listener here is done, and REJECTS with an `AggregateError` if any refused. A
+     * carrier's whole job is to know whether the fact landed: at-least-once is retrying what
+     * failed, so a delivery that cannot report makes durability impossible to build above it.
+     * "Dispatch is not delivery" protects the EMITTER from a slow subscriber; a carrier is
+     * not the emitter, it is the party whose business this is.
+     *
+     * It still holds nothing. A refused fact is refused, and whether it comes back is the
+     * carrier's decision — Fougere puts the channel underneath rather than reimplementing it.
+     */
+    deliver(fact: string, payload: unknown): Promise<void>;
+    /**
+     * The storage an entity is backed by, resolved through its owning frond's scope —
+     * the dual of {@link facadeFor}. `undefined` when no loaded frond hosts the entity,
+     * or when the app booted with no storage at all.
+     *
+     * `unknown` because the port belongs to whoever wired it: narrowing it to `EntityOrm`
+     * is the caller saying which implementation they are standing on.
+     */
+    ormFor(entity: string): unknown | undefined;
+    /**
+     * The presenter of an entity, resolved through its owning frond's scope.
+     *
+     * Same shape as {@link ormFor}, and it exists so an adapter never spells the container
+     * key itself: `schema-graphql` wrote out `${Name}Presenter` by hand, and a key respelled
+     * in a second place finds nothing and reports nothing the day the convention moves.
+     */
+    presenterFor(entity: string): unknown | undefined;
+    /** Dispose the root container. */
+    dispose(): Promise<void>;
+    /**
+     * Stop taking calls, and resolve once the running ones are done.
+     *
+     * The step before releasing, when there is work on the app: `dispose()` closes a
+     * storage connection the running calls are standing on. Rejects on `timeoutMs`
+     * naming how many are left, rather than resolving as if it had succeeded.
+     */
+    drain(timeoutMs?: number): Promise<void>;
+    /** How many calls are running right now — one count for all three doors and the wire. */
+    inFlight(): number;
+    /**
+     * The same disposal, spelled so the language does it: `await using app = await
+     * createApp(…)`. Twelve of the twenty-six mounts in this repo's own tests never
+     * called `dispose()` — a scope that closes itself is the only version of that
+     * rule nobody forgets.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * What this app took on, in the order it will release them. The reading of
+     * `CreateAppOptions.extensions` after the boot resolved it.
+     */
+    extensions(): string[];
+    /**
+     * Declare one `rpc` op — what the app says about ITSELF, beside the card.
+     *
+     * The gesture a package uses to add a reading core does not hold: an app that never
+     * installed it never registers it, so the runner's refusal is the whole degradation.
+     * A name already declared is refused rather than replaced — `discover` included.
+     */
+    serveRpc(op: string, answer: RpcAnswer): void;
+    /** Register a global app middleware (runs on every operation). */
+    use(middleware: AppMiddleware): void;
+    /** Register an app middleware scoped to a specific entity. */
+    use(entity: string, middleware: AppMiddleware): void;
+    /** Auth runtime, present when fougere.config.ts declares `auth`. */
+    auth?: AuthRuntime;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/boot/types.js.map

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

package/dist/builtins/config.d.ts

@@ -1,4 +1,13 @@
+/**
+ * The process environment, as a service — so a handler asks for it rather than reading it.
+ *
+ * `process` is absent on a Worker, where the environment arrives as a binding. Read through
+ * `globalThis` and treated as empty when there is none: a missing variable and a missing
+ * `process` are the same answer to a caller, and the fallback already says what to do.
+ */
 export declare class Config {
+    private readonly env;
+    constructor(env?: Record<string, string | undefined>);
     get<T = string>(key: string, fallback?: T): T;
 }
 //# sourceMappingURL=config.d.ts.map

package/dist/builtins/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/builtins/config.ts"],"names":[],"mappings":"AAAA,qBAAa,MAAM;IACjB,GAAG,CAAC,CAAC,GAAG,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC,GAAG,CAAC;CAG9C"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/builtins/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,qBAAa,MAAM;IACL,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAkB;IAErF,GAAG,CAAC,CAAC,GAAG,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC,GAAG,CAAC;CAG9C"}

package/dist/builtins/config.js

@@ -1,6 +1,21 @@
+/**
+ * The process environment, as a service — so a handler asks for it rather than reading it.
+ *
+ * `process` is absent on a Worker, where the environment arrives as a binding. Read through
+ * `globalThis` and treated as empty when there is none: a missing variable and a missing
+ * `process` are the same answer to a caller, and the fallback already says what to do.
+ */
 export class Config {
+    env;
+    constructor(env = envOfProcess()) {
+        this.env = env;
+    }
     get(key, fallback) {
-        return process.env[key] ?? fallback;
+        return this.env[key] ?? fallback;
     }
 }
+function envOfProcess() {
+    const proc = globalThis.process;
+    return proc?.env ?? {};
+}
 //# sourceMappingURL=config.js.map

package/dist/builtins/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/builtins/config.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,MAAM;IACjB,GAAG,CAAa,GAAW,EAAE,QAAY;QACvC,OAAQ,OAAO,CAAC,GAAG,CAAC,GAAG,CAAO,IAAK,QAAc,CAAC;IACpD,CAAC;CACF"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/builtins/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,OAAO,MAAM;IACY;IAA7B,YAA6B,MAA0C,YAAY,EAAE;QAAxD,QAAG,GAAH,GAAG,CAAqD;IAAG,CAAC;IAEzF,GAAG,CAAa,GAAW,EAAE,QAAY;QACvC,OAAQ,IAAI,CAAC,GAAG,CAAC,GAAG,CAAO,IAAK,QAAc,CAAC;IACjD,CAAC;CACF;AAED,SAAS,YAAY;IACnB,MAAM,IAAI,GAAI,UAAyE,CAAC,OAAO,CAAC;IAChG,OAAO,IAAI,EAAE,GAAG,IAAI,EAAE,CAAC;AACzB,CAAC"}

package/dist/builtins/logger.d.ts

@@ -4,20 +4,53 @@
  * Works on Node, Bun, Deno, Cloudflare Workers (console-based, no native bindings).
  */
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+/**
+ * One line, before it was formatted for a terminal.
+ *
+ * The console form is already cooked — ANSI codes, a badge, a timestamp — so anything
+ * that wants to FORWARD a log needs it before that. What travels is the structure, and
+ * nothing here knows where it goes.
+ */
+export interface LogRecord {
+    level: Exclude<LogLevel, 'silent'>;
+    /** The logger's own name — 'boot:app', 'boot:app:catalog'. */
+    name: string;
+    message: string;
+    args: unknown[];
+    /** Epoch milliseconds. */
+    at: number;
+}
+export type LogSink = (record: LogRecord) => void;
+/** Take every line this process logs. Returns the way to withdraw. */
+export declare function onLog(next: LogSink): () => void;
+/**
+ * The level the PROCESS was started with. Read here rather than only at `applyConfig`,
+ * which runs after the boot has already said where its root is — an operator asking for
+ * `warn` got that line anyway. Guarded: this module runs on Workers, where there is no
+ * `process`.
+ */
+export declare function envLevel(): LogLevel | undefined;
+/**
+ * Set the level for every logger in this process, at once.
+ *
+ * Refuses a level it does not know rather than storing `undefined` as the threshold:
+ * every comparison against it is then `NaN`, so nothing is filtered and `logLevel()`
+ * reports its own fallback instead of what is in force.
+ */
+export declare function setLogLevel(level: LogLevel): void;
+/** What the level is now — the dual, so a reload can report what it changed. */
+export declare function logLevel(): LogLevel;
 export interface LoggerOptions {
-    /** Minimum log level. Default: 'info'. */
-    level?: LogLevel;
     /** Logger name / prefix. */
     name?: string;
     /** Force color on/off. Auto-detected by default. */
     color?: boolean;
 }
 export declare class Logger {
-    private level;
     private name;
     private color;
     constructor(prefix?: string, options?: Omit<LoggerOptions, 'name'>);
-    /** Create a child logger with a sub-name. */
+    /** Create a child logger with a sub-name. It carries no level of its own either. */
     child(name: string): Logger;
     debug(msg: string, ...args: unknown[]): void;
     info(msg: string, ...args: unknown[]): void;

package/dist/builtins/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/builtins/logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAyCtE,MAAM,WAAW,aAAa;IAC5B,0CAA0C;IAC1C,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,4BAA4B;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,qBAAa,MAAM;IACjB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,KAAK,CAAU;gBAEX,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,MAAM,CAAC;IAMlE,6CAA6C;IAC7C,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAK3B,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE;IACrC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE;IACpC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE;IACpC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE;IAErC,OAAO,CAAC,GAAG;CAeZ"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/builtins/logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEtE;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,OAAO,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACnC,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,0BAA0B;IAC1B,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,MAAM,OAAO,GAAG,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,CAAC;AAUlD,sEAAsE;AACtE,wBAAgB,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,IAAI,CAM/C;AAcD;;;;;GAKG;AACH,wBAAgB,QAAQ,IAAI,QAAQ,GAAG,SAAS,CAG/C;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAKjD;AAED,gFAAgF;AAChF,wBAAgB,QAAQ,IAAI,QAAQ,CAEnC;AAuCD,MAAM,WAAW,aAAa;IAC5B,4BAA4B;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,qBAAa,MAAM;IACjB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,KAAK,CAAU;gBAEX,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,MAAM,CAAC;IAKlE,oFAAoF;IACpF,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI3B,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE;IACrC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE;IACpC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE;IACpC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE;IAErC,OAAO,CAAC,GAAG;CAyBZ"}

package/dist/builtins/logger.js

@@ -3,7 +3,59 @@
  *
  * Works on Node, Bun, Deno, Cloudflare Workers (console-based, no native bindings).
  */
+/**
+ * Who else takes this process's log lines, beside the console. A list, like the span
+ * sinks: a line is one fact, and forwarding it twice is the caller's business.
+ *
+ * Nothing is built when nobody listens — the record is only shaped if a sink exists.
+ */
+const sinks = [];
+/** Take every line this process logs. Returns the way to withdraw. */
+export function onLog(next) {
+    sinks.push(next);
+    return () => {
+        const at = sinks.indexOf(next);
+        if (at >= 0)
+            sinks.splice(at, 1);
+    };
+}
 const LEVELS = { debug: 0, info: 1, warn: 2, error: 3, silent: 4 };
+/**
+ * The level, held ONCE for the process and CONSULTED at every emission.
+ *
+ * It used to be copied into each Logger by the constructor, and copied again by
+ * `child()` — so there was no place where "the level" was, and changing it meant
+ * rebuilding every logger AND everything that had been handed one. A value read at
+ * the moment it is used costs the same and can move.
+ */
+let threshold = LEVELS[envLevel() ?? 'info'];
+/**
+ * The level the PROCESS was started with. Read here rather than only at `applyConfig`,
+ * which runs after the boot has already said where its root is — an operator asking for
+ * `warn` got that line anyway. Guarded: this module runs on Workers, where there is no
+ * `process`.
+ */
+export function envLevel() {
+    const raw = typeof process === 'undefined' ? undefined : process.env.FOUGERE_LOG_LEVEL;
+    return raw !== undefined && raw in LEVELS ? raw : undefined;
+}
+/**
+ * Set the level for every logger in this process, at once.
+ *
+ * Refuses a level it does not know rather than storing `undefined` as the threshold:
+ * every comparison against it is then `NaN`, so nothing is filtered and `logLevel()`
+ * reports its own fallback instead of what is in force.
+ */
+export function setLogLevel(level) {
+    if (!(level in LEVELS)) {
+        throw new Error(`Unknown log level: '${level}'. One of ${Object.keys(LEVELS).join(', ')}.`);
+    }
+    threshold = LEVELS[level];
+}
+/** What the level is now — the dual, so a reload can report what it changed. */
+export function logLevel() {
+    return Object.keys(LEVELS).find((l) => LEVELS[l] === threshold) ?? 'info';
+}
 const COLORS = {
     reset: '\x1b[0m',
     dim: '\x1b[2m',
@@ -40,29 +92,36 @@ function formatTime() {
     return `${h}:${m}:${s}.${ms}`;
 }
 export class Logger {
-    level;
     name;
     color;
     constructor(prefix, options) {
         this.name = prefix ?? 'app';
-        this.level = LEVELS[options?.level ?? 'info'];
         this.color = options?.color ?? supportsColor();
     }
-    /** Create a child logger with a sub-name. */
+    /** Create a child logger with a sub-name. It carries no level of its own either. */
     child(name) {
-        const level = (Object.entries(LEVELS).find(([, v]) => v === this.level)?.[0] ?? 'info');
-        return new Logger(`${this.name}:${name}`, { level, color: this.color });
+        return new Logger(`${this.name}:${name}`, { color: this.color });
     }
     debug(msg, ...args) { this.log('debug', msg, args); }
     info(msg, ...args) { this.log('info', msg, args); }
     warn(msg, ...args) { this.log('warn', msg, args); }
     error(msg, ...args) { this.log('error', msg, args); }
     log(level, msg, args) {
-        if (LEVELS[level] < this.level)
+        if (LEVELS[level] < threshold)
             return;
+        // Beside the console, never instead of it: a forwarded line is an addition, and a
+        // sink that throws must not cost the operator the line they were reading.
+        for (const take of sinks) {
+            try {
+                take({ level: level, name: this.name, message: msg, args, at: Date.now() });
+            }
+            catch { /* forwarding never breaks logging */ }
+        }
         const style = LEVEL_STYLE[level];
         const time = formatTime();
-        const method = level === 'error' ? 'error' : level === 'warn' ? 'warn' : 'log';
+        // One console method per level. `debug` and `info` both went to `console.log`, so
+        // nothing downstream — a terminal filter, a collector — could tell them apart.
+        const method = level;
         if (this.color) {
             const c = COLORS[style.color];
             const prefix = `${COLORS.dim}${time}${COLORS.reset} ${c}${COLORS.bold}${style.badge}${COLORS.reset} ${COLORS.magenta}${this.name}${COLORS.reset}`;

package/dist/builtins/logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/builtins/logger.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/builtins/logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAuBH;;;;;GAKG;AACH,MAAM,KAAK,GAAc,EAAE,CAAC;AAE5B,sEAAsE;AACtE,MAAM,UAAU,KAAK,CAAC,IAAa;IACjC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjB,OAAO,GAAG,EAAE;QACV,MAAM,EAAE,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,EAAE,IAAI,CAAC;YAAE,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IACnC,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,MAAM,GAA6B,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;AAE7F;;;;;;;GAOG;AACH,IAAI,SAAS,GAAW,MAAM,CAAC,QAAQ,EAAE,IAAI,MAAM,CAAC,CAAC;AAErD;;;;;GAKG;AACH,MAAM,UAAU,QAAQ;IACtB,MAAM,GAAG,GAAG,OAAO,OAAO,KAAK,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;IACvF,OAAO,GAAG,KAAK,SAAS,IAAI,GAAG,IAAI,MAAM,CAAC,CAAC,CAAE,GAAgB,CAAC,CAAC,CAAC,SAAS,CAAC;AAC5E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,KAAe;IACzC,IAAI,CAAC,CAAC,KAAK,IAAI,MAAM,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,uBAAuB,KAAK,aAAa,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC9F,CAAC;IACD,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;AAC5B,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,QAAQ;IACtB,OAAQ,MAAM,CAAC,IAAI,CAAC,MAAM,CAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,IAAI,MAAM,CAAC;AAC5F,CAAC;AAED,MAAM,MAAM,GAA2B;IACrC,KAAK,EAAE,SAAS;IAChB,GAAG,EAAE,SAAS;IACd,IAAI,EAAE,SAAS;IACf,KAAK,EAAE,UAAU;IACjB,MAAM,EAAE,UAAU;IAClB,GAAG,EAAE,UAAU;IACf,IAAI,EAAE,UAAU;IAChB,OAAO,EAAE,UAAU;IACnB,IAAI,EAAE,UAAU;CACjB,CAAC;AAEF,MAAM,WAAW,GAAqD;IACpE,KAAK,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE;IACtC,IAAI,EAAG,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE;IACvC,IAAI,EAAG,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE;IACxC,KAAK,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE;CACtC,CAAC;AAEF,SAAS,aAAa;IACpB,IAAI,OAAO,OAAO,KAAK,WAAW,EAAE,CAAC;QACnC,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ;YAAE,OAAO,KAAK,CAAC;QACvC,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,KAAK,GAAG;YAAE,OAAO,IAAI,CAAC;QACjD,OAAO,OAAO,CAAC,MAAM,EAAE,KAAK,KAAK,IAAI,CAAC;IACxC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,UAAU;IACjB,MAAM,CAAC,GAAG,IAAI,IAAI,EAAE,CAAC;IACrB,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAChD,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAClD,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAClD,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,eAAe,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACxD,OAAO,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;AAChC,CAAC;AASD,MAAM,OAAO,MAAM;IACT,IAAI,CAAS;IACb,KAAK,CAAU;IAEvB,YAAY,MAAe,EAAE,OAAqC;QAChE,IAAI,CAAC,IAAI,GAAG,MAAM,IAAI,KAAK,CAAC;QAC5B,IAAI,CAAC,KAAK,GAAG,OAAO,EAAE,KAAK,IAAI,aAAa,EAAE,CAAC;IACjD,CAAC;IAED,oFAAoF;IACpF,KAAK,CAAC,IAAY;QAChB,OAAO,IAAI,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IACnE,CAAC;IAED,KAAK,CAAC,GAAW,EAAE,GAAG,IAAe,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IACxE,IAAI,CAAC,GAAW,EAAE,GAAG,IAAe,IAAK,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IACvE,IAAI,CAAC,GAAW,EAAE,GAAG,IAAe,IAAK,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IACvE,KAAK,CAAC,GAAW,EAAE,GAAG,IAAe,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IAEhE,GAAG,CAAC,KAAa,EAAE,GAAW,EAAE,IAAe;QACrD,IAAI,MAAM,CAAC,KAAiB,CAAC,GAAG,SAAS;YAAE,OAAO;QAElD,kFAAkF;QAClF,0EAA0E;QAC1E,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC;gBACH,IAAI,CAAC,EAAE,KAAK,EAAE,KAA2B,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YACpG,CAAC;YAAC,MAAM,CAAC,CAAC,qCAAqC,CAAC,CAAC;QACnD,CAAC;QAED,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;QACjC,MAAM,IAAI,GAAG,UAAU,EAAE,CAAC;QAC1B,kFAAkF;QAClF,+EAA+E;QAC/E,MAAM,MAAM,GAAG,KAA4C,CAAC;QAE5D,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC9B,MAAM,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,GAAG,IAAI,GAAG,MAAM,CAAC,KAAK,IAAI,CAAC,GAAG,MAAM,CAAC,IAAI,GAAG,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC;YAClJ,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;QACxC,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI,CAAC,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;QACzE,CAAC;IACH,CAAC;CACF"}

package/dist/config-loader.d.ts

@@ -1,4 +1,6 @@
-import type { AuthConfig } from './types.js';
+import type { AuthConfig } from './boot/auth.js';
+import type { LogLevel } from './builtins/logger.js';
+import type { ConventionsInput } from './scan/conventions.js';
 export interface FougereConfig {
     /** Database configuration — the DEFAULT source, the one an entity lands in unnamed. */
     db?: 'sqlite' | {
@@ -25,10 +27,38 @@ export interface FougereConfig {
         path?: string;
         entities: string[];
     }>;
-    /** Directory containing fronds. Defaults to 'fronds'. */
-    frondsDir?: string;
+    /**
+     * The names the scan reads instead of deriving them — the import scope, the fronds
+     * directory, the seven convention directories.
+     *
+     * Only what differs is stated. Read BEFORE the fronds are discovered, which is what
+     * lets it name the prefix they are found under: nothing in this file may import
+     * `@fronds/*`, or the name would be needed to read the file that declares it.
+     */
+    conventions?: ConventionsInput;
+    /**
+     * How much every logger says. The one key a running app CONSULTS rather than
+     * consumes, so re-reading this file changes it without rebuilding anything.
+     *
+     * `FOUGERE_LOG_LEVEL` still wins — it is how the CLI speaks, and the precedence is
+     * the usual one (CLI over config file).
+     */
+    logLevel?: LogLevel;
     /** Remote fronds — frondName → base URL. */
     remotes?: Record<string, string>;
+    /**
+     * Which realization answers which port — port class name → implementation class name.
+     *
+     * A fact about the APP, stated beside `remotes:` for the same reason `sources:` is:
+     * `remotes:` says where a CALL goes, `sources:` says where a ROW is, this says who
+     * performs an ACTION. None of the three belongs inside the frond, which describes
+     * itself and not its deployment — a `billing` frond naming Stripe would be the one
+     * thing the framework refuses.
+     *
+     * Only the exception is declared. One class extending a port answers it by
+     * convention and this key stays absent; two make the boot refuse until one is named.
+     */
+    ports?: Record<string, string>;
     /** Auth declaration — picks a provider package and forwards options to it. */
     auth?: AuthConfig;
     /**
@@ -54,38 +84,16 @@ export interface AdapterConfig {
     /** A surface of your own; the framework only records that you declared it. */
     [adapter: string]: boolean | undefined;
 }
-export interface ResolvedConfig {
-    /** Global config merged with all overrides. */
-    global: FougereConfig;
-    /** Per-frond config overrides. */
-    fronds: Record<string, FougereConfig>;
-}
 /**
  * Load the root fougere.config.{ts,js,mjs} from the given directory.
- */
-export declare function loadConfig(root: string): Promise<FougereConfig>;
-/**
- * Load per-frond config files from each frond's directory.
- */
-export declare function loadFrondConfigs(root: string, frondsDir?: string): Promise<Record<string, FougereConfig>>;
-/**
- * Override a config with another, the invariant of every cascade level:
- * scalar keys replace, but `remotes` (the topology) MERGES — an override adds
- * or redirects a frond without erasing the others. Used for workspace→app and
- * for global→CLI alike.
- */
-export declare function mergeGlobal(base: FougereConfig, override: Partial<FougereConfig>): FougereConfig;
-/**
- * Merge configs with cascade: global → frond → CLI overrides.
  *
- * Returns a ResolvedConfig with the merged global and per-frond overrides.
- */
-export declare function mergeConfig(global: FougereConfig, frondConfigs: Record<string, FougereConfig>, cliOverrides?: Partial<FougereConfig>): ResolvedConfig;
-/**
- * Get the effective config for a specific frond.
- * Cascade: global → frond override.
+ * `fresh` re-reads a file that may have changed since the last load — what a host
+ * calls when it decides to reconsider its config, and the only way `applyConfig` has
+ * anything new to apply.
  */
-export declare function configForFrond(resolved: ResolvedConfig, frondName: string): FougereConfig;
+export declare function loadConfig(root: string, options?: {
+    fresh?: boolean;
+}): Promise<FougereConfig>;
 /**
  * Load config along the workspace→app frontier. The workspace-root config is
  * the base (canonical topology: `remotes`, shared `db`); the app-root config
@@ -94,8 +102,4 @@ export declare function configForFrond(resolved: ResolvedConfig, frondName: stri
  * root config — idempotent, no behavior change.
  */
 export declare function loadCascadedConfig(workspaceRoot: string, appRoot: string): Promise<FougereConfig>;
-/**
- * Load everything: root config + frond configs + merge with CLI overrides.
- */
-export declare function resolveConfig(root: string, cliOverrides?: Partial<FougereConfig>): Promise<ResolvedConfig>;
 //# sourceMappingURL=config-loader.d.ts.map

package/dist/config-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config-loader.d.ts","sourceRoot":"","sources":["../src/config-loader.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAK7C,MAAM,WAAW,aAAa;IAC5B,uFAAuF;IACvF,EAAE,CAAC,EAAE,QAAQ,GAAG;QAAE,OAAO,EAAE,QAAQ,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,KAAK,CAAC;IAC7D;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,OAAO,CAAC,EAAE,QAAQ,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IACpF,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,8EAA8E;IAC9E,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B;AAED,wEAAwE;AACxE,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,8EAA8E;IAC9E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,8EAA8E;IAC9E,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;CACxC;AAED,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,MAAM,EAAE,aAAa,CAAC;IACtB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CACvC;AAkBD;;GAEG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAErE;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,SAAW,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAgBjH;AAID;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,aAAa,CAMhG;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,aAAa,EACrB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,EAC3C,YAAY,GAAE,OAAO,CAAC,aAAa,CAAM,GACxC,cAAc,CAEhB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,GAAG,aAAa,CAIzF;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAIvG;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,YAAY,GAAE,OAAO,CAAC,aAAa,CAAM,GACxC,OAAO,CAAC,cAAc,CAAC,CAKzB"}
+{"version":3,"file":"config-loader.d.ts","sourceRoot":"","sources":["../src/config-loader.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAK9D,MAAM,WAAW,aAAa;IAC5B,uFAAuF;IACvF,EAAE,CAAC,EAAE,QAAQ,GAAG;QAAE,OAAO,EAAE,QAAQ,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,KAAK,CAAC;IAC7D;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,OAAO,CAAC,EAAE,QAAQ,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IACpF;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,8EAA8E;IAC9E,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B;AAED,wEAAwE;AACxE,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,8EAA8E;IAC9E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,8EAA8E;IAC9E,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;CACxC;AAsBD;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAEpG;AAkBD;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAIvG"}