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

package/src/boot/Emissions.ts

@@ -0,0 +1,263 @@
+import { applyCreate, type SchemaView } from '@fougere/schema';
+import type { Container } from '@fougere/container';
+import { validationErrorsOf } from '../wire/errors.js';
+import { emitKeyOf, factsAnnouncedBy } from '../emit.js';
+import { ambient } from '#ambient';
+import { EMPTY_INVOCATION } from '../wire/invocation.js';
+import type { Logger } from '../builtins/logger.js';
+import type { Fronds } from '../scan/Fronds.js';
+import type { OperationsMap } from '../wire/operation.js';
+
+/** A door and the op on it that accepts a fact. */
+interface Listener {
+  door: string;
+  op: string;
+}
+
+/** Carries an announced fact out of this process — see `CreateAppOptions.onEmit`. */
+type Carrier = (fact: string, payload: unknown) => void | Promise<void>;
+
+/**
+ * Emissions — the only place in Fougere where an initiator names a SUBJECT.
+ *
+ * It was eight closures over four collections in the middle of the boot, which is a
+ * class that had not been named: the announced set, the subscriber index, the chain
+ * carried in async context, and the shapes a fact is judged against.
+ *
+ * **It is a resolver, not a channel.** It answers *who*, then hands over to the door
+ * that already exists — so a subscriber keeps its judge, its binding and its
+ * middlewares, and nothing here is durable.
+ */
+export class Emissions {
+  /** Who listens to what. Filled as each door's contracts are resolved. */
+  private readonly subscribers = new Map<string, Listener[]>();
+
+  /**
+   * What is announced here, read from the DEPS and not from the subscribers: a handler
+   * declaring `Emit<PostPublished>` must resolve it whether or not anybody listens, and
+   * announcing to nobody is legal.
+   */
+  private readonly announced: Set<string>;
+
+  constructor(
+    fronds: Fronds,
+    private readonly shapes: Map<string, SchemaView>,
+    private readonly container: Container,
+    private readonly log: Logger,
+    private readonly carry?: Carrier,
+  ) {
+    this.announced = new Set(fronds.flatMap((frond) => factsAnnouncedBy(frond.handlers)));
+  }
+
+  /**
+   * Who listens to what — read from the PLAN, where `{ kind: 'fact' }` is a sentence
+   * `computeBindingPlan` already wrote, so nothing re-derives what a parameter is.
+   *
+   * It is called for a frond hosted here AND for one declared remote. A remote frond is
+   * still scanned — only its hosting is elsewhere — so its subscriptions are known, and
+   * its door resolves to a doublure. That is the whole reason an emission crosses a
+   * process without a line of transport code: the emitter learned the signature locally
+   * and calls the same key. Noting only the hosted ones left the index EMPTY under a
+   * split, and a fact announced to a remote listener reached nobody, in silence.
+   */
+  note(contracts: OperationsMap, door: string): void {
+    for (const [op, contract] of contracts) {
+      for (const bound of contract.binding ?? []) {
+        if (bound.source.kind !== 'fact') continue;
+        const listeners = this.subscribers.get(bound.source.factName) ?? [];
+        listeners.push({ door, op });
+        this.subscribers.set(bound.source.factName, listeners);
+      }
+    }
+  }
+
+  /** The shape a fact is judged by, when the fact is a declared entity. */
+  shapeOf(fact: string): SchemaView | undefined {
+    return this.shapes.get(fact);
+  }
+
+  /** The facts this process has a listener for — what a carrier subscribes to on its behalf. */
+  listensTo(): string[] {
+    return [...this.subscribers.keys()];
+  }
+
+  /**
+   * Register one emission value per fact — announced here, or merely listened to.
+   *
+   * A process that only subscribes still needs the value, because `deliver` is what a
+   * carrier calls and it goes through the same door. Called once every door has been
+   * built, so the two sets are complete.
+   */
+  register(): void {
+    for (const fact of new Set([...this.announced, ...this.subscribers.keys()])) {
+      this.container.registerValue(emitKeyOf(fact), (raw: unknown) => this.announce(fact, raw));
+    }
+    if (ambient.degraded && this.subscribers.size > 0) {
+      this.log.warn('no async context on this runtime — an emission ring is not detected');
+    }
+  }
+
+  /**
+   * Announcing. Dispatch, never delivery — the emitter is handed back the moment every
+   * subscriber has been HANDED the fact, not when any of them is done.
+   *
+   * The `EventBus` this replaces did `await Promise.all(handlers)` and passed their
+   * rejections up, which made a publication hostage to its own indexer.
+   */
+  private async announce(fact: string, raw: unknown): Promise<void> {
+    /**
+     * A fact announced inside a frame that then rolls back is a lie, and nothing can take
+     * it back: announcing is DISPATCH — every subscriber has been handed the fact and the
+     * carrier has already put it on the wire — while the frame's writes are still
+     * provisional.
+     *
+     * Refused rather than deferred to the commit. Deferring would make `Emit<T>` behave
+     * differently depending on where it is called from, which is the hidden runtime the
+     * doctrine refuses; and it opens a window between the commit and the announcement whose
+     * only remedy is an outbox — a table, therefore durability, the one thing Fougere says
+     * it does not hold.
+     *
+     * A fact designates something that HAS happened. `run` returning is when that becomes
+     * true, so that is where the announcement belongs.
+     */
+    await ambient.beforeAnnounce(fact);
+
+    const payload = this.stamped(fact, raw);
+
+    /**
+     * Whoever is not in this process — and it is the ONLY way to reach them.
+     *
+     * The local dispatch finds its listeners by having READ their code, so it stops at
+     * the repository boundary: another team's Frond is not on this disk, and the
+     * emission reaches nobody. A carrier hands the fact to a name instead, and the far
+     * side subscribes to that same name from ITS own code. Neither reads the other.
+     *
+     * `deliver` deliberately does NOT come here: a hub that resolved this value to hand
+     * on an incoming reading echoed it straight back to the whole fleet.
+     */
+    const carried = this.carry?.(fact, payload);
+    if (carried) void Promise.resolve(carried).catch((cause) => this.log.error(`${fact} — carrier refused it`, cause));
+
+    for (const { door, op, done } of this.handToListeners(fact, payload)) {
+      void done.catch((cause) => this.log.error(`${fact} → ${door}.${op}`, this.describeRefusal(fact, cause) ?? cause));
+    }
+  }
+
+  /**
+   * Receiving. **The opposite rule, deliberately**: this one waits, and it tells.
+   *
+   * `deliver` is what a CARRIER calls, and 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 on top. It used to be the announcement itself:
+   * it resolved before any subscriber had run and swallowed every failure into a log, so a
+   * queue calling it could only ever ack blindly.
+   *
+   * That is not a contradiction of "dispatch is not delivery". That rule protects the
+   * EMITTER, which must not become hostage to a subscriber; a carrier is not the emitter,
+   * it is precisely the party whose business this is.
+   *
+   * What it still does not do is HOLD anything. A fact refused here is refused, and the
+   * carrier decides whether it comes back — which is the whole of Fougere's position on
+   * durability: the channel goes underneath, it is not reimplemented here.
+   */
+  async deliver(fact: string, payload: unknown): Promise<void> {
+    const handed = this.handToListeners(fact, payload);
+    const settled = await Promise.allSettled(handed.map((h) => h.done));
+
+    const refused = settled.flatMap((result, i) =>
+      result.status === 'rejected' ? [{ ...handed[i], reason: result.reason as unknown }] : []);
+    for (const { door, op, reason } of refused) {
+      this.log.error(`${fact} → ${door}.${op}`, this.describeRefusal(fact, reason) ?? reason);
+    }
+    if (refused.length > 0) {
+      throw new AggregateError(
+        refused.map((r) => r.reason),
+        `${fact} — ${refused.length} of ${handed.length} listener(s) refused it`
+        + ` (${refused.map((r) => `${r.door}.${r.op}`).join(', ')}).`
+        + ` Nothing here holds it: the carrier decides whether it comes back.`,
+      );
+    }
+  }
+
+  /**
+   * The announcement realizes the fact's own `lifecycle.create` — a `created()` stamped,
+   * an id generated, a default applied.
+   *
+   * `applyCreate` (`schema/src/axis/lifecycle/apply.ts`) is where the split is realized:
+   * the judge never fills a hole, the STORAGE does, at the point of persistence. A fact has no storage, so nobody did — the judge declared an
+   * absent `created()` legal and omitted it, and a subscriber received a value missing a
+   * field its own type promises. Announcing is a fact's point of persistence.
+   *
+   * Announcing only, never `deliver`: a fact that arrives from elsewhere was stamped by
+   * its sender, and stamping it again would give one fact a different identity in every
+   * process that relayed it.
+   *
+   * **A typed emitter cannot reach this yet.** `Emit<T>` names the ROW type, where a
+   * `created()` field is present and required, so `announce({ id, title })` is a compile
+   * error and the author writes `at: new Date()` anyway. So this runs for a payload built
+   * outside the type — a bridge, a replay, a test — and is inert for everyone else.
+   */
+  private stamped(fact: string, raw: unknown): unknown {
+    const shape = this.shapes.get(fact);
+    return shape && raw !== null && typeof raw === 'object' && !Array.isArray(raw)
+      ? applyCreate(shape.getFields(), raw as Record<string, unknown>)
+      : raw;
+  }
+
+  /**
+   * Hand the fact to every listener in THIS process, and give back one promise each.
+   *
+   * The call goes THROUGH the door, so a subscriber meets the same judge, the same binding
+   * and the same middlewares as any caller. Nothing new answers for correctness — that is
+   * the dividend of a subscriber being an ordinary op rather than a special kind.
+   *
+   * It returns the promises rather than settling them, because the two callers want
+   * opposite things and only one of them is wrong to wait.
+   */
+  private handToListeners(fact: string, payload: unknown): (Listener & { done: Promise<unknown> })[] {
+    const walked = ambient.currentChain();
+    if (walked.includes(fact)) {
+      throw new Error(
+        `Emission cycle: ${[...walked, fact].join(' → ')}.\n`
+        + `  A fact cannot cause itself. One of the subscribers above announces a fact that leads back here.`,
+      );
+    }
+
+    const listeners = this.subscribers.get(fact) ?? [];
+    if (listeners.length === 0) {
+      this.log.debug(`${fact} — nobody listens in this process`);
+      return [];
+    }
+
+    return listeners.map(({ door, op }) => ({
+      door,
+      op,
+      done: ambient.enterChain(fact, async () => {
+        let facade: Record<string, Function>;
+        try {
+          facade = this.container.resolve<Record<string, Function>>(door);
+        } catch (cause) {
+          throw new Error(`${fact} → ${door} could not be reached`, { cause });
+        }
+        return facade[op]({ ...EMPTY_INVOCATION, body: payload });
+      }),
+    }));
+  }
+
+  /**
+   * A subscriber refusing the SHAPE, said in one line instead of dumped as an error.
+   *
+   * This is the one refusal nobody else will ever see. A door hands its 400 back to the
+   * caller who can fix it; a fact is dispatched, not delivered, so the sender learns
+   * nothing and the log is the whole of the evidence. The most likely cause is also the
+   * one a stack trace hides worst — this process's copy is older than the sender's — so
+   * the line names the fields and the remedy, and hedges because a genuinely bad payload
+   * produces the same refusal.
+   */
+  private describeRefusal(fact: string, cause: unknown): string | undefined {
+    const refusals = validationErrorsOf(cause);
+    if (!refusals?.length) return undefined;
+    return `refused the shape — ${refusals.map((d) => `${d.path}: ${d.message}`).join(', ')}.`
+      + ` If '${fact}' gained a field, this copy is older than the sender's: re-run \`fougere sync\`.`;
+  }
+}

package/src/boot/HandlerFacade.ts

@@ -0,0 +1,242 @@
+import { lowerFirst, type Fields } from '@fougere/schema';
+import type { Container } from '@fougere/container';
+import type { AppMiddleware } from '../wire/middleware.js';
+import type { CollectorResolver } from './binding.js';
+import { collectorKeyOf } from '../prefab/collector.js';
+import { presenterKeyOf } from '../prefab/presenter.js';
+import { repositoryKeyOf } from '../prefab/repository.js';
+import { targetOf } from '../prefab/prefab.js';
+import type { OperationContract, OperationsMap } from '../wire/operation.js';
+import type { EffectiveOperation, EffectiveOperationsMap } from '../effective-operation.js';
+import type { InvocationContext } from '../wire/invocation.js';
+import type { Emissions } from './Emissions.js';
+import type { Logger } from '../builtins/logger.js';
+import type { EntityEntry, HandlerEntry, PresenterEntry } from '../scan/frond.js';
+import { InputValidator } from '../dispatch/InputValidator.js';
+import { ArgumentResolver } from '../dispatch/ArgumentResolver.js';
+import { OperationExecutor } from '../dispatch/OperationExecutor.js';
+import { OutputProjector } from '../dispatch/OutputProjector.js';
+import { OutputView } from '../dispatch/OutputView.js';
+import { PresenterExecutor } from '../dispatch/PresenterExecutor.js';
+import { PresenterArgumentResolver } from '../dispatch/PresenterArgumentResolver.js';
+
+/** What this door is about: a handler, the entity behind it when there is one, and where it resolves. */
+export interface Doorway {
+  handler: HandlerEntry;
+  /** Handlers in the owning frond, used to realize a resolved implementation override. */
+  handlers: readonly HandlerEntry[];
+  /** The canonical operation table resolved before boot performs any side effect. */
+  operations: EffectiveOperationsMap;
+  /** The subject — absent is ordinary: a health check owns no row. */
+  entity: EntityEntry | undefined;
+  /** The scope the handler and its collectors resolve in — a surface gets its own. */
+  scope: Container;
+  /** The container key this door answers under. */
+  key: string;
+}
+
+/** What the frond and the boot supply to every door alike. */
+export interface Wiring {
+  /** The frond this door belongs to — travels on every OperationContext. */
+  frond: string;
+  /** The frond's own scope — where presenters live, whatever sub-scope the door uses. */
+  frondScope: Container;
+  log: Logger;
+  /** Entity names this frond has a collector for. */
+  collectors: Set<string>;
+  presenters: Map<string, PresenterEntry>;
+  /** The middlewares that apply to an address, read at call time and never at boot. */
+  middlewaresFor: (address: string) => AppMiddleware[];
+  emissions: Emissions;
+}
+
+/** Adapts one handler door to executable operations. */
+export class HandlerFacade {
+  /** Rich operation facts shared with check, explain and adapters. */
+  readonly effectiveOperations: EffectiveOperationsMap;
+  /** Contracts served by this door. */
+  readonly contracts: OperationsMap;
+
+  /** The callable surface: op name → the function a caller reaches. */
+  readonly ops: Record<string, Function> = {};
+
+  private readonly cachedViews = new Map<string, OutputView>();
+  private instance: any;
+  private readonly implementationKeys = new Map<string, string>();
+  private readonly implementationInstances = new Map<string, any>();
+  private readonly inputValidator = new InputValidator();
+  private readonly argumentResolver = new ArgumentResolver(
+    (typeName) => this.collectorResolver(typeName),
+  );
+  private readonly presenterArguments: PresenterArgumentResolver;
+
+  constructor(private readonly door: Doorway, private readonly wiring: Wiring) {
+    const { handler, entity } = door;
+    this.presenterArguments = new PresenterArgumentResolver(
+      this.argumentResolver,
+      wiring.collectors,
+    );
+    this.refuseCrudWithoutRepository(handler);
+
+    door.scope.register(this.handlerKey, handler.ctor, { deps: this.depsOf(handler) });
+
+    this.effectiveOperations = door.operations;
+    this.contracts = new Map(
+      [...door.operations].map(([name, operation]) => [name, operation as OperationContract] as const),
+    );
+    handler.operations = this.contracts;
+
+    // Register model-selected implementations in the same execution scope.
+    for (const [name, operation] of door.operations) {
+      if (this.isBaseImplementation(operation)) continue;
+      const implementation = this.implementationHandler(name);
+      this.refuseCrudWithoutRepository(implementation);
+      const key = `${this.handlerKey}:implementation:${operation.implementation.className}`;
+      if (!this.implementationKeys.has(operation.implementation.className)) {
+        door.scope.register(key, implementation.ctor, { deps: this.depsOf(implementation) });
+        this.implementationKeys.set(operation.implementation.className, key);
+      }
+    }
+
+    // Emissions use the same contracts and execution path as direct calls.
+    wiring.emissions.note(this.contracts, door.key);
+    // Only declared operations become callable façade members.
+    for (const op of this.contracts.keys()) this.ops[op] = this.wrap(op);
+
+    if (this.inheritsCrud(handler) && !entity) {
+      // An installed Crud subject may be absent from the local scan.
+      wiring.log.debug(`${handler.ctor.name} extends Crud() and no scanned entity is named `
+        + `'${this.subjectOf(handler)}' — installed entity, or a missing one: no ORM will be injected`);
+    }
+  }
+
+  /** Storage follows the Crud subject, which may differ from the door address. */
+  private subjectOf(handler: HandlerEntry): string {
+    const target = targetOf(handler.ctor);
+    return target?.name ? lowerFirst(target.name) : handler.address;
+  }
+
+  private inheritsCrud(handler: HandlerEntry): boolean {
+    const proto = handler.ctor.prototype;
+    return typeof proto?.list === 'function' && typeof proto?.findById === 'function';
+  }
+
+  private get handlerKey(): string {
+    return `_handler:${this.door.key}`;
+  }
+
+  private depsOf(handler: HandlerEntry): string[] {
+    const { deps } = handler;
+    if (deps.length > 0) return deps;
+    return this.inheritsCrud(handler) ? [repositoryKeyOf(this.subjectOf(handler))] : [];
+  }
+
+  /** A custom Crud constructor must explicitly receive its repository. */
+  private refuseCrudWithoutRepository(handler: HandlerEntry): void {
+    const repoTypeName = repositoryKeyOf(this.subjectOf(handler));
+    if (!this.inheritsCrud(handler) || handler.deps.length === 0 || handler.deps.includes(repoTypeName)) return;
+    throw new Error(
+      `${handler.ctor.name} extends Crud() and declares a constructor, so its storage is no ` +
+      `longer injected for it — but it does not take any.\n` +
+      `  Add it and hand it to super():\n` +
+      `    constructor(repo: ${repoTypeName}, …) { super(repo); }`,
+    );
+  }
+
+  /** Resolve and cache the output view declared for one operation. */
+  private viewOf(op: string): OutputView {
+    const known = this.cachedViews.get(op);
+    if (known) return known;
+
+    const operation = this.effectiveOperations.get(op);
+    const schema = operation?.output as { getFields?: () => Fields } | undefined;
+    const resolved = new OutputView(
+      typeof schema?.getFields === 'function' ? schema.getFields() : {},
+      operation?.outputClosed ?? false,
+    );
+    this.cachedViews.set(op, resolved);
+    return resolved;
+  }
+
+  private collectorResolver = (typeName: string): CollectorResolver | undefined => {
+    try { return this.door.scope.resolve(collectorKeyOf(typeName)) as CollectorResolver; }
+    catch { return undefined; }
+  };
+
+  /** The handler itself, resolved on first call — never at boot. */
+  private resolvedHandler(): any {
+    if (!this.instance) this.instance = this.door.scope.resolve(this.handlerKey);
+    return this.instance;
+  }
+
+  private isBaseImplementation(operation: EffectiveOperation): boolean {
+    return operation.implementation.className === this.door.handler.ctor.name
+      && operation.implementation.address === this.door.handler.address
+      && operation.implementation.filePath === this.door.handler.filePath;
+  }
+
+  /** The exact handler entry the pure model selected; no name-only retry or fallback. */
+  private implementationHandler(operationName: string): HandlerEntry {
+    const operation = this.effectiveOperations.get(operationName)!;
+    const matches = this.door.handlers.filter((handler) =>
+      handler.ctor.name === operation.implementation.className
+      && handler.address === operation.implementation.address
+      && handler.filePath === operation.implementation.filePath);
+    if (matches.length !== 1) {
+      throw new Error(
+        `EffectiveOperation '${operation.id}' names ${operation.implementation.className}.`
+        + `${operation.implementation.method}, but boot found ${matches.length} matching handlers.`,
+      );
+    }
+    return matches[0]!;
+  }
+
+  private resolvedImplementation(operationName: string): { instance: any; method: string } {
+    const operation = this.effectiveOperations.get(operationName)!;
+    if (this.isBaseImplementation(operation)) {
+      return { instance: this.resolvedHandler(), method: operation.implementation.method };
+    }
+
+    const className = operation.implementation.className;
+    const key = this.implementationKeys.get(className);
+    if (!key) throw new Error(`No registered implementation for EffectiveOperation '${operation.id}'.`);
+    let instance = this.implementationInstances.get(key);
+    if (!instance) {
+      instance = this.door.scope.resolve(key);
+      this.implementationInstances.set(key, instance);
+    }
+    return { instance, method: operation.implementation.method };
+  }
+
+  private wrap(op: string): (invocation?: InvocationContext) => Promise<unknown> {
+    const address = this.door.handler.address;
+    const contract = this.contracts.get(op);
+    const view = this.viewOf(op);
+    const presenter = this.wiring.presenters.get(address);
+    const executor = new OperationExecutor({
+      entity: address,
+      frond: this.wiring.frond,
+      operation: op,
+      contract,
+      middlewares: () => this.wiring.middlewaresFor(address),
+      validator: this.inputValidator,
+      arguments: this.argumentResolver,
+      invoke: async (args) => {
+        const implementation = this.resolvedImplementation(op);
+        return implementation.instance[implementation.method](...args);
+      },
+      projector: new OutputProjector(view),
+      ...(view.closed || !presenter ? {} : {
+        present: async (result: unknown, effective: InvocationContext) =>
+          new PresenterExecutor(
+            this.wiring.frondScope.resolve(presenterKeyOf(address)),
+            presenter.fields,
+            address,
+            op,
+          ).present(result, await this.presenterArguments.resolve(presenter, effective)),
+      }),
+    });
+
+    return (invocation) => executor.execute(invocation);
+  }
+}

package/src/boot/Lifecycle.ts

@@ -0,0 +1,3 @@
+/** Compatibility module. Prefer AppLifecycle for the process-level lifecycle. */
+export { AppLifecycle, AppLifecycle as Lifecycle, migrating } from './AppLifecycle.js';
+export type { Extension } from './AppLifecycle.js';

package/src/boot/ambient-port.ts

@@ -0,0 +1,41 @@
+/**
+ * What a call needs to know about the call it is inside, and the two ways to answer it.
+ *
+ * One realization reads an async context (`ambient.als.ts`), the other cannot and waits
+ * its turn instead (`ambient.queue.ts`). `#ambient` in package.json picks one per runtime,
+ * so a bundle for a host without async context never names `node:async_hooks`.
+ */
+export interface Ambient {
+  /** True when this runtime has no async context, and the boot says so. */
+  readonly degraded: boolean;
+
+  /**
+   * Run `fn` as the frame `key`. A frame opened inside another must not proceed.
+   *
+   * Measured on SQLite: a second transaction on the same connection WAITS for the first,
+   * so a nested frame hangs on one engine and returns when split across two.
+   */
+  enterFrame<R>(key: string, fn: () => Promise<R>): Promise<R>;
+
+  /**
+   * Settle before `fact` is dispatched: a fact announced inside a frame that then rolls
+   * back is a lie. Refuses when the caller's own frame can be told, waits when it cannot.
+   */
+  beforeAnnounce(fact: string): Promise<void>;
+
+  /**
+   * The facts already being announced up the stack, so a fact cannot cause itself.
+   *
+   * A CHAIN and not a depth: `A → B → D` and `A → C → D` is a diamond, perfectly legal,
+   * while `A → … → A` never ends. Empty where it cannot be followed.
+   *
+   * Detecting this at boot was the first idea and it was wrong: `Emit<G>` is a CONSTRUCTOR
+   * dependency, so it belongs to the handler and not to one of its methods. A handler that
+   * subscribes to `A` in one method and emits `G` from another would have been refused for
+   * a cycle it never walks.
+   */
+  currentChain(): readonly string[];
+
+  /** Run `fn` with `fact` appended to the emission chain. */
+  enterChain<R>(fact: string, fn: () => Promise<R>): Promise<R>;
+}

package/src/boot/ambient.als.ts

@@ -0,0 +1,43 @@
+/**
+ * The realization that can tell whose frame is open: an async context.
+ *
+ * Chosen by `#ambient` wherever `node:async_hooks` exists — Node, Deno, Bun, and workerd
+ * with `nodejs_als`. Every refusal here is immediate and names its cause.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { Ambient } from './ambient-port.js';
+
+const frame = new AsyncLocalStorage<string>();
+const chain = new AsyncLocalStorage<readonly string[]>();
+
+export const ambient: Ambient = {
+  degraded: false,
+
+  enterFrame<R>(key: string, fn: () => Promise<R>): Promise<R> {
+    const held = frame.getStore();
+    if (held !== undefined) {
+      return Promise.reject(new Error(
+        `Together<[…]> (${key}) cannot be opened inside ${held}: on one engine the second `
+        + `transaction waits for the first and the call hangs. Two frames that must both hold `
+        + `are ONE frame — declare a single Together naming every member.`,
+      ));
+    }
+    return frame.run(key, fn);
+  },
+
+  beforeAnnounce(fact: string): Promise<void> {
+    const held = frame.getStore();
+    if (held === undefined) return Promise.resolve();
+    return Promise.reject(new Error(
+      `${fact} cannot be announced inside Together<[…]> (${held}): announcing is dispatch, `
+      + `so subscribers and the carrier would have it while these writes can still be taken `
+      + `back. Announce after run() returns, when it is true.`,
+    ));
+  },
+
+  currentChain: () => chain.getStore() ?? [],
+
+  enterChain<R>(fact: string, fn: () => Promise<R>): Promise<R> {
+    return chain.run([...(chain.getStore() ?? []), fact], fn);
+  },
+};

package/src/boot/ambient.queue.ts

@@ -0,0 +1,75 @@
+/**
+ * The realization for a runtime with no async context: it cannot tell whose frame is
+ * open, so it never guesses — it waits its turn.
+ *
+ * Two consequences the boot reports rather than hides: frames run one at a time, and a
+ * frame opened inside another is not refused, it waits for itself and times out.
+ */
+import type { Ambient } from './ambient-port.js';
+
+/** What a nested frame waits before it is told what it did — the hang, measured, plus a name. */
+const NESTED_TIMEOUT_MS = 5_000;
+
+let busy: Promise<void> | undefined;
+let holder: string | undefined;
+
+const settled = () => undefined;
+
+/** Resolves when `p` settles or `ms` elapses, whichever comes first, holding no timer after. */
+function raceWith(p: Promise<void>, ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    const clear = () => { clearTimeout(timer); resolve(); };
+    void p.then(clear, clear);
+  });
+}
+
+export const ambient: Ambient = {
+  degraded: true,
+
+  async enterFrame<R>(key: string, fn: () => Promise<R>): Promise<R> {
+    const deadline = Date.now() + NESTED_TIMEOUT_MS;
+    for (;;) {
+      // Nothing may await between this test and the reservation below, or two waiters
+      // woken in the same tick would both take the frame.
+      if (busy === undefined) break;
+      const left = deadline - Date.now();
+      if (left <= 0) {
+        throw new Error(
+          `Together<[…]> (${key}) waited ${NESTED_TIMEOUT_MS}ms for ${holder} and gave up. `
+          + `This runtime has no async context, so a frame opened inside another waits for `
+          + `itself instead of being refused. Two frames that must both hold are ONE frame — `
+          + `declare a single Together naming every member.`,
+        );
+      }
+      await raceWith(busy, left);
+    }
+    // Held BEFORE `fn` runs: the first thing a frame's body does may be to open another,
+    // and reserving on the returned promise would be one tick too late to see it.
+    let release = settled as () => void;
+    busy = new Promise<void>((resolve) => { release = resolve; });
+    holder = key;
+    try {
+      return await fn();
+    } finally {
+      busy = undefined;
+      holder = undefined;
+      release();
+    }
+  },
+
+  /**
+   * Waits rather than refuses: whose frame is open cannot be told here, and refusing on
+   * that would refuse an announcement made by an unrelated call.
+   */
+  async beforeAnnounce(_fact: string): Promise<void> {
+    while (busy) await raceWith(busy, NESTED_TIMEOUT_MS);
+  },
+
+  /** No chain can be followed here — an emission ring is not detected. Said at boot. */
+  currentChain: () => [],
+
+  enterChain<R>(_fact: string, fn: () => Promise<R>): Promise<R> {
+    return fn();
+  },
+};