@agimon-ai/po-core 0.0.0-alpha.0

package/dist/src/schemas/readiness.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.mjs","names":[],"sources":["../../../src/schemas/readiness.ts"],"sourcesContent":["import type { Context } from '@deepseek-ai/cordis';\n\n/** Cordis service name for session-scoped package initialization. */\nexport const DOOM_READINESS_SERVICE = 'doom/readiness';\n\n/** Stable machine-readable failures produced by the readiness contract. */\nexport const DOOM_READINESS_ERROR_CODE = {\n  cancelled: 'DOOM_READINESS_CANCELLED',\n  disposed: 'DOOM_READINESS_DISPOSED',\n  duplicate: 'DOOM_READINESS_DUPLICATE',\n  failed: 'DOOM_READINESS_FAILED',\n  invalidArgument: 'DOOM_READINESS_INVALID_ARGUMENT',\n  unavailable: 'DOOM_READINESS_UNAVAILABLE',\n  waitAborted: 'DOOM_READINESS_WAIT_ABORTED',\n} as const;\n\nexport type DoomReadinessErrorCode = (typeof DOOM_READINESS_ERROR_CODE)[keyof typeof DOOM_READINESS_ERROR_CODE];\nexport type DoomReadinessState = 'pending' | 'ready' | 'degraded' | 'failed' | 'cancelled';\n\nexport interface DoomReadinessErrorDetail {\n  readonly code: DoomReadinessErrorCode;\n  readonly message: string;\n}\n\n/** Immutable public state for the latest generation of one package. */\nexport interface DoomReadinessSnapshot {\n  readonly packageId: string;\n  readonly generation: string;\n  readonly state: DoomReadinessState;\n  readonly diagnostics: readonly string[];\n  readonly error?: DoomReadinessErrorDetail;\n}\n\nexport interface DoomReadinessTaskResult<TValue> {\n  readonly value: TValue;\n  readonly diagnostics?: readonly string[];\n}\n\nexport type DoomReadinessTask<TValue> = (signal: AbortSignal) => Promise<DoomReadinessTaskResult<TValue>>;\n\nexport interface DoomReadinessWaitOptions {\n  readonly signal?: AbortSignal;\n}\n\nexport interface DoomReadinessHandle<TValue> {\n  readonly packageId: string;\n  readonly generation: string;\n  /** Waits for this package only. Degraded initialization still returns its value. */\n  wait(options?: DoomReadinessWaitOptions): Promise<TValue>;\n  /** Reads this handle's generation, even after a newer generation replaces it. */\n  snapshot(): DoomReadinessSnapshot;\n}\n\nexport interface DoomReadinessNotification {\n  readonly packageId: string;\n  readonly generation: string;\n  readonly state: 'degraded' | 'failed';\n  readonly diagnostics: readonly string[];\n  readonly error?: DoomReadinessErrorDetail;\n}\n\nexport interface DoomReadinessCoordinatorOptions {\n  /** Called once when a task becomes degraded or failed. */\n  readonly notify?: (notification: DoomReadinessNotification) => void | Promise<void>;\n}\n\nexport interface DoomReadinessCoordinator {\n  start<TValue>(packageId: string, generation: string, task: DoomReadinessTask<TValue>): DoomReadinessHandle<TValue>;\n  /** Reads the latest generation registered for a package. */\n  read(packageId: string): DoomReadinessSnapshot | undefined;\n  /** Reads the latest generation of every registered package. */\n  snapshots(): readonly DoomReadinessSnapshot[];\n  /** Aborts pending work and waits for every started task to settle. */\n  dispose(): Promise<void>;\n}\n\ninterface ReadinessRecord {\n  readonly token: symbol;\n  readonly packageId: string;\n  readonly generation: string;\n  readonly controller: AbortController;\n  readonly terminal: Promise<void>;\n  readonly resolveTerminal: () => void;\n  operation: Promise<unknown>;\n  state: DoomReadinessState;\n  diagnostics: readonly string[];\n  error?: DoomReadinessError;\n  value?: unknown;\n  hasValue: boolean;\n  notified: boolean;\n}\n\nexport interface DoomReadinessErrorOptions {\n  readonly packageId?: string;\n  readonly generation?: string;\n  readonly cause?: unknown;\n}\n\n/** Error returned to package callers without exposing task-specific rejection shapes. */\nexport class DoomReadinessError extends Error {\n  readonly code: DoomReadinessErrorCode;\n  readonly packageId?: string;\n  readonly generation?: string;\n\n  constructor(code: DoomReadinessErrorCode, message: string, input: DoomReadinessErrorOptions = {}) {\n    super(message, input.cause === undefined ? undefined : { cause: input.cause });\n    this.name = 'DoomReadinessError';\n    this.code = code;\n    this.packageId = input.packageId;\n    this.generation = input.generation;\n  }\n}\n\nfunction createTerminal(): { readonly promise: Promise<void>; readonly resolve: () => void } {\n  let resolve = (): void => undefined;\n  const promise = new Promise<void>((settle) => {\n    resolve = settle;\n  });\n  return { promise, resolve };\n}\n\nfunction frozenDiagnostics(diagnostics: readonly string[] | undefined): readonly string[] {\n  if (diagnostics === undefined) return Object.freeze([]);\n  if (!Array.isArray(diagnostics) || diagnostics.some((diagnostic) => typeof diagnostic !== 'string')) {\n    throw new TypeError('Doom readiness task diagnostics must be an array of strings.');\n  }\n  return Object.freeze([...diagnostics]);\n}\n\nfunction errorDetail(error: DoomReadinessError | undefined): DoomReadinessErrorDetail | undefined {\n  return error === undefined ? undefined : Object.freeze({ code: error.code, message: error.message });\n}\n\nfunction recordSnapshot(record: ReadinessRecord): DoomReadinessSnapshot {\n  return Object.freeze({\n    packageId: record.packageId,\n    generation: record.generation,\n    state: record.state,\n    diagnostics: record.diagnostics,\n    ...(record.error === undefined ? {} : { error: errorDetail(record.error) }),\n  });\n}\n\nfunction rethrowAsync(error: unknown): void {\n  queueMicrotask(() => {\n    throw error instanceof Error ? error : new Error(String(error));\n  });\n}\n\nfunction waitAbortedError(record: ReadinessRecord, signal: AbortSignal): DoomReadinessError {\n  return new DoomReadinessError(\n    DOOM_READINESS_ERROR_CODE.waitAborted,\n    `Waiting for Doom package '${record.packageId}' readiness was aborted.`,\n    { packageId: record.packageId, generation: record.generation, cause: signal.reason },\n  );\n}\n\nfunction waitForTerminal(record: ReadinessRecord, signal: AbortSignal | undefined): Promise<void> {\n  if (signal === undefined) return record.terminal;\n  if (signal.aborted) return Promise.reject(waitAbortedError(record, signal));\n\n  return new Promise<void>((resolve, reject) => {\n    const onAbort = (): void => {\n      reject(waitAbortedError(record, signal));\n    };\n    signal.addEventListener('abort', onAbort, { once: true });\n    void record.terminal.then(() => {\n      signal.removeEventListener('abort', onAbort);\n      resolve();\n    });\n  });\n}\n\n/** Creates the session-scoped coordinator value published through Cordis. */\nexport function createDoomReadinessCoordinator(\n  options: DoomReadinessCoordinatorOptions = {},\n): DoomReadinessCoordinator {\n  const records = new Map<string, ReadinessRecord>();\n  let disposed = false;\n  let disposal: Promise<void> | undefined;\n\n  const current = (record: ReadinessRecord): boolean =>\n    !disposed && records.get(record.packageId)?.token === record.token && record.state === 'pending';\n\n  const notify = (record: ReadinessRecord): void => {\n    if (record.notified || (record.state !== 'degraded' && record.state !== 'failed')) return;\n    record.notified = true;\n    const notification = Object.freeze({\n      packageId: record.packageId,\n      generation: record.generation,\n      state: record.state,\n      diagnostics: record.diagnostics,\n      ...(record.error === undefined ? {} : { error: errorDetail(record.error) }),\n    });\n    if (options.notify) void Promise.resolve(options.notify(notification)).catch(rethrowAsync);\n  };\n\n  const finish = (\n    record: ReadinessRecord,\n    state: Exclude<DoomReadinessState, 'pending'>,\n    input: {\n      readonly value?: unknown;\n      readonly hasValue?: boolean;\n      readonly diagnostics?: readonly string[];\n      readonly error?: DoomReadinessError;\n    } = {},\n  ): void => {\n    if (!current(record)) return;\n    record.state = state;\n    record.value = input.value;\n    record.hasValue = input.hasValue ?? false;\n    record.diagnostics = input.diagnostics ?? Object.freeze([]);\n    record.error = input.error;\n    record.resolveTerminal();\n    notify(record);\n  };\n\n  const handleFor = <TValue>(record: ReadinessRecord): DoomReadinessHandle<TValue> =>\n    Object.freeze({\n      packageId: record.packageId,\n      generation: record.generation,\n      snapshot: () => recordSnapshot(record),\n      wait: async (waitOptions: DoomReadinessWaitOptions = {}): Promise<TValue> => {\n        await waitForTerminal(record, waitOptions.signal);\n        if (record.state === 'ready' || record.state === 'degraded') {\n          if (!record.hasValue) {\n            throw new DoomReadinessError(\n              DOOM_READINESS_ERROR_CODE.failed,\n              `Doom package '${record.packageId}' readiness completed without a value.`,\n              { packageId: record.packageId, generation: record.generation },\n            );\n          }\n          return record.value as TValue;\n        }\n        if (record.error) throw record.error;\n        throw new DoomReadinessError(\n          DOOM_READINESS_ERROR_CODE.failed,\n          `Doom package '${record.packageId}' readiness did not complete.`,\n          { packageId: record.packageId, generation: record.generation },\n        );\n      },\n    });\n\n  return Object.freeze({\n    start<TValue>(packageId: string, generation: string, task: DoomReadinessTask<TValue>): DoomReadinessHandle<TValue> {\n      if (disposed) {\n        throw new DoomReadinessError(\n          DOOM_READINESS_ERROR_CODE.disposed,\n          'The Doom readiness coordinator has been disposed.',\n          { packageId, generation },\n        );\n      }\n      if (typeof packageId !== 'string' || packageId.trim().length === 0) {\n        throw new DoomReadinessError(\n          DOOM_READINESS_ERROR_CODE.invalidArgument,\n          'Doom readiness requires a non-empty package id.',\n          { packageId, generation },\n        );\n      }\n      if (typeof generation !== 'string' || generation.trim().length === 0) {\n        throw new DoomReadinessError(\n          DOOM_READINESS_ERROR_CODE.invalidArgument,\n          'Doom readiness requires a non-empty generation.',\n          { packageId, generation },\n        );\n      }\n      if (typeof task !== 'function') {\n        throw new DoomReadinessError(\n          DOOM_READINESS_ERROR_CODE.invalidArgument,\n          'Doom readiness requires an initialization task.',\n          { packageId, generation },\n        );\n      }\n\n      const previous = records.get(packageId);\n      if (previous?.state === 'pending') {\n        throw new DoomReadinessError(\n          DOOM_READINESS_ERROR_CODE.duplicate,\n          `Doom package '${packageId}' already has live readiness work.`,\n          { packageId, generation },\n        );\n      }\n\n      const terminal = createTerminal();\n      const controller = new AbortController();\n      const record: ReadinessRecord = {\n        token: Symbol(packageId),\n        packageId,\n        generation,\n        controller,\n        terminal: terminal.promise,\n        resolveTerminal: terminal.resolve,\n        operation: Promise.resolve(),\n        state: 'pending',\n        diagnostics: Object.freeze([]),\n        hasValue: false,\n        notified: false,\n      };\n      records.set(packageId, record);\n\n      const operation = Promise.resolve().then(() => {\n        if (controller.signal.aborted) throw controller.signal.reason;\n        return task(controller.signal);\n      });\n      record.operation = operation;\n      void operation\n        .then(\n          (result) => {\n            if (!current(record)) return;\n            if (result === null || typeof result !== 'object' || !Object.hasOwn(result, 'value')) {\n              finish(record, 'failed', {\n                error: new DoomReadinessError(\n                  DOOM_READINESS_ERROR_CODE.failed,\n                  `Doom package '${packageId}' returned an invalid readiness result.`,\n                  { packageId, generation },\n                ),\n              });\n              return;\n            }\n            try {\n              const diagnostics = frozenDiagnostics(result.diagnostics);\n              finish(record, diagnostics.length === 0 ? 'ready' : 'degraded', {\n                value: result.value,\n                hasValue: true,\n                diagnostics,\n              });\n            } catch (error) {\n              finish(record, 'failed', {\n                error: new DoomReadinessError(\n                  DOOM_READINESS_ERROR_CODE.failed,\n                  `Doom package '${packageId}' returned an invalid readiness result.`,\n                  { packageId, generation, cause: error },\n                ),\n              });\n            }\n          },\n          (error: unknown) => {\n            finish(record, 'failed', {\n              error: new DoomReadinessError(\n                DOOM_READINESS_ERROR_CODE.failed,\n                `Doom package '${packageId}' readiness failed: ${error instanceof Error ? error.message : String(error)}`,\n                { packageId, generation, cause: error },\n              ),\n            });\n          },\n        )\n        .catch(rethrowAsync);\n\n      return handleFor<TValue>(record);\n    },\n\n    read(packageId: string): DoomReadinessSnapshot | undefined {\n      const record = records.get(packageId);\n      return record === undefined ? undefined : recordSnapshot(record);\n    },\n\n    snapshots(): readonly DoomReadinessSnapshot[] {\n      return Object.freeze([...records.values()].map(recordSnapshot));\n    },\n\n    dispose(): Promise<void> {\n      if (disposal) return disposal;\n      disposed = true;\n      const operations = [...records.values()].map((record) => {\n        if (record.state === 'pending') {\n          const error = new DoomReadinessError(\n            DOOM_READINESS_ERROR_CODE.cancelled,\n            `Doom package '${record.packageId}' readiness was cancelled.`,\n            { packageId: record.packageId, generation: record.generation },\n          );\n          record.state = 'cancelled';\n          record.error = error;\n          record.resolveTerminal();\n          record.controller.abort(error);\n        }\n        return record.operation;\n      });\n      disposal = Promise.allSettled(operations).then(() => undefined);\n      return disposal;\n    },\n  });\n}\n\n/** Reads the coordinator visible to the current Cordis plugin context. */\nexport function readDoomReadinessCoordinator(ctx: Context): DoomReadinessCoordinator | undefined {\n  return ctx.get(DOOM_READINESS_SERVICE) as DoomReadinessCoordinator | undefined;\n}\n\n/** Reads the coordinator or reports that Config has not published session readiness. */\nexport function requireDoomReadinessCoordinator(ctx: Context): DoomReadinessCoordinator {\n  const coordinator = readDoomReadinessCoordinator(ctx);\n  if (coordinator) return coordinator;\n  throw new DoomReadinessError(\n    DOOM_READINESS_ERROR_CODE.unavailable,\n    'Doom readiness is unavailable. Load the Po Config core.',\n  );\n}\n"],"mappings":"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"}

package/dist/src/schemas/sandboxHarness.cjs

@@ -0,0 +1,29 @@
+//#region src/schemas/sandboxHarness.ts
+/**
+* Sandbox harness contract.
+*
+* A layer package that owns sandboxed launches exports a module at the
+* `./sandbox-harness` subpath. The harness resolves that module from the
+* selected composition and delegates the whole launch to it, so core never
+* depends on a concrete sandbox technology.
+*/
+/** Exports subpath a sandbox-owning layer package declares. */
+const SANDBOX_HARNESS_EXPORT_SUBPATH = "./sandbox-harness";
+/** Marks a process that already runs inside a Po sandbox. */
+const PO_SANDBOX_ENV = "PO_SANDBOX";
+const SANDBOX_FLAG = "1";
+/** True inside a sandboxed session, which is how a provider refuses to nest. */
+function insideSandbox(environment = process.env) {
+	return environment[PO_SANDBOX_ENV] === SANDBOX_FLAG;
+}
+/** Narrowing guard for a dynamically imported sandbox harness entry. */
+function isSandboxHarnessModule(value) {
+	return typeof value === "object" && value !== null && typeof value.launchSandbox === "function";
+}
+//#endregion
+exports.PO_SANDBOX_ENV = PO_SANDBOX_ENV;
+exports.SANDBOX_HARNESS_EXPORT_SUBPATH = SANDBOX_HARNESS_EXPORT_SUBPATH;
+exports.insideSandbox = insideSandbox;
+exports.isSandboxHarnessModule = isSandboxHarnessModule;
+
+//# sourceMappingURL=sandboxHarness.cjs.map

package/dist/src/schemas/sandboxHarness.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandboxHarness.cjs","names":[],"sources":["../../../src/schemas/sandboxHarness.ts"],"sourcesContent":["/**\n * Sandbox harness contract.\n *\n * A layer package that owns sandboxed launches exports a module at the\n * `./sandbox-harness` subpath. The harness resolves that module from the\n * selected composition and delegates the whole launch to it, so core never\n * depends on a concrete sandbox technology.\n */\n\n/** Exports subpath a sandbox-owning layer package declares. */\nexport const SANDBOX_HARNESS_EXPORT_SUBPATH = './sandbox-harness';\n\n/** Marks a process that already runs inside a Po sandbox. */\nexport const PO_SANDBOX_ENV = 'PO_SANDBOX';\n\nconst SANDBOX_FLAG = '1';\n\n/** True inside a sandboxed session, which is how a provider refuses to nest. */\nexport function insideSandbox(environment: NodeJS.ProcessEnv = process.env): boolean {\n  return environment[PO_SANDBOX_ENV] === SANDBOX_FLAG;\n}\n\n/** One sandboxed launch, owned end to end by the providing layer. */\nexport interface SandboxLaunchRequest {\n  /** Repository the sandbox mounts and works against. */\n  repoRoot: string;\n  /** Working directory of the launch, expected to sit inside the mounted repository. */\n  cwd: string;\n  /**\n   * Harness arguments the in-sandbox launcher replays. Never contains the\n   * sandbox flag itself: a sandboxed launch must not provision another.\n   */\n  forwardArgs: string[];\n  /** Host environment the provider filters before any of it enters the sandbox. */\n  environment: NodeJS.ProcessEnv;\n  /** Receives one human-readable line per provisioning decision. */\n  onProgress?: (message: string) => void;\n}\n\nexport interface SandboxHarnessModule {\n  /** Provisions the sandbox, runs the launch inside it, and reports the exit code. */\n  launchSandbox(request: SandboxLaunchRequest): Promise<number>;\n}\n\n/** Narrowing guard for a dynamically imported sandbox harness entry. */\nexport function isSandboxHarnessModule(value: unknown): value is SandboxHarnessModule {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    typeof (value as { launchSandbox?: unknown }).launchSandbox === 'function'\n  );\n}\n"],"mappings":";;;;;;;;;;AAUA,MAAa,iCAAiC;;AAG9C,MAAa,iBAAiB;AAE9B,MAAM,eAAe;;AAGrB,SAAgB,cAAc,cAAiC,QAAQ,KAAc;CACnF,OAAO,YAAY,oBAAoB;AACzC;;AAyBA,SAAgB,uBAAuB,OAA+C;CACpF,OACE,OAAO,UAAU,YACjB,UAAU,QACV,OAAQ,MAAsC,kBAAkB;AAEpE"}

package/dist/src/schemas/sandboxHarness.d.mts

@@ -0,0 +1,39 @@
+//#region src/schemas/sandboxHarness.d.ts
+/**
+ * Sandbox harness contract.
+ *
+ * A layer package that owns sandboxed launches exports a module at the
+ * `./sandbox-harness` subpath. The harness resolves that module from the
+ * selected composition and delegates the whole launch to it, so core never
+ * depends on a concrete sandbox technology.
+ */
+/** Exports subpath a sandbox-owning layer package declares. */
+export declare const SANDBOX_HARNESS_EXPORT_SUBPATH = "./sandbox-harness";
+/** Marks a process that already runs inside a Po sandbox. */
+export declare const PO_SANDBOX_ENV = "PO_SANDBOX";
+/** True inside a sandboxed session, which is how a provider refuses to nest. */
+export declare function insideSandbox(environment?: NodeJS.ProcessEnv): boolean;
+/** One sandboxed launch, owned end to end by the providing layer. */
+export interface SandboxLaunchRequest {
+  /** Repository the sandbox mounts and works against. */
+  repoRoot: string;
+  /** Working directory of the launch, expected to sit inside the mounted repository. */
+  cwd: string;
+  /**
+   * Harness arguments the in-sandbox launcher replays. Never contains the
+   * sandbox flag itself: a sandboxed launch must not provision another.
+   */
+  forwardArgs: string[];
+  /** Host environment the provider filters before any of it enters the sandbox. */
+  environment: NodeJS.ProcessEnv;
+  /** Receives one human-readable line per provisioning decision. */
+  onProgress?: (message: string) => void;
+}
+export interface SandboxHarnessModule {
+  /** Provisions the sandbox, runs the launch inside it, and reports the exit code. */
+  launchSandbox(request: SandboxLaunchRequest): Promise<number>;
+}
+/** Narrowing guard for a dynamically imported sandbox harness entry. */
+export declare function isSandboxHarnessModule(value: unknown): value is SandboxHarnessModule;
+//#endregion
+//# sourceMappingURL=sandboxHarness.d.mts.map

package/dist/src/schemas/sandboxHarness.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandboxHarness.d.mts","names":[],"sources":["../../../src/schemas/sandboxHarness.ts"],"mappings":";;;;;;;;;;qBAUa;;qBAGA;;wBAKG,cAAc,cAAa,OAAO;;iBAKjC;;EAEf;;EAEA;;;;;EAKA;;EAEA,aAAa,OAAO;;EAEpB,cAAc;;iBAGC;;EAEf,cAAc,SAAS,uBAAuB;;;wBAIhC,uBAAuB,iBAAiB,SAAS"}

package/dist/src/schemas/sandboxHarness.mjs

@@ -0,0 +1,26 @@
+//#region src/schemas/sandboxHarness.ts
+/**
+* Sandbox harness contract.
+*
+* A layer package that owns sandboxed launches exports a module at the
+* `./sandbox-harness` subpath. The harness resolves that module from the
+* selected composition and delegates the whole launch to it, so core never
+* depends on a concrete sandbox technology.
+*/
+/** Exports subpath a sandbox-owning layer package declares. */
+const SANDBOX_HARNESS_EXPORT_SUBPATH = "./sandbox-harness";
+/** Marks a process that already runs inside a Po sandbox. */
+const PO_SANDBOX_ENV = "PO_SANDBOX";
+const SANDBOX_FLAG = "1";
+/** True inside a sandboxed session, which is how a provider refuses to nest. */
+function insideSandbox(environment = process.env) {
+	return environment[PO_SANDBOX_ENV] === SANDBOX_FLAG;
+}
+/** Narrowing guard for a dynamically imported sandbox harness entry. */
+function isSandboxHarnessModule(value) {
+	return typeof value === "object" && value !== null && typeof value.launchSandbox === "function";
+}
+//#endregion
+export { PO_SANDBOX_ENV, SANDBOX_HARNESS_EXPORT_SUBPATH, insideSandbox, isSandboxHarnessModule };
+
+//# sourceMappingURL=sandboxHarness.mjs.map

package/dist/src/schemas/sandboxHarness.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandboxHarness.mjs","names":[],"sources":["../../../src/schemas/sandboxHarness.ts"],"sourcesContent":["/**\n * Sandbox harness contract.\n *\n * A layer package that owns sandboxed launches exports a module at the\n * `./sandbox-harness` subpath. The harness resolves that module from the\n * selected composition and delegates the whole launch to it, so core never\n * depends on a concrete sandbox technology.\n */\n\n/** Exports subpath a sandbox-owning layer package declares. */\nexport const SANDBOX_HARNESS_EXPORT_SUBPATH = './sandbox-harness';\n\n/** Marks a process that already runs inside a Po sandbox. */\nexport const PO_SANDBOX_ENV = 'PO_SANDBOX';\n\nconst SANDBOX_FLAG = '1';\n\n/** True inside a sandboxed session, which is how a provider refuses to nest. */\nexport function insideSandbox(environment: NodeJS.ProcessEnv = process.env): boolean {\n  return environment[PO_SANDBOX_ENV] === SANDBOX_FLAG;\n}\n\n/** One sandboxed launch, owned end to end by the providing layer. */\nexport interface SandboxLaunchRequest {\n  /** Repository the sandbox mounts and works against. */\n  repoRoot: string;\n  /** Working directory of the launch, expected to sit inside the mounted repository. */\n  cwd: string;\n  /**\n   * Harness arguments the in-sandbox launcher replays. Never contains the\n   * sandbox flag itself: a sandboxed launch must not provision another.\n   */\n  forwardArgs: string[];\n  /** Host environment the provider filters before any of it enters the sandbox. */\n  environment: NodeJS.ProcessEnv;\n  /** Receives one human-readable line per provisioning decision. */\n  onProgress?: (message: string) => void;\n}\n\nexport interface SandboxHarnessModule {\n  /** Provisions the sandbox, runs the launch inside it, and reports the exit code. */\n  launchSandbox(request: SandboxLaunchRequest): Promise<number>;\n}\n\n/** Narrowing guard for a dynamically imported sandbox harness entry. */\nexport function isSandboxHarnessModule(value: unknown): value is SandboxHarnessModule {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    typeof (value as { launchSandbox?: unknown }).launchSandbox === 'function'\n  );\n}\n"],"mappings":";;;;;;;;;;AAUA,MAAa,iCAAiC;;AAG9C,MAAa,iBAAiB;AAE9B,MAAM,eAAe;;AAGrB,SAAgB,cAAc,cAAiC,QAAQ,KAAc;CACnF,OAAO,YAAY,oBAAoB;AACzC;;AAyBA,SAAgB,uBAAuB,OAA+C;CACpF,OACE,OAAO,UAAU,YACjB,UAAU,QACV,OAAQ,MAAsC,kBAAkB;AAEpE"}

package/dist/src/schemas/serverBundle.d.mts

@@ -0,0 +1,19 @@
+import { DoomApiScope } from "./packageApi.mjs";
+//#region src/schemas/serverBundle.d.ts
+/** Every occurrence that can activate a package in this repository. */
+export interface DoomServerBundleOwner {
+  readonly majorMode: string;
+  readonly layer: string;
+}
+export interface DoomServerBundleEntry {
+  readonly packageName: string;
+  /** The declared package-relative source entry, retained for attribution. */
+  readonly entry: string;
+  /** Absolute path of the package's built module; the live loader imports it from its content URL. */
+  readonly module: string;
+  readonly scopes: readonly DoomApiScope[];
+  readonly owners: readonly DoomServerBundleOwner[];
+  readonly required: boolean;
+}
+//#endregion
+//# sourceMappingURL=serverBundle.d.mts.map

package/dist/src/schemas/serverBundle.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serverBundle.d.mts","names":[],"sources":["../../../src/schemas/serverBundle.ts"],"mappings":";;;iBAGiB;WACN;WACA;;iBAGM;WACN;;WAEA;;WAEA;WACA,iBAAiB;WACjB,iBAAiB;WACjB"}

package/dist/src/schemas/serverFacet.cjs

@@ -0,0 +1,111 @@
+//#region src/schemas/serverFacet.ts
+/** The host a server facet contributes to. */
+const DOOM_SERVER_HOST_SERVICE = "doom/server-host";
+function readDoomServerHost(context) {
+	return context.get(DOOM_SERVER_HOST_SERVICE);
+}
+function requireDoomServerHost(context) {
+	const service = readDoomServerHost(context);
+	if (!service) throw new Error("The Doom server host is unavailable. Start a Doom server first.");
+	return service;
+}
+/** The package.json field a package declares its server facet under. */
+const DOOM_SERVER_FACET_MANIFEST_FIELD = "poServer";
+/** The default export a facet module must provide, so a host can install it. */
+const DOOM_SERVER_FACET_EXPORT = "default";
+/** Read pure root metadata without initializing or mounting the root. */
+function composeServerProviderOverrides(...roots) {
+	return (context) => roots.flatMap((root) => {
+		if (typeof root !== "function" && typeof root !== "object" || root === null) return [];
+		const callback = root.providerOverrides;
+		return typeof callback === "function" ? callback(context) : [];
+	});
+}
+/** Capture schema inference before heterogeneous methods enter a contribution array. */
+function defineServerMethod(definition, handler) {
+	return { register: (host) => host.registerMethod(definition, handler) };
+}
+var DoomServerFacetManifestError = class extends Error {
+	constructor(packageDir, message) {
+		super(`${DOOM_SERVER_FACET_MANIFEST_FIELD} manifest in ${packageDir}: ${message}`);
+		this.name = "DoomServerFacetManifestError";
+	}
+};
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Narrows a module's default export, so a broken package is a notice rather than a crash. */
+function isDoomServerFacet(value) {
+	return isRecord(value) && typeof value.apply === "function";
+}
+function normalizePath(packageDir, field, value) {
+	if (typeof value !== "string" || !value.startsWith("./") || value.includes("..")) throw new DoomServerFacetManifestError(packageDir, `${field} must be a package-relative ./path with no '..'.`);
+	return value;
+}
+function normalizeScopes(packageDir, value) {
+	if (value === void 0) throw new DoomServerFacetManifestError(packageDir, "scopes must be declared explicitly.");
+	if (!Array.isArray(value) || value.length === 0) throw new DoomServerFacetManifestError(packageDir, "scopes must name 'global', 'workspace', or 'session'.");
+	const scopes = [];
+	for (const scope of value) {
+		if (scope !== "session" && scope !== "global" && scope !== "workspace") throw new DoomServerFacetManifestError(packageDir, `Unknown scope '${String(scope)}'; resync for the three-level host.`);
+		if (!scopes.includes(scope)) scopes.push(scope);
+	}
+	return scopes;
+}
+/**
+* Validates one package.json's `poServer` block.
+*
+* `dist` is required because a host imports the built entry the package ships,
+* never its source.
+*/
+function declaredServerFacetsOf(packageDir, manifest) {
+	const declared = manifest[DOOM_SERVER_FACET_MANIFEST_FIELD];
+	if (declared === void 0) return [];
+	if (!isRecord(declared)) throw new DoomServerFacetManifestError(packageDir, "the block must be an object naming entry and dist.");
+	const entry = normalizePath(packageDir, "entry", declared.entry);
+	if (declared.dist === void 0) throw new DoomServerFacetManifestError(packageDir, "dist is required: a host imports the built entry the package ships, never its source.");
+	const dist = normalizePath(packageDir, "dist", declared.dist);
+	if (declared.required !== void 0 && typeof declared.required !== "boolean") throw new DoomServerFacetManifestError(packageDir, "required must be a boolean.");
+	return [{
+		packageName: typeof manifest.name === "string" ? manifest.name : packageDir,
+		packageDir,
+		entry,
+		dist,
+		scopes: normalizeScopes(packageDir, declared.scopes),
+		...typeof declared.required === "boolean" ? { required: declared.required } : {}
+	}];
+}
+/**
+* The deterministic order hosts install in. A package appears once: the first
+* directory claiming a package name keeps it and the later one is dropped with
+* a notice, so a duplicated install never installs a facet twice.
+*/
+function orderServerFacets(facets, onNotice = () => void 0) {
+	const sorted = [...facets].sort((left, right) => left.packageName.localeCompare(right.packageName) || left.packageDir.localeCompare(right.packageDir));
+	const owners = /* @__PURE__ */ new Map();
+	const kept = [];
+	for (const facet of sorted) {
+		const holder = owners.get(facet.packageName);
+		if (holder !== void 0) {
+			onNotice(`server facet '${facet.packageName}' from ${facet.packageDir} is skipped: ${holder.packageDir} already claims it.`);
+			continue;
+		}
+		owners.set(facet.packageName, facet);
+		kept.push(facet);
+	}
+	return kept;
+}
+//#endregion
+exports.DOOM_SERVER_FACET_EXPORT = DOOM_SERVER_FACET_EXPORT;
+exports.DOOM_SERVER_FACET_MANIFEST_FIELD = DOOM_SERVER_FACET_MANIFEST_FIELD;
+exports.DOOM_SERVER_HOST_SERVICE = DOOM_SERVER_HOST_SERVICE;
+exports.DoomServerFacetManifestError = DoomServerFacetManifestError;
+exports.composeServerProviderOverrides = composeServerProviderOverrides;
+exports.declaredServerFacetsOf = declaredServerFacetsOf;
+exports.defineServerMethod = defineServerMethod;
+exports.isDoomServerFacet = isDoomServerFacet;
+exports.orderServerFacets = orderServerFacets;
+exports.readDoomServerHost = readDoomServerHost;
+exports.requireDoomServerHost = requireDoomServerHost;
+
+//# sourceMappingURL=serverFacet.cjs.map

package/dist/src/schemas/serverFacet.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"serverFacet.cjs","names":[],"sources":["../../../src/schemas/serverFacet.ts"],"sourcesContent":["import type { Context } from '@deepseek-ai/cordis';\n/**\n * The server facet a package installs into a headless host.\n *\n * A package already ships a Pi extension facet for the agent process. This is\n * the second facet: one cordis plugin that a session server or the cockpit hub\n * installs, through which the package contributes its HTTP surface and any\n * behaviour that has to run outside the agent.\n *\n * A facet is installed and disposed like every other Doom contribution. It\n * registers its API from inside that lifecycle, so server behaviour has a clear\n * owner and disposer.\n */\nimport type { Static, TSchema } from 'typebox';\n\nimport type { DoomHeadlessHostService, DoomHeadlessToolRestriction } from './headless';\nimport type { DoomHeadlessTool, DoomHeadlessCommand } from './headless';\nimport type { DoomHubChannel } from './hubChannel';\nimport type { DoomApi, DoomApiContext, DoomApiScope } from './packageApi';\nimport type { DoomPluginTool, DoomPluginCommand } from './pluginContributions';\nimport type { DoomPluginCaller, DoomPluginMethod } from './pluginProtocol';\nimport type { DoomToolRestrictionDefinition } from './toolSurface';\n\n/** The host a server facet contributes to. */\nexport const DOOM_SERVER_HOST_SERVICE = 'doom/server-host';\n\nexport interface DoomServerRegistration {\n  /** Whether the API was mounted. A refused registration is a no-op handle. */\n  readonly mounted?: boolean;\n  /** Unmount the surface and close its handler. Idempotent. */\n  dispose(): void;\n}\n\n/**\n * What a facet is handed when it installs.\n *\n * `scope` is fixed for the life of the host: a session server never becomes a\n * hub. A facet that only makes sense in one scope returns early in the other\n * rather than declaring itself twice.\n */\nexport interface DoomServerHostService {\n  readonly scope: DoomApiScope;\n  /** Identity and host-lent capabilities, the same record an API is started with. */\n  readonly context: DoomApiContext;\n  /**\n   * Mount an API under its own base path. A base path already claimed by an\n   * earlier facet is refused with a notice and a no-op handle. The same\n   * failure posture applies when the API cannot start or the host is disposed.\n   */\n  registerApi(api: DoomApi): DoomServerRegistration;\n  /** Register a live event source under this host's lifecycle. */\n  registerChannel(channel: DoomHubChannel): DoomServerRegistration;\n  /** Mount a typed call at this host's exact scope. */\n  registerMethod<TInput extends TSchema, TOutput extends TSchema>(\n    definition: DoomPluginMethod<TInput, TOutput>,\n    handler: (input: Static<TInput>, caller: DoomPluginCaller) => Static<TOutput> | Promise<Static<TOutput>>,\n  ): DoomServerRegistration;\n  /** Base paths currently mounted, in mount order. */\n  mounted(): readonly string[];\n  /** Channel frame types currently mounted, in mount order. */\n  mountedChannels(): readonly string[];\n}\n\ndeclare module '@deepseek-ai/cordis' {\n  interface Context {\n    'doom/server-host': DoomServerHostService;\n  }\n}\n\nexport function readDoomServerHost(context: Context): DoomServerHostService | undefined {\n  return context.get(DOOM_SERVER_HOST_SERVICE) as DoomServerHostService | undefined;\n}\n\nexport function requireDoomServerHost(context: Context): DoomServerHostService {\n  const service = readDoomServerHost(context);\n  if (!service) throw new Error('The Doom server host is unavailable. Start a Doom server first.');\n  return service;\n}\n\n/** The package.json field a package declares its server facet under. */\nexport const DOOM_SERVER_FACET_MANIFEST_FIELD = 'poServer';\n\n/** The default export a facet module must provide, so a host can install it. */\nexport const DOOM_SERVER_FACET_EXPORT = 'default';\n\n/**\n * One package's server contributions, as a Cordis object plugin.\n *\n * The object form rather than a bare function, because it is the only shape\n * that declares its own `inject`. That matters to a host: a plugin carrying\n * its dependencies is a single fiber, so `fiber.await()` settles once `apply`\n * has run, and the host can decide whether to open a listener from a mount\n * table it knows is complete. A function facet calling `ctx.inject` inside\n * itself mounts a child fiber that the host has no handle on.\n *\n * A returned function is the disposer, run when the host's root unwinds.\n */\nexport interface DoomServerProviderOverride {\n  readonly name: string;\n  readonly baseUrl: string;\n}\nexport type DoomServerProviderOverrides = (context: {\n  readonly environment: Readonly<Record<string, string | undefined>>;\n}) => readonly DoomServerProviderOverride[];\n\n/** Read pure root metadata without initializing or mounting the root. */\nexport function composeServerProviderOverrides(...roots: readonly unknown[]): DoomServerProviderOverrides {\n  return (context) =>\n    roots.flatMap((root) => {\n      if ((typeof root !== 'function' && typeof root !== 'object') || root === null) return [];\n      const callback = (root as { providerOverrides?: DoomServerProviderOverrides }).providerOverrides;\n      return typeof callback === 'function' ? callback(context) : [];\n    });\n}\n\nexport interface DoomServerFacet {\n  readonly providerOverrides?: DoomServerProviderOverrides;\n  readonly inject?: readonly string[];\n  apply(context: Context): void | (() => void | Promise<void>) | Promise<void | (() => void | Promise<void>)>;\n}\n\n/** One instance belongs to one mounted server scope. */\nexport interface DoomServerPluginContext {\n  readonly context: Context;\n  readonly host: DoomServerHostService;\n  readonly agent?: DoomHeadlessHostService;\n  readonly signal: AbortSignal;\n}\n\nexport interface DoomServerMethod {\n  register(host: DoomServerHostService): DoomServerRegistration;\n}\n\n/** Capture schema inference before heterogeneous methods enter a contribution array. */\nexport function defineServerMethod<TInput extends TSchema, TOutput extends TSchema>(\n  definition: DoomPluginMethod<TInput, TOutput>,\n  handler: (input: Static<TInput>, caller: DoomPluginCaller) => Static<TOutput> | Promise<Static<TOutput>>,\n): DoomServerMethod {\n  return { register: (host) => host.registerMethod(definition, handler) };\n}\n\nexport interface DoomServerPluginScope {\n  readonly services?: readonly Parameters<Context['plugin']>[0][];\n  readonly channels?: readonly (() => DoomHubChannel)[];\n  readonly api?: readonly DoomApi[];\n  readonly methods?: readonly DoomServerMethod[];\n  readonly onStart?: (context: DoomServerPluginContext) => void | Promise<void>;\n  readonly onStop?: (context: DoomServerPluginContext) => void | Promise<void>;\n  readonly onDispose?: (context: DoomServerPluginContext) => void | Promise<void>;\n}\n\nexport interface DoomServerSessionPlugin extends DoomServerPluginScope {\n  readonly tools?: readonly (DoomHeadlessTool | DoomPluginTool)[];\n  readonly commands?: readonly (DoomHeadlessCommand | DoomPluginCommand)[];\n  readonly resources?: readonly Parameters<DoomHeadlessHostService['registerResource']>[0][];\n  readonly hooks?: readonly Parameters<DoomHeadlessHostService['registerHook']>[0][];\n  readonly toolRestrictions?: readonly (\n    | DoomHeadlessToolRestriction\n    | DoomToolRestrictionDefinition<() => DoomHeadlessToolRestriction>\n  )[];\n  readonly activities?: readonly Parameters<DoomHeadlessHostService['registerActivity']>[0][];\n}\n\ntype ScopeDeclaration<TScope> = TScope | ((context: DoomServerPluginContext) => TScope | Promise<TScope>);\n// Explicitly forbid session contributions even when a factory returns an inferred object.\ntype NonSessionScope = DoomServerPluginScope & {\n  readonly [K in Exclude<keyof DoomServerSessionPlugin, keyof DoomServerPluginScope>]?: never;\n};\nexport interface DoomServerPluginDefinition {\n  readonly providerOverrides?: DoomServerProviderOverrides;\n  readonly name: string;\n  readonly inject?: readonly string[];\n  readonly global?: ScopeDeclaration<NonSessionScope>;\n  readonly workspace?: ScopeDeclaration<NonSessionScope>;\n  readonly session?: ScopeDeclaration<DoomServerSessionPlugin>;\n}\n\n/** One package's validated declaration. */\nexport interface DeclaredServerFacet {\n  packageName: string;\n  packageDir: string;\n  /** Package-relative ./path to the source entry. */\n  entry: string;\n  /** Package-relative ./path to the built entry, which is what a host imports. */\n  dist: string;\n  /** Scopes this facet is installed into; both when the package names neither. */\n  scopes: readonly DoomApiScope[];\n  /** A selected host cannot be ready without this package's runtime capability. */\n  required?: boolean;\n}\n\nexport class DoomServerFacetManifestError extends Error {\n  constructor(packageDir: string, message: string) {\n    super(`${DOOM_SERVER_FACET_MANIFEST_FIELD} manifest in ${packageDir}: ${message}`);\n    this.name = 'DoomServerFacetManifestError';\n  }\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\n/** Narrows a module's default export, so a broken package is a notice rather than a crash. */\nexport function isDoomServerFacet(value: unknown): value is DoomServerFacet {\n  return isRecord(value) && typeof value.apply === 'function';\n}\n\nfunction normalizePath(packageDir: string, field: string, value: unknown): string {\n  if (typeof value !== 'string' || !value.startsWith('./') || value.includes('..')) {\n    throw new DoomServerFacetManifestError(packageDir, `${field} must be a package-relative ./path with no '..'.`);\n  }\n  return value;\n}\n\nfunction normalizeScopes(packageDir: string, value: unknown): readonly DoomApiScope[] {\n  if (value === undefined) throw new DoomServerFacetManifestError(packageDir, 'scopes must be declared explicitly.');\n  if (!Array.isArray(value) || value.length === 0) {\n    throw new DoomServerFacetManifestError(packageDir, \"scopes must name 'global', 'workspace', or 'session'.\");\n  }\n  const scopes: DoomApiScope[] = [];\n  for (const scope of value) {\n    if (scope !== 'session' && scope !== 'global' && scope !== 'workspace') {\n      throw new DoomServerFacetManifestError(\n        packageDir,\n        `Unknown scope '${String(scope)}'; resync for the three-level host.`,\n      );\n    }\n    if (!scopes.includes(scope)) scopes.push(scope);\n  }\n  return scopes;\n}\n\n/**\n * Validates one package.json's `poServer` block.\n *\n * `dist` is required because a host imports the built entry the package ships,\n * never its source.\n */\nexport function declaredServerFacetsOf(packageDir: string, manifest: Record<string, unknown>): DeclaredServerFacet[] {\n  const declared = manifest[DOOM_SERVER_FACET_MANIFEST_FIELD];\n  if (declared === undefined) return [];\n  if (!isRecord(declared)) {\n    throw new DoomServerFacetManifestError(packageDir, 'the block must be an object naming entry and dist.');\n  }\n  const entry = normalizePath(packageDir, 'entry', declared.entry);\n  if (declared.dist === undefined) {\n    throw new DoomServerFacetManifestError(\n      packageDir,\n      'dist is required: a host imports the built entry the package ships, never its source.',\n    );\n  }\n  const dist = normalizePath(packageDir, 'dist', declared.dist);\n  if (declared.required !== undefined && typeof declared.required !== 'boolean') {\n    throw new DoomServerFacetManifestError(packageDir, 'required must be a boolean.');\n  }\n  return [\n    {\n      packageName: typeof manifest.name === 'string' ? manifest.name : packageDir,\n      packageDir,\n      entry,\n      dist,\n      scopes: normalizeScopes(packageDir, declared.scopes),\n      ...(typeof declared.required === 'boolean' ? { required: declared.required } : {}),\n    },\n  ];\n}\n\n/**\n * The deterministic order hosts install in. A package appears once: the first\n * directory claiming a package name keeps it and the later one is dropped with\n * a notice, so a duplicated install never installs a facet twice.\n */\nexport function orderServerFacets(\n  facets: readonly DeclaredServerFacet[],\n  onNotice: (message: string) => void = () => undefined,\n): DeclaredServerFacet[] {\n  const sorted = [...facets].sort(\n    (left, right) =>\n      left.packageName.localeCompare(right.packageName) || left.packageDir.localeCompare(right.packageDir),\n  );\n  const owners = new Map<string, DeclaredServerFacet>();\n  const kept: DeclaredServerFacet[] = [];\n  for (const facet of sorted) {\n    const holder = owners.get(facet.packageName);\n    if (holder !== undefined) {\n      onNotice(\n        `server facet '${facet.packageName}' from ${facet.packageDir} is skipped: ${holder.packageDir} already claims it.`,\n      );\n      continue;\n    }\n    owners.set(facet.packageName, facet);\n    kept.push(facet);\n  }\n  return kept;\n}\n"],"mappings":"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"}

package/dist/src/schemas/serverFacet.d.mts

@@ -0,0 +1,152 @@
+import { DoomHubChannel } from "./hubChannel.mjs";
+import { DoomApi, DoomApiContext, DoomApiScope } from "./packageApi.mjs";
+import { DoomHeadlessCommand, DoomHeadlessHostService, DoomHeadlessTool, DoomHeadlessToolRestriction } from "./headless.mjs";
+import { DoomPluginCommand, DoomPluginTool } from "./pluginContributions.mjs";
+import { DoomPluginCaller, DoomPluginMethod } from "./pluginProtocol.mjs";
+import { DoomToolRestrictionDefinition } from "./toolSurface.mjs";
+import { Static, TSchema } from "typebox";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/schemas/serverFacet.d.ts
+/** The host a server facet contributes to. */
+export declare const DOOM_SERVER_HOST_SERVICE = "doom/server-host";
+export interface DoomServerRegistration {
+  /** Whether the API was mounted. A refused registration is a no-op handle. */
+  readonly mounted?: boolean;
+  /** Unmount the surface and close its handler. Idempotent. */
+  dispose(): void;
+}
+/**
+ * What a facet is handed when it installs.
+ *
+ * `scope` is fixed for the life of the host: a session server never becomes a
+ * hub. A facet that only makes sense in one scope returns early in the other
+ * rather than declaring itself twice.
+ */
+export interface DoomServerHostService {
+  readonly scope: DoomApiScope;
+  /** Identity and host-lent capabilities, the same record an API is started with. */
+  readonly context: DoomApiContext;
+  /**
+   * Mount an API under its own base path. A base path already claimed by an
+   * earlier facet is refused with a notice and a no-op handle. The same
+   * failure posture applies when the API cannot start or the host is disposed.
+   */
+  registerApi(api: DoomApi): DoomServerRegistration;
+  /** Register a live event source under this host's lifecycle. */
+  registerChannel(channel: DoomHubChannel): DoomServerRegistration;
+  /** Mount a typed call at this host's exact scope. */
+  registerMethod<TInput extends TSchema, TOutput extends TSchema>(definition: DoomPluginMethod<TInput, TOutput>, handler: (input: Static<TInput>, caller: DoomPluginCaller) => Static<TOutput> | Promise<Static<TOutput>>): DoomServerRegistration;
+  /** Base paths currently mounted, in mount order. */
+  mounted(): readonly string[];
+  /** Channel frame types currently mounted, in mount order. */
+  mountedChannels(): readonly string[];
+}
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    'doom/server-host': DoomServerHostService;
+  }
+}
+export declare function readDoomServerHost(context: Context): DoomServerHostService | undefined;
+export declare function requireDoomServerHost(context: Context): DoomServerHostService;
+/** The package.json field a package declares its server facet under. */
+export declare const DOOM_SERVER_FACET_MANIFEST_FIELD = "poServer";
+/** The default export a facet module must provide, so a host can install it. */
+export declare const DOOM_SERVER_FACET_EXPORT = "default";
+/**
+ * One package's server contributions, as a Cordis object plugin.
+ *
+ * The object form rather than a bare function, because it is the only shape
+ * that declares its own `inject`. That matters to a host: a plugin carrying
+ * its dependencies is a single fiber, so `fiber.await()` settles once `apply`
+ * has run, and the host can decide whether to open a listener from a mount
+ * table it knows is complete. A function facet calling `ctx.inject` inside
+ * itself mounts a child fiber that the host has no handle on.
+ *
+ * A returned function is the disposer, run when the host's root unwinds.
+ */
+export interface DoomServerProviderOverride {
+  readonly name: string;
+  readonly baseUrl: string;
+}
+export type DoomServerProviderOverrides = (context: {
+  readonly environment: Readonly<Record<string, string | undefined>>;
+}) => readonly DoomServerProviderOverride[];
+/** Read pure root metadata without initializing or mounting the root. */
+export declare function composeServerProviderOverrides(...roots: readonly unknown[]): DoomServerProviderOverrides;
+export interface DoomServerFacet {
+  readonly providerOverrides?: DoomServerProviderOverrides;
+  readonly inject?: readonly string[];
+  apply(context: Context): void | (() => void | Promise<void>) | Promise<void | (() => void | Promise<void>)>;
+}
+/** One instance belongs to one mounted server scope. */
+export interface DoomServerPluginContext {
+  readonly context: Context;
+  readonly host: DoomServerHostService;
+  readonly agent?: DoomHeadlessHostService;
+  readonly signal: AbortSignal;
+}
+export interface DoomServerMethod {
+  register(host: DoomServerHostService): DoomServerRegistration;
+}
+/** Capture schema inference before heterogeneous methods enter a contribution array. */
+export declare function defineServerMethod<TInput extends TSchema, TOutput extends TSchema>(definition: DoomPluginMethod<TInput, TOutput>, handler: (input: Static<TInput>, caller: DoomPluginCaller) => Static<TOutput> | Promise<Static<TOutput>>): DoomServerMethod;
+export interface DoomServerPluginScope {
+  readonly services?: readonly Parameters<Context['plugin']>[0][];
+  readonly channels?: readonly (() => DoomHubChannel)[];
+  readonly api?: readonly DoomApi[];
+  readonly methods?: readonly DoomServerMethod[];
+  readonly onStart?: (context: DoomServerPluginContext) => void | Promise<void>;
+  readonly onStop?: (context: DoomServerPluginContext) => void | Promise<void>;
+  readonly onDispose?: (context: DoomServerPluginContext) => void | Promise<void>;
+}
+export interface DoomServerSessionPlugin extends DoomServerPluginScope {
+  readonly tools?: readonly (DoomHeadlessTool | DoomPluginTool)[];
+  readonly commands?: readonly (DoomHeadlessCommand | DoomPluginCommand)[];
+  readonly resources?: readonly Parameters<DoomHeadlessHostService['registerResource']>[0][];
+  readonly hooks?: readonly Parameters<DoomHeadlessHostService['registerHook']>[0][];
+  readonly toolRestrictions?: readonly (DoomHeadlessToolRestriction | DoomToolRestrictionDefinition<() => DoomHeadlessToolRestriction>)[];
+  readonly activities?: readonly Parameters<DoomHeadlessHostService['registerActivity']>[0][];
+}
+type ScopeDeclaration<TScope> = TScope | ((context: DoomServerPluginContext) => TScope | Promise<TScope>);
+type NonSessionScope = DoomServerPluginScope & { readonly [K in Exclude<keyof DoomServerSessionPlugin, keyof DoomServerPluginScope>]?: never; };
+export interface DoomServerPluginDefinition {
+  readonly providerOverrides?: DoomServerProviderOverrides;
+  readonly name: string;
+  readonly inject?: readonly string[];
+  readonly global?: ScopeDeclaration<NonSessionScope>;
+  readonly workspace?: ScopeDeclaration<NonSessionScope>;
+  readonly session?: ScopeDeclaration<DoomServerSessionPlugin>;
+}
+/** One package's validated declaration. */
+export interface DeclaredServerFacet {
+  packageName: string;
+  packageDir: string;
+  /** Package-relative ./path to the source entry. */
+  entry: string;
+  /** Package-relative ./path to the built entry, which is what a host imports. */
+  dist: string;
+  /** Scopes this facet is installed into; both when the package names neither. */
+  scopes: readonly DoomApiScope[];
+  /** A selected host cannot be ready without this package's runtime capability. */
+  required?: boolean;
+}
+export declare class DoomServerFacetManifestError extends Error {
+  constructor(packageDir: string, message: string);
+}
+/** Narrows a module's default export, so a broken package is a notice rather than a crash. */
+export declare function isDoomServerFacet(value: unknown): value is DoomServerFacet;
+/**
+ * Validates one package.json's `poServer` block.
+ *
+ * `dist` is required because a host imports the built entry the package ships,
+ * never its source.
+ */
+export declare function declaredServerFacetsOf(packageDir: string, manifest: Record<string, unknown>): DeclaredServerFacet[];
+/**
+ * The deterministic order hosts install in. A package appears once: the first
+ * directory claiming a package name keeps it and the later one is dropped with
+ * a notice, so a duplicated install never installs a facet twice.
+ */
+export declare function orderServerFacets(facets: readonly DeclaredServerFacet[], onNotice?: (message: string) => void): DeclaredServerFacet[];
+//#endregion
+//# sourceMappingURL=serverFacet.d.mts.map

package/dist/src/schemas/serverFacet.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serverFacet.d.mts","names":[],"sources":["../../../src/schemas/serverFacet.ts"],"mappings":";;;;;;;;;;qBAwBa;iBAEI;;WAEN;;EAET;;;;;;;;;iBAUe;WACN,OAAO;;WAEP,SAAS;;;;;;EAMlB,YAAY,KAAK,UAAU;;EAE3B,gBAAgB,SAAS,iBAAiB;;EAE1C,eAAe,eAAe,SAAS,gBAAgB,SACrD,YAAY,iBAAiB,QAAQ,UACrC,UAAU,OAAO,OAAO,SAAS,QAAQ,qBAAqB,OAAO,WAAW,QAAQ,OAAO,YAC9F;;EAEH;;EAEA;;;YAIU;IACR,oBAAoB;;;wBAIR,mBAAmB,SAAS,UAAU;wBAItC,sBAAsB,SAAS,UAAU;;qBAO5C;;qBAGA;;;;;;;;;;;;;iBAcI;WACN;WACA;;YAEC,+BAA+B;WAChC,aAAa,SAAS;eAClB;;wBAGC,kCAAkC,4BAA4B;iBAS7D;WACN,oBAAoB;WACpB;EACT,MAAM,SAAS,+BAA+B,iBAAiB,6BAA6B;;;iBAI7E;WACN,SAAS;WACT,MAAM;WACN,QAAQ;WACR,QAAQ;;iBAGF;EACf,SAAS,MAAM,wBAAwB;;;wBAIzB,mBAAmB,eAAe,SAAS,gBAAgB,SACzE,YAAY,iBAAiB,QAAQ,UACrC,UAAU,OAAO,OAAO,SAAS,QAAQ,qBAAqB,OAAO,WAAW,QAAQ,OAAO,YAC9F;iBAIc;WACN,oBAAoB,WAAW;WAC/B,2BAA2B;WAC3B,eAAe;WACf,mBAAmB;WACnB,WAAW,SAAS,mCAAmC;WACvD,UAAU,SAAS,mCAAmC;WACtD,aAAa,SAAS,mCAAmC;;iBAGnD,gCAAgC;WACtC,kBAAkB,mBAAmB;WACrC,qBAAqB,sBAAsB;WAC3C,qBAAqB,WAAW;WAChC,iBAAiB,WAAW;WAC5B,6BACL,8BACA,oCAAoC;WAE/B,sBAAsB,WAAW;;KAGvC,iBAAiB,UAAU,WAAW,SAAS,4BAA4B,SAAS,QAAQ;KAE5F,kBAAkB,oCACX,KAAK,cAAc,+BAA+B;iBAE7C;WACN,oBAAoB;WACpB;WACA;WACA,SAAS,iBAAiB;WAC1B,YAAY,iBAAiB;WAC7B,UAAU,iBAAiB;;;iBAIrB;EACf;EACA;;EAEA;;EAEA;;EAEA,iBAAiB;;EAEjB;;qBAGW,qCAAqC;EAChD,YAAY,oBAAoB;;;wBAWlB,kBAAkB,iBAAiB,SAAS;;;;;;;wBAmC5C,uBAAuB,oBAAoB,UAAU,0BAA0B;;;;;;wBAkC/E,kBACd,iBAAiB,uBACjB,YAAW,2BACV"}

package/dist/src/schemas/serverFacet.mjs

@@ -0,0 +1,101 @@
+//#region src/schemas/serverFacet.ts
+/** The host a server facet contributes to. */
+const DOOM_SERVER_HOST_SERVICE = "doom/server-host";
+function readDoomServerHost(context) {
+	return context.get(DOOM_SERVER_HOST_SERVICE);
+}
+function requireDoomServerHost(context) {
+	const service = readDoomServerHost(context);
+	if (!service) throw new Error("The Doom server host is unavailable. Start a Doom server first.");
+	return service;
+}
+/** The package.json field a package declares its server facet under. */
+const DOOM_SERVER_FACET_MANIFEST_FIELD = "poServer";
+/** The default export a facet module must provide, so a host can install it. */
+const DOOM_SERVER_FACET_EXPORT = "default";
+/** Read pure root metadata without initializing or mounting the root. */
+function composeServerProviderOverrides(...roots) {
+	return (context) => roots.flatMap((root) => {
+		if (typeof root !== "function" && typeof root !== "object" || root === null) return [];
+		const callback = root.providerOverrides;
+		return typeof callback === "function" ? callback(context) : [];
+	});
+}
+/** Capture schema inference before heterogeneous methods enter a contribution array. */
+function defineServerMethod(definition, handler) {
+	return { register: (host) => host.registerMethod(definition, handler) };
+}
+var DoomServerFacetManifestError = class extends Error {
+	constructor(packageDir, message) {
+		super(`${DOOM_SERVER_FACET_MANIFEST_FIELD} manifest in ${packageDir}: ${message}`);
+		this.name = "DoomServerFacetManifestError";
+	}
+};
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Narrows a module's default export, so a broken package is a notice rather than a crash. */
+function isDoomServerFacet(value) {
+	return isRecord(value) && typeof value.apply === "function";
+}
+function normalizePath(packageDir, field, value) {
+	if (typeof value !== "string" || !value.startsWith("./") || value.includes("..")) throw new DoomServerFacetManifestError(packageDir, `${field} must be a package-relative ./path with no '..'.`);
+	return value;
+}
+function normalizeScopes(packageDir, value) {
+	if (value === void 0) throw new DoomServerFacetManifestError(packageDir, "scopes must be declared explicitly.");
+	if (!Array.isArray(value) || value.length === 0) throw new DoomServerFacetManifestError(packageDir, "scopes must name 'global', 'workspace', or 'session'.");
+	const scopes = [];
+	for (const scope of value) {
+		if (scope !== "session" && scope !== "global" && scope !== "workspace") throw new DoomServerFacetManifestError(packageDir, `Unknown scope '${String(scope)}'; resync for the three-level host.`);
+		if (!scopes.includes(scope)) scopes.push(scope);
+	}
+	return scopes;
+}
+/**
+* Validates one package.json's `poServer` block.
+*
+* `dist` is required because a host imports the built entry the package ships,
+* never its source.
+*/
+function declaredServerFacetsOf(packageDir, manifest) {
+	const declared = manifest[DOOM_SERVER_FACET_MANIFEST_FIELD];
+	if (declared === void 0) return [];
+	if (!isRecord(declared)) throw new DoomServerFacetManifestError(packageDir, "the block must be an object naming entry and dist.");
+	const entry = normalizePath(packageDir, "entry", declared.entry);
+	if (declared.dist === void 0) throw new DoomServerFacetManifestError(packageDir, "dist is required: a host imports the built entry the package ships, never its source.");
+	const dist = normalizePath(packageDir, "dist", declared.dist);
+	if (declared.required !== void 0 && typeof declared.required !== "boolean") throw new DoomServerFacetManifestError(packageDir, "required must be a boolean.");
+	return [{
+		packageName: typeof manifest.name === "string" ? manifest.name : packageDir,
+		packageDir,
+		entry,
+		dist,
+		scopes: normalizeScopes(packageDir, declared.scopes),
+		...typeof declared.required === "boolean" ? { required: declared.required } : {}
+	}];
+}
+/**
+* The deterministic order hosts install in. A package appears once: the first
+* directory claiming a package name keeps it and the later one is dropped with
+* a notice, so a duplicated install never installs a facet twice.
+*/
+function orderServerFacets(facets, onNotice = () => void 0) {
+	const sorted = [...facets].sort((left, right) => left.packageName.localeCompare(right.packageName) || left.packageDir.localeCompare(right.packageDir));
+	const owners = /* @__PURE__ */ new Map();
+	const kept = [];
+	for (const facet of sorted) {
+		const holder = owners.get(facet.packageName);
+		if (holder !== void 0) {
+			onNotice(`server facet '${facet.packageName}' from ${facet.packageDir} is skipped: ${holder.packageDir} already claims it.`);
+			continue;
+		}
+		owners.set(facet.packageName, facet);
+		kept.push(facet);
+	}
+	return kept;
+}
+//#endregion
+export { DOOM_SERVER_FACET_EXPORT, DOOM_SERVER_FACET_MANIFEST_FIELD, DOOM_SERVER_HOST_SERVICE, DoomServerFacetManifestError, composeServerProviderOverrides, declaredServerFacetsOf, defineServerMethod, isDoomServerFacet, orderServerFacets, readDoomServerHost, requireDoomServerHost };
+
+//# sourceMappingURL=serverFacet.mjs.map