apcore-a2a 0.5.0 → 0.7.0

package/dist/config.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Config namespace registration and resolution for `apcore-a2a`.
+ *
+ * Mirrors the Python binding's `apcore_a2a._config`. It lives in its own module
+ * rather than in `server/factory.ts` because the CLI has to read the
+ * `apcore-a2a.openapi` section *before* it builds a Registry, and therefore long
+ * before anything in the server stack is imported — pulling in the factory (and
+ * with it express and the whole A2A SDK) just to register a namespace would put
+ * the entire server on the startup path of `apcore-a2a serve --help`.
+ *
+ * Registration must happen from exactly ONE place: apcore's
+ * `Config.registerNamespace` throws `ConfigNamespaceDuplicateError` on a second
+ * call for the same name, so a second registration site would crash the process
+ * at import time rather than being ignored.
+ */
+export declare const A2A_NAMESPACE = "apcore-a2a";
+export declare const A2A_ENV_PREFIX = "APCORE_A2A";
+/** The registered namespace defaults (stable in apcore-js >= 0.22.0). */
+export declare const A2A_DEFAULTS: Record<string, unknown>;
+/**
+ * Register the `apcore-a2a` config namespace. Safe to call repeatedly.
+ *
+ * The already-registered case is detected rather than caught: swallowing every
+ * exception here would also swallow a genuine `ConfigEnvPrefixConflictError`
+ * from another package claiming `APCORE_A2A`, which is a misconfiguration the
+ * operator needs to see.
+ */
+export declare function registerA2aNamespace(): void;
+/**
+ * Resolve one `apcore-a2a` namespace setting through apcore's Config.
+ *
+ * Delegates to `Config.load` so that values from an apcore config file and
+ * `APCORE_A2A_*` environment overrides are applied by apcore itself (namespace
+ * mode), exactly like the other apcore bindings. Falls back to `fallback` when
+ * the key is unset.
+ */
+export declare function getA2aSetting(key: string, fallback?: unknown): unknown;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,eAAO,MAAM,aAAa,eAAe,CAAC;AAC1C,eAAO,MAAM,cAAc,eAAe,CAAC;AAE3C,yEAAyE;AACzE,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAoBhD,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAO3C;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,CAMtE"}

package/dist/config.js

@@ -0,0 +1,71 @@
+/**
+ * Config namespace registration and resolution for `apcore-a2a`.
+ *
+ * Mirrors the Python binding's `apcore_a2a._config`. It lives in its own module
+ * rather than in `server/factory.ts` because the CLI has to read the
+ * `apcore-a2a.openapi` section *before* it builds a Registry, and therefore long
+ * before anything in the server stack is imported — pulling in the factory (and
+ * with it express and the whole A2A SDK) just to register a namespace would put
+ * the entire server on the startup path of `apcore-a2a serve --help`.
+ *
+ * Registration must happen from exactly ONE place: apcore's
+ * `Config.registerNamespace` throws `ConfigNamespaceDuplicateError` on a second
+ * call for the same name, so a second registration site would crash the process
+ * at import time rather than being ignored.
+ */
+import { Config } from "apcore-js";
+export const A2A_NAMESPACE = "apcore-a2a";
+export const A2A_ENV_PREFIX = "APCORE_A2A";
+/** The registered namespace defaults (stable in apcore-js >= 0.22.0). */
+export const A2A_DEFAULTS = {
+    execution_timeout: 300,
+    cors_origins: [],
+    explorer: false,
+    metrics: false,
+    push_notifications: false,
+    // The OpenAPI backend's section (feature F-12) — {spec, base_url, prefix,
+    // include, exclude, include_deprecated, timeout, headers,
+    // acknowledge_unapproved_writes}. The first NESTED key in this namespace,
+    // whose five siblings are all scalars.
+    //
+    // `openapi.spec` is also the FIRST path-typed key here, and apcore 0.30.0's
+    // protections for path-typed keys do not reach it: `Config.pathTypedKeys()`
+    // is a fixed list of apcore's own five keys and never consults a namespace
+    // registered through `Config.registerNamespace` (verified against apcore
+    // 0.30.0), and the PROTOCOL_SPEC §9.2.1 requirement-5 empty-value discard is
+    // gated on that same set — so `APCORE_A2A_OPENAPI_SPEC=` would be treated as
+    // an ordinary override to `""`, a legal relative path to every filesystem
+    // API. `openapiBackend.resolveSpecLocation` owns the three rules instead.
+    openapi: null,
+};
+/**
+ * Register the `apcore-a2a` config namespace. Safe to call repeatedly.
+ *
+ * The already-registered case is detected rather than caught: swallowing every
+ * exception here would also swallow a genuine `ConfigEnvPrefixConflictError`
+ * from another package claiming `APCORE_A2A`, which is a misconfiguration the
+ * operator needs to see.
+ */
+export function registerA2aNamespace() {
+    if (Config.registeredNamespaces().some((ns) => ns.name === A2A_NAMESPACE))
+        return;
+    Config.registerNamespace({
+        name: A2A_NAMESPACE,
+        envPrefix: A2A_ENV_PREFIX,
+        defaults: A2A_DEFAULTS,
+    });
+}
+/**
+ * Resolve one `apcore-a2a` namespace setting through apcore's Config.
+ *
+ * Delegates to `Config.load` so that values from an apcore config file and
+ * `APCORE_A2A_*` environment overrides are applied by apcore itself (namespace
+ * mode), exactly like the other apcore bindings. Falls back to `fallback` when
+ * the key is unset.
+ */
+export function getA2aSetting(key, fallback) {
+    registerA2aNamespace();
+    const value = Config.load(undefined, { validate: false }).get(`${A2A_NAMESPACE}.${key}`);
+    return value === undefined || value === null ? fallback : value;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAEnC,MAAM,CAAC,MAAM,aAAa,GAAG,YAAY,CAAC;AAC1C,MAAM,CAAC,MAAM,cAAc,GAAG,YAAY,CAAC;AAE3C,yEAAyE;AACzE,MAAM,CAAC,MAAM,YAAY,GAA4B;IACnD,iBAAiB,EAAE,GAAG;IACtB,YAAY,EAAE,EAAE;IAChB,QAAQ,EAAE,KAAK;IACf,OAAO,EAAE,KAAK;IACd,kBAAkB,EAAE,KAAK;IACzB,0EAA0E;IAC1E,0DAA0D;IAC1D,0EAA0E;IAC1E,uCAAuC;IACvC,EAAE;IACF,4EAA4E;IAC5E,4EAA4E;IAC5E,2EAA2E;IAC3E,yEAAyE;IACzE,6EAA6E;IAC7E,6EAA6E;IAC7E,0EAA0E;IAC1E,0EAA0E;IAC1E,OAAO,EAAE,IAAI;CACd,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB;IAClC,IAAI,MAAM,CAAC,oBAAoB,EAAE,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,KAAK,aAAa,CAAC;QAAE,OAAO;IAClF,MAAM,CAAC,iBAAiB,CAAC;QACvB,IAAI,EAAE,aAAa;QACnB,SAAS,EAAE,cAAc;QACzB,QAAQ,EAAE,YAAY;KACvB,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW,EAAE,QAAkB;IAC3D,oBAAoB,EAAE,CAAC;IACvB,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC,GAAG,CAC3D,GAAG,aAAa,IAAI,GAAG,EAAE,CAC1B,CAAC;IACF,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC;AAClE,CAAC"}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-export declare const VERSION = "0.4.1";
+export declare const VERSION = "0.7.0";
 export { serve, asyncServe } from "./serve.js";
 export { A2AClient } from "./client/index.js";
+export { A2AClientError, A2AConnectionError, A2ADiscoveryError, A2AServerError, AccessDeniedError, ApprovalDeniedError, ApprovalTimeoutError, GovernanceRefusedError, TaskNotCancelableError, TaskNotFoundError, } from "./client/index.js";
 export type { Authenticator, ClaimMapping } from "./auth/index.js";
 export { JWTAuthenticator } from "./auth/index.js";
 export { createAuthMiddleware } from "./auth/index.js";
@@ -12,4 +13,6 @@ export { ErrorMapper } from "./adapters/index.js";
 export { PartConverter } from "./adapters/index.js";
 export { A2AServerFactory } from "./server/index.js";
 export { ApCoreAgentExecutor } from "./server/index.js";
+export { buildOpenapiBackendFromConfig, openapiBackend, projectModuleId, resolveSpecLocation, synthesizeDescription, MODULE_ID_SEGMENT, WRITE_METHODS, } from "./openapi-backend.js";
+export type { GovernanceStateLike, OpenapiBackendLogger, OpenapiBackendOptions, } from "./openapi-backend.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,UAAU,CAAC;AAG/B,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG/C,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAG9C,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGrE,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,UAAU,CAAC;AAG/B,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG/C,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,sBAAsB,EACtB,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAG3B,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGrE,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAIxD,OAAO,EACL,6BAA6B,EAC7B,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,qBAAqB,EACrB,iBAAiB,EACjB,aAAa,GACd,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -1,8 +1,9 @@
-export const VERSION = "0.4.1";
+export const VERSION = "0.7.0";
 // Public API: serve
 export { serve, asyncServe } from "./serve.js";
 // Client
 export { A2AClient } from "./client/index.js";
+export { A2AClientError, A2AConnectionError, A2ADiscoveryError, A2AServerError, AccessDeniedError, ApprovalDeniedError, ApprovalTimeoutError, GovernanceRefusedError, TaskNotCancelableError, TaskNotFoundError, } from "./client/index.js";
 export { JWTAuthenticator } from "./auth/index.js";
 export { createAuthMiddleware } from "./auth/index.js";
 export { authIdentityStore, getAuthIdentity } from "./auth/index.js";
@@ -15,4 +16,7 @@ export { PartConverter } from "./adapters/index.js";
 // Server
 export { A2AServerFactory } from "./server/index.js";
 export { ApCoreAgentExecutor } from "./server/index.js";
+// OpenAPI backend (feature F-12) — turn an OpenAPI 3.0/3.1 document into a
+// populated apcore Registry, which `serve` accepts like any other.
+export { buildOpenapiBackendFromConfig, openapiBackend, projectModuleId, resolveSpecLocation, synthesizeDescription, MODULE_ID_SEGMENT, WRITE_METHODS, } from "./openapi-backend.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAE/B,oBAAoB;AACpB,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE/C,SAAS;AACT,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAI9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAErE,WAAW;AACX,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,SAAS;AACT,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAE/B,oBAAoB;AACpB,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE/C,SAAS;AACT,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,sBAAsB,EACtB,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAI3B,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAErE,WAAW;AACX,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,SAAS;AACT,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAExD,2EAA2E;AAC3E,mEAAmE;AACnE,OAAO,EACL,6BAA6B,EAC7B,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,qBAAqB,EACrB,iBAAiB,EACjB,aAAa,GACd,MAAM,sBAAsB,CAAC"}

package/dist/openapi-backend.d.ts

@@ -0,0 +1,203 @@
+/**
+ * OpenAPI backend — serve an OpenAPI 3.0/3.1 document as A2A Skills.
+ *
+ * Pipeline:
+ *
+ *     loadSpec -> OpenAPIScanner.scan -> [repair] -> HTTPProxyRegistryWriter.write -> Registry
+ *
+ * The scanner and the writer live in apcore-toolkit; this module composes them
+ * and adds the two repairs the composition needs, neither of which the toolkit
+ * can make on its own:
+ *
+ * - **FR-OAS-002 module-ID projection.** The toolkit sanitizes a derived ID into
+ *   `[A-Za-z0-9_.-]`; apcore's registry accepts only
+ *   `^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$`. Without the projection the canonical
+ *   Swagger Petstore scans cleanly and registers nothing — the server starts and
+ *   serves an Agent Card with zero skills, and nothing in the path raises.
+ * - **FR-OAS-003 description repair.** An operation with neither `summary` nor
+ *   `description` yields `""`, and `AgentCardBuilder` skips a module whose
+ *   description is empty — so the operation would vanish from the Agent Card with
+ *   no diagnostic.
+ *
+ * See `apcore-a2a/docs/features/openapi-backend.md` for the specification and
+ * `conformance/fixtures/openapi_backend.json` for the shared contract.
+ */
+import { Registry } from "apcore-js";
+import { type ScannedModule } from "apcore-toolkit";
+/**
+ * One dot-separated segment of an apcore-legal module ID. apcore enforces
+ * `^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$` at `Registry.register` and again at
+ * `Executor.call`; a segment may not begin with a digit, which is why some
+ * derived IDs cannot be repaired at all.
+ */
+export declare const MODULE_ID_SEGMENT: RegExp;
+/** HTTP methods that change state. The population FR-OAS-005 warns about. */
+export declare const WRITE_METHODS: ReadonlySet<string>;
+/**
+ * The diagnostics sink.
+ *
+ * Injectable rather than hard-wired to `console` for two reasons: a host that
+ * already owns a logger should not have this module writing past it, and the
+ * conformance driver asserts the *text* of the FR-OAS-002 / FR-OAS-003 /
+ * FR-OAS-005 diagnostics, which it cannot do against an unaddressable sink.
+ */
+export interface OpenapiBackendLogger {
+    warn(message: string): void;
+    error(message: string): void;
+    info(message: string): void;
+}
+/**
+ * The fragment of apcore's `GovernanceState` this module reads.
+ *
+ * Both naming conventions are accepted so a duck-typed object from a test or a
+ * host framework works alongside apcore's own camelCase record.
+ */
+export interface GovernanceStateLike {
+    readonly builtinApprovalGateWired?: boolean;
+    readonly builtin_approval_gate_wired?: boolean;
+}
+/** Options for {@link openapiBackend}. */
+export interface OpenapiBackendOptions {
+    /** Where proxied requests go. Defaults to the document's `servers[0].url`. */
+    baseUrl?: string;
+    /** `basePathPrefix` — prepended to every derived module ID. */
+    prefix?: string;
+    /** Scanner include filter (regex over module IDs). */
+    include?: string;
+    /** Scanner exclude filter (regex over module IDs). */
+    exclude?: string;
+    /** When `false`, operations marked `deprecated: true` are skipped. Default `true`. */
+    includeDeprecated?: boolean;
+    /**
+     * Headers for the **spec fetch only**. Never forwarded to proxied calls, and
+     * never logged: a document is often public while the API behind it is not.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Spec-fetch timeout in **SECONDS** — never the per-call proxy timeout.
+     *
+     * apcore-toolkit's `loadSpec` takes milliseconds (default `30_000`), so this
+     * value is multiplied by 1000 at the call site. The Config Bus key is seconds
+     * in all three SDKs; passing it straight through would turn a documented
+     * `timeout: 30` into a 30 ms fetch timeout.
+     */
+    timeout?: number;
+    /** Passed to `HTTPProxyRegistryWriter` — the per-request credential hook. */
+    authHeaderFactory?: () => Record<string, string>;
+    /** Write into this registry instead of a fresh one. */
+    registry?: Registry;
+    /** True when an extensions directory (or another source) also populates the registry. */
+    hasOtherBackendSource?: boolean;
+    /** The base a relative `spec` resolves against (FR-OAS-004 rule 3). */
+    projectRoot?: string;
+    /** Records an explicit operator decision, suppressing FR-OAS-005's warning. */
+    acknowledgeUnapprovedWrites?: boolean;
+    /** Consulted only to word FR-OAS-005's warning; never to suppress it. */
+    governanceState?: GovernanceStateLike | null;
+    /** Scanner hook: patch an operation before extraction. */
+    transformOperation?: (p: string, method: string, operation: Record<string, unknown>) => Record<string, unknown> | null;
+    /**
+     * Caller hook: adjust the finished module. Runs **first**, before the
+     * description repair and the ID projection, so the invariants those two hold
+     * are unconditional whatever this returns.
+     */
+    transformModule?: (module: ScannedModule) => ScannedModule | null;
+    /** Scanner hook: override the naming algorithm. */
+    deriveModuleId?: (p: string, method: string, operation: Record<string, unknown>) => string | null;
+    /** Diagnostics sink. Defaults to `console`. */
+    logger?: Partial<OpenapiBackendLogger>;
+}
+/**
+ * Project a toolkit-derived module ID into apcore's registry alphabet.
+ *
+ * Lowercase, then `-` -> `_`. Returns `null` when the result still has a segment
+ * apcore would reject — such an ID cannot be repaired without *inventing* a
+ * character, which is a naming decision belonging to the operator's own hook
+ * rather than to a silent default. The module is dropped and reported by the
+ * caller.
+ */
+export declare function projectModuleId(moduleId: string): string | null;
+/** The minimum surface {@link synthesizeDescription} reads off a scanned module. */
+export interface DescribableModule {
+    readonly moduleId?: string;
+    readonly metadata?: Record<string, unknown> | null;
+}
+/**
+ * Build a `{METHOD} {path}` description for an undocumented operation.
+ *
+ * Uses the `http_method` / `url_path` metadata keys `HTTPProxyRegistryWriter`
+ * already requires, so the value is factual and stable across scans of the same
+ * document. Deliberately terse so it reads as a placeholder rather than as
+ * documentation.
+ */
+export declare function synthesizeDescription(module: DescribableModule): string;
+/**
+ * The base a relative `spec` resolves against (FR-OAS-004 rule 3).
+ *
+ * `Config.projectRoot` is apcore 0.30.0's public accessor. It reports a base and
+ * applies nothing, which is exactly the division of labour this key needs: the
+ * adapter owns the resolution because `Config.pathTypedKeys()` never reaches a
+ * consumer namespace.
+ */
+export declare function resolveProjectRoot(explicit?: string | null): string;
+/**
+ * Resolve `apcore-a2a.openapi.spec` (FR-OAS-004).
+ *
+ * apcore 0.30.0 declared the closed set of path-typed configuration keys and the
+ * base a relative one resolves against, but `Config.pathTypedKeys()` is a fixed
+ * list of apcore's own keys and never consults a namespace registered through
+ * `Config.registerNamespace` — verified against apcore 0.30.0. The §9.2.1
+ * requirement-5 empty-value discard is gated on that same set, so
+ * `APCORE_A2A_OPENAPI_SPEC=` would otherwise become an ordinary override to `""`,
+ * a legal relative path to every filesystem API and never the one an operator
+ * meant. This binding therefore owns the three rules rather than inheriting them.
+ *
+ * 1. A value beginning `http://` / `https://` is a URL, used verbatim — never
+ *    path-resolved, never made absolute.
+ * 2. A set-but-empty value is discarded with a WARNING and the caller falls
+ *    through to the next configuration tier. It is never joined to a base, which
+ *    would silently yield the project root.
+ * 3. A relative path resolves against `Config.projectRoot` — not the process CWD,
+ *    and not the document's own directory.
+ *
+ * @returns the URL unchanged, an absolute path, the already-parsed document, or
+ *   `null` when the value was empty and the caller should fall through.
+ */
+export declare function resolveSpecLocation(spec: unknown, options?: {
+    projectRoot?: string | null;
+    logger?: {
+        warn(message: string): void;
+    };
+}): unknown;
+/**
+ * Build an apcore `Registry` from an OpenAPI 3.0/3.1 document.
+ *
+ * `spec` is a URL, a filesystem path (resolved per FR-OAS-004), or an
+ * already-parsed document object. `timeout` is the **spec-fetch** timeout in
+ * seconds, never the per-call proxy timeout — the two are different concerns.
+ *
+ * Never returns a partially-populated registry: the collision preflight and
+ * every validation run before the first write.
+ */
+export declare function openapiBackend(spec: unknown, options?: OpenapiBackendOptions): Promise<Registry>;
+/**
+ * Build the backend from an `apcore-a2a.openapi` Config Bus section.
+ *
+ * The raw Config Bus value is a plain object (from `apcore.yaml` or
+ * `APCORE_A2A_OPENAPI_*` env vars) in snake_case, not the camelCase options
+ * {@link openapiBackend} takes, so this is the one place that translates between
+ * them.
+ *
+ * Returns `null` when the section is absent or falsy, so a caller can treat "no
+ * OpenAPI configured" as an ordinary outcome.
+ *
+ * `authHeaderFactory` is deliberately not read from the section: it is a
+ * callable, and a value sourced from YAML/JSON/env can never carry one.
+ */
+export declare function buildOpenapiBackendFromConfig(openapiConfig: unknown, options?: {
+    registry?: Registry;
+    hasOtherBackendSource?: boolean;
+    governanceState?: GovernanceStateLike | null;
+    logger?: Partial<OpenapiBackendLogger>;
+}): Promise<Registry | null>;
+//# sourceMappingURL=openapi-backend.d.ts.map

package/dist/openapi-backend.d.ts.map

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