@ankhorage/data-sources 2.0.4 → 2.0.5

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @ankhorage/data-sources
 
+## 2.0.5
+
+### Patch Changes
+
+- 43264ba: Scope OpenAPI documents discovered at a shared origin root to the service path requested by the caller.
+
 ## 2.0.4
 
 ### Patch Changes

package/dist/discovery/index.d.ts

@@ -58,7 +58,10 @@ export type IntrospectGraphQlApiResult = {
     readonly diagnostics: readonly DataSourceDiagnostic[];
     readonly status?: number;
 };
+/*** Creates the ordered, deduplicated URLs probed during OpenAPI discovery. */
 export declare function createOpenApiDiscoveryCandidates(rawUrl: string, conventionalPaths?: readonly string[]): readonly string[];
+/*** Discovers and imports an OpenAPI document while preserving the requested service boundary. */
 export declare function discoverOpenApi(input: DiscoverOpenApiInput): Promise<DiscoverOpenApiResult>;
+/*** Introspects a GraphQL endpoint and normalizes its schema into the canonical API definition. */
 export declare function introspectGraphQlApi(input: IntrospectGraphQlApiInput): Promise<IntrospectGraphQlApiResult>;
 //# sourceMappingURL=index.d.ts.map

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

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

package/dist/discovery/index.js

@@ -1,36 +1,29 @@
 import { createGraphQlApi, createGraphQlIntrospectionRequest, } from '../graphql';
 import { importOpenApiDocument } from '../openapi';
 import { isSuccessfulStatus, normalizeCandidateUrl, parseHttpUrl, parseJsonResponse, readRecord, } from './http';
+import { createOpenApiDiscoveryPlan } from './openapiDiscoveryPlan';
+import { scopeOpenApiDocument } from './scopeOpenApiDocument';
 export const DEFAULT_OPENAPI_DISCOVERY_PATHS = [
     'openapi.json',
     'swagger.json',
     'api/openapi.json',
     'v3/api-docs',
 ];
+/*** Creates the ordered, deduplicated URLs probed during OpenAPI discovery. */
 export function createOpenApiDiscoveryCandidates(rawUrl, conventionalPaths = DEFAULT_OPENAPI_DISCOVERY_PATHS) {
-    const parsed = parseHttpUrl(rawUrl);
-    if (parsed === undefined)
-        return [];
-    const exact = normalizeCandidateUrl(parsed);
-    const serviceBase = new URL(exact);
-    if (!serviceBase.pathname.endsWith('/'))
-        serviceBase.pathname = `${serviceBase.pathname}/`;
-    const candidates = [exact];
-    for (const path of conventionalPaths) {
-        const normalizedPath = path.replace(/^\/+/, '');
-        candidates.push(normalizeCandidateUrl(new URL(normalizedPath, serviceBase)));
-        candidates.push(normalizeCandidateUrl(new URL(normalizedPath, `${parsed.origin}/`)));
-    }
-    return [...new Set(candidates)];
+    return createOpenApiDiscoveryPlan(rawUrl, conventionalPaths).candidates.map((candidate) => candidate.url);
 }
+/*** Discovers and imports an OpenAPI document while preserving the requested service boundary. */
 export async function discoverOpenApi(input) {
-    const candidates = createOpenApiDiscoveryCandidates(input.url, input.conventionalPaths);
-    if (candidates.length === 0) {
+    const conventionalPaths = input.conventionalPaths ?? DEFAULT_OPENAPI_DISCOVERY_PATHS;
+    const plan = createOpenApiDiscoveryPlan(input.url, conventionalPaths);
+    if (plan.candidates.length === 0) {
         return discoveryFailure(input.id, [], 'OpenAPI discovery requires a valid HTTP or HTTPS URL.');
     }
     const attempts = [];
-    for (const candidate of candidates) {
-        const probed = await probeOpenApiCandidate(input, candidate);
+    for (const candidate of plan.candidates) {
+        const requestedScope = candidate.scopeToRequestedService ? plan.requestedScope : undefined;
+        const probed = await probeOpenApiCandidate(input, candidate.url, requestedScope);
         attempts.push(probed.attempt);
         if (probed.result === undefined)
             continue;
@@ -38,7 +31,7 @@ export async function discoverOpenApi(input) {
             ? {
                 ok: true,
                 data: probed.result.data,
-                documentUrl: candidate,
+                documentUrl: candidate.url,
                 attempts,
                 diagnostics: probed.result.diagnostics ?? [],
             }
@@ -46,6 +39,7 @@ export async function discoverOpenApi(input) {
     }
     return discoveryFailure(input.id, attempts, 'No supported OpenAPI document was found at the supplied URL or conventional locations.');
 }
+/*** Introspects a GraphQL endpoint and normalizes its schema into the canonical API definition. */
 export async function introspectGraphQlApi(input) {
     const endpoint = parseHttpUrl(input.endpointUrl);
     if (endpoint === undefined) {
@@ -80,6 +74,7 @@ export async function introspectGraphQlApi(input) {
         ? { ok: true, data: result.data, diagnostics: result.diagnostics ?? [] }
         : { ok: false, diagnostics: result.diagnostics };
 }
+/*** Fetches GraphQL introspection without exposing transport failures beyond the discovery boundary. */
 async function fetchGraphQlIntrospection(input, endpoint) {
     try {
         return await input.fetch(normalizeCandidateUrl(endpoint), {
@@ -96,7 +91,8 @@ async function fetchGraphQlIntrospection(input, endpoint) {
         return undefined;
     }
 }
-async function probeOpenApiCandidate(input, candidate) {
+/*** Probes one OpenAPI candidate and scopes origin-root documents before canonical import. */
+async function probeOpenApiCandidate(input, candidate, requestedScope) {
     let response;
     try {
         response = await input.fetch(candidate, {
@@ -119,16 +115,7 @@ async function probeOpenApiCandidate(input, candidate) {
             attempt: { url: candidate, outcome: 'unsupported-document', status: response.status },
         };
     }
-    const result = importOpenApiDocument({
-        id: input.id,
-        document: parsed,
-        baseUrl: input.baseUrl,
-        credential: input.credential,
-        documentUrl: candidate,
-        name: input.name,
-        description: input.description,
-        metadata: input.metadata,
-    });
+    const result = importOpenApiCandidate(input, candidate, parsed, requestedScope);
     return {
         attempt: {
             url: candidate,
@@ -138,12 +125,35 @@ async function probeOpenApiCandidate(input, candidate) {
         result,
     };
 }
+/*** Applies service scoping and imports one validated OpenAPI candidate. */
+function importOpenApiCandidate(input, candidate, parsed, requestedScope) {
+    let document = parsed;
+    if (requestedScope !== undefined) {
+        const scoped = scopeOpenApiDocument(parsed, input.id, requestedScope, candidate);
+        if (!scoped.ok)
+            return { ok: false, diagnostics: [scoped.diagnostic] };
+        const { document: scopedDocument } = scoped;
+        document = scopedDocument;
+    }
+    return importOpenApiDocument({
+        id: input.id,
+        document,
+        baseUrl: input.baseUrl,
+        credential: input.credential,
+        documentUrl: candidate,
+        name: input.name,
+        description: input.description,
+        metadata: input.metadata,
+    });
+}
+/*** Checks whether parsed JSON has the minimal OpenAPI document shape required for import. */
 function isOpenApiDocument(value) {
     const record = readRecord(value);
     return (record !== undefined &&
         typeof record.openapi === 'string' &&
         readRecord(record.paths) !== undefined);
 }
+/*** Reads a GraphQL introspection schema from a parsed response payload. */
 function readGraphQlIntrospection(value) {
     const payload = readRecord(value);
     const data = readRecord(payload?.data);
@@ -151,6 +161,7 @@ function readGraphQlIntrospection(value) {
         return undefined;
     return data;
 }
+/*** Builds a canonical OpenAPI discovery failure with safe diagnostics. */
 function discoveryFailure(apiId, attempts, message) {
     return {
         ok: false,
@@ -158,6 +169,7 @@ function discoveryFailure(apiId, attempts, message) {
         diagnostics: [{ code: 'missing-schema', apiId, message, severity: 'error' }],
     };
 }
+/*** Builds a canonical GraphQL introspection failure with API identity. */
 function graphqlFailure(apiId, message, code = 'invalid-config') {
     return {
         ok: false,

package/dist/discovery/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/discovery/index.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  CredentialRef,\n  DataContractValue,\n  DataSourceDiagnostic,\n  ExternalGraphQlApiDefinition,\n  ExternalRestApiDefinition,\n} from '@ankhorage/contracts/data';\n\nimport {\n  createGraphQlApi,\n  createGraphQlIntrospectionRequest,\n  type GraphQlIntrospectionResult,\n} from '../graphql';\nimport { importOpenApiDocument, type OpenApiDocumentObject } from '../openapi';\nimport {\n  isSuccessfulStatus,\n  normalizeCandidateUrl,\n  parseHttpUrl,\n  parseJsonResponse,\n  readRecord,\n} from './http';\n\nexport const DEFAULT_OPENAPI_DISCOVERY_PATHS = [\n  'openapi.json',\n  'swagger.json',\n  'api/openapi.json',\n  'v3/api-docs',\n] as const;\n\nexport interface ExternalApiFetchInit {\n  readonly method: 'GET' | 'POST';\n  readonly headers: Readonly<Record<string, string>>;\n  readonly body?: string;\n}\n\nexport interface ExternalApiFetchResponse {\n  readonly status: number;\n  text(): Promise<string>;\n}\n\nexport type ExternalApiFetch = (\n  url: string,\n  init: ExternalApiFetchInit,\n) => Promise<ExternalApiFetchResponse>;\n\nexport type OpenApiDiscoveryAttemptOutcome =\n  | 'http-error'\n  | 'invalid-document'\n  | 'matched'\n  | 'network-error'\n  | 'parse-error'\n  | 'unsupported-document';\n\nexport interface OpenApiDiscoveryAttempt {\n  readonly url: string;\n  readonly outcome: OpenApiDiscoveryAttemptOutcome;\n  readonly status?: number;\n}\n\nexport interface DiscoverOpenApiInput {\n  readonly id: string;\n  readonly url: string;\n  readonly fetch: ExternalApiFetch;\n  readonly baseUrl?: string;\n  readonly credential?: CredentialRef;\n  readonly name?: string;\n  readonly description?: string;\n  readonly metadata?: DataContractValue;\n  readonly conventionalPaths?: readonly string[];\n}\n\nexport type DiscoverOpenApiResult =\n  | {\n      readonly ok: true;\n      readonly data: ExternalRestApiDefinition;\n      readonly documentUrl: string;\n      readonly attempts: readonly OpenApiDiscoveryAttempt[];\n      readonly diagnostics: readonly DataSourceDiagnostic[];\n    }\n  | {\n      readonly ok: false;\n      readonly attempts: readonly OpenApiDiscoveryAttempt[];\n      readonly diagnostics: readonly DataSourceDiagnostic[];\n    };\n\nexport interface IntrospectGraphQlApiInput {\n  readonly id: string;\n  readonly endpointUrl: string;\n  readonly fetch: ExternalApiFetch;\n  readonly headers?: Readonly<Record<string, string>>;\n  readonly credential?: CredentialRef;\n  readonly name?: string;\n  readonly description?: string;\n  readonly schemaVersion?: string;\n  readonly metadata?: DataContractValue;\n}\n\nexport type IntrospectGraphQlApiResult =\n  | {\n      readonly ok: true;\n      readonly data: ExternalGraphQlApiDefinition;\n      readonly diagnostics: readonly DataSourceDiagnostic[];\n    }\n  | {\n      readonly ok: false;\n      readonly diagnostics: readonly DataSourceDiagnostic[];\n      readonly status?: number;\n    };\n\nexport function createOpenApiDiscoveryCandidates(\n  rawUrl: string,\n  conventionalPaths: readonly string[] = DEFAULT_OPENAPI_DISCOVERY_PATHS,\n): readonly string[] {\n  const parsed = parseHttpUrl(rawUrl);\n  if (parsed === undefined) return [];\n\n  const exact = normalizeCandidateUrl(parsed);\n  const serviceBase = new URL(exact);\n  if (!serviceBase.pathname.endsWith('/')) serviceBase.pathname = `${serviceBase.pathname}/`;\n\n  const candidates = [exact];\n  for (const path of conventionalPaths) {\n    const normalizedPath = path.replace(/^\\/+/, '');\n    candidates.push(normalizeCandidateUrl(new URL(normalizedPath, serviceBase)));\n    candidates.push(normalizeCandidateUrl(new URL(normalizedPath, `${parsed.origin}/`)));\n  }\n\n  return [...new Set(candidates)];\n}\n\nexport async function discoverOpenApi(input: DiscoverOpenApiInput): Promise<DiscoverOpenApiResult> {\n  const candidates = createOpenApiDiscoveryCandidates(input.url, input.conventionalPaths);\n  if (candidates.length === 0) {\n    return discoveryFailure(input.id, [], 'OpenAPI discovery requires a valid HTTP or HTTPS URL.');\n  }\n\n  const attempts: OpenApiDiscoveryAttempt[] = [];\n  for (const candidate of candidates) {\n    const probed = await probeOpenApiCandidate(input, candidate);\n    attempts.push(probed.attempt);\n    if (probed.result === undefined) continue;\n    return probed.result.ok\n      ? {\n          ok: true,\n          data: probed.result.data,\n          documentUrl: candidate,\n          attempts,\n          diagnostics: probed.result.diagnostics ?? [],\n        }\n      : { ok: false, attempts, diagnostics: probed.result.diagnostics };\n  }\n\n  return discoveryFailure(\n    input.id,\n    attempts,\n    'No supported OpenAPI document was found at the supplied URL or conventional locations.',\n  );\n}\n\nexport async function introspectGraphQlApi(\n  input: IntrospectGraphQlApiInput,\n): Promise<IntrospectGraphQlApiResult> {\n  const endpoint = parseHttpUrl(input.endpointUrl);\n  if (endpoint === undefined) {\n    return graphqlFailure(input.id, 'GraphQL introspection requires a valid HTTP or HTTPS URL.');\n  }\n\n  const response = await fetchGraphQlIntrospection(input, endpoint);\n  if (response === undefined) {\n    return graphqlFailure(input.id, 'GraphQL introspection request failed.', 'network-error');\n  }\n  if (!isSuccessfulStatus(response.status)) {\n    return {\n      ...graphqlFailure(\n        input.id,\n        `GraphQL introspection returned HTTP status ${response.status}.`,\n        'network-error',\n      ),\n      status: response.status,\n    };\n  }\n\n  const introspection = readGraphQlIntrospection(await parseJsonResponse(response));\n  if (introspection === undefined) {\n    return graphqlFailure(\n      input.id,\n      'GraphQL introspection response did not contain data.__schema.',\n      'parse-error',\n    );\n  }\n\n  const result = createGraphQlApi({\n    id: input.id,\n    endpointUrl: normalizeCandidateUrl(endpoint),\n    credential: input.credential,\n    name: input.name,\n    description: input.description,\n    introspection,\n    introspectionEnabled: true,\n    schemaVersion: input.schemaVersion,\n    metadata: input.metadata,\n  });\n  return result.ok\n    ? { ok: true, data: result.data, diagnostics: result.diagnostics ?? [] }\n    : { ok: false, diagnostics: result.diagnostics };\n}\n\nasync function fetchGraphQlIntrospection(\n  input: IntrospectGraphQlApiInput,\n  endpoint: URL,\n): Promise<ExternalApiFetchResponse | undefined> {\n  try {\n    return await input.fetch(normalizeCandidateUrl(endpoint), {\n      method: 'POST',\n      headers: {\n        accept: 'application/json',\n        'content-type': 'application/json',\n        ...(input.headers ?? {}),\n      },\n      body: JSON.stringify(createGraphQlIntrospectionRequest()),\n    });\n  } catch {\n    return undefined;\n  }\n}\n\ninterface OpenApiProbeResult {\n  readonly attempt: OpenApiDiscoveryAttempt;\n  readonly result?: ReturnType<typeof importOpenApiDocument>;\n}\n\nasync function probeOpenApiCandidate(\n  input: DiscoverOpenApiInput,\n  candidate: string,\n): Promise<OpenApiProbeResult> {\n  let response: ExternalApiFetchResponse;\n  try {\n    response = await input.fetch(candidate, {\n      method: 'GET',\n      headers: { accept: 'application/json, application/vnd.oai.openapi+json' },\n    });\n  } catch {\n    return { attempt: { url: candidate, outcome: 'network-error' } };\n  }\n\n  if (!isSuccessfulStatus(response.status)) {\n    return { attempt: { url: candidate, outcome: 'http-error', status: response.status } };\n  }\n\n  const parsed = await parseJsonResponse(response);\n  if (parsed === undefined) {\n    return { attempt: { url: candidate, outcome: 'parse-error', status: response.status } };\n  }\n  if (!isOpenApiDocument(parsed)) {\n    return {\n      attempt: { url: candidate, outcome: 'unsupported-document', status: response.status },\n    };\n  }\n\n  const result = importOpenApiDocument({\n    id: input.id,\n    document: parsed,\n    baseUrl: input.baseUrl,\n    credential: input.credential,\n    documentUrl: candidate,\n    name: input.name,\n    description: input.description,\n    metadata: input.metadata,\n  });\n  return {\n    attempt: {\n      url: candidate,\n      outcome: result.ok ? 'matched' : 'invalid-document',\n      status: response.status,\n    },\n    result,\n  };\n}\n\nfunction isOpenApiDocument(value: unknown): value is OpenApiDocumentObject {\n  const record = readRecord(value);\n  return (\n    record !== undefined &&\n    typeof record.openapi === 'string' &&\n    readRecord(record.paths) !== undefined\n  );\n}\n\nfunction readGraphQlIntrospection(value: unknown): GraphQlIntrospectionResult | undefined {\n  const payload = readRecord(value);\n  const data = readRecord(payload?.data);\n  if (readRecord(data?.__schema) === undefined) return undefined;\n  return data;\n}\n\nfunction discoveryFailure(\n  apiId: string,\n  attempts: readonly OpenApiDiscoveryAttempt[],\n  message: string,\n): DiscoverOpenApiResult {\n  return {\n    ok: false,\n    attempts,\n    diagnostics: [{ code: 'missing-schema', apiId, message, severity: 'error' }],\n  };\n}\n\nfunction graphqlFailure(\n  apiId: string,\n  message: string,\n  code: DataSourceDiagnostic['code'] = 'invalid-config',\n): Extract<IntrospectGraphQlApiResult, { readonly ok: false }> {\n  return {\n    ok: false,\n    diagnostics: [{ code, apiId, message, severity: 'error' }],\n  };\n}\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/discovery/index.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  CredentialRef,\n  DataContractValue,\n  DataSourceDiagnostic,\n  ExternalGraphQlApiDefinition,\n  ExternalRestApiDefinition,\n} from '@ankhorage/contracts/data';\n\nimport {\n  createGraphQlApi,\n  createGraphQlIntrospectionRequest,\n  type GraphQlIntrospectionResult,\n} from '../graphql';\nimport { importOpenApiDocument, type OpenApiDocumentObject } from '../openapi';\nimport {\n  isSuccessfulStatus,\n  normalizeCandidateUrl,\n  parseHttpUrl,\n  parseJsonResponse,\n  readRecord,\n} from './http';\nimport { createOpenApiDiscoveryPlan } from './openapiDiscoveryPlan';\nimport { scopeOpenApiDocument } from './scopeOpenApiDocument';\n\nexport const DEFAULT_OPENAPI_DISCOVERY_PATHS = [\n  'openapi.json',\n  'swagger.json',\n  'api/openapi.json',\n  'v3/api-docs',\n] as const;\n\nexport interface ExternalApiFetchInit {\n  readonly method: 'GET' | 'POST';\n  readonly headers: Readonly<Record<string, string>>;\n  readonly body?: string;\n}\n\nexport interface ExternalApiFetchResponse {\n  readonly status: number;\n  text(): Promise<string>;\n}\n\nexport type ExternalApiFetch = (\n  url: string,\n  init: ExternalApiFetchInit,\n) => Promise<ExternalApiFetchResponse>;\n\nexport type OpenApiDiscoveryAttemptOutcome =\n  | 'http-error'\n  | 'invalid-document'\n  | 'matched'\n  | 'network-error'\n  | 'parse-error'\n  | 'unsupported-document';\n\nexport interface OpenApiDiscoveryAttempt {\n  readonly url: string;\n  readonly outcome: OpenApiDiscoveryAttemptOutcome;\n  readonly status?: number;\n}\n\nexport interface DiscoverOpenApiInput {\n  readonly id: string;\n  readonly url: string;\n  readonly fetch: ExternalApiFetch;\n  readonly baseUrl?: string;\n  readonly credential?: CredentialRef;\n  readonly name?: string;\n  readonly description?: string;\n  readonly metadata?: DataContractValue;\n  readonly conventionalPaths?: readonly string[];\n}\n\nexport type DiscoverOpenApiResult =\n  | {\n      readonly ok: true;\n      readonly data: ExternalRestApiDefinition;\n      readonly documentUrl: string;\n      readonly attempts: readonly OpenApiDiscoveryAttempt[];\n      readonly diagnostics: readonly DataSourceDiagnostic[];\n    }\n  | {\n      readonly ok: false;\n      readonly attempts: readonly OpenApiDiscoveryAttempt[];\n      readonly diagnostics: readonly DataSourceDiagnostic[];\n    };\n\nexport interface IntrospectGraphQlApiInput {\n  readonly id: string;\n  readonly endpointUrl: string;\n  readonly fetch: ExternalApiFetch;\n  readonly headers?: Readonly<Record<string, string>>;\n  readonly credential?: CredentialRef;\n  readonly name?: string;\n  readonly description?: string;\n  readonly schemaVersion?: string;\n  readonly metadata?: DataContractValue;\n}\n\nexport type IntrospectGraphQlApiResult =\n  | {\n      readonly ok: true;\n      readonly data: ExternalGraphQlApiDefinition;\n      readonly diagnostics: readonly DataSourceDiagnostic[];\n    }\n  | {\n      readonly ok: false;\n      readonly diagnostics: readonly DataSourceDiagnostic[];\n      readonly status?: number;\n    };\n\n/*** Creates the ordered, deduplicated URLs probed during OpenAPI discovery. */\nexport function createOpenApiDiscoveryCandidates(\n  rawUrl: string,\n  conventionalPaths: readonly string[] = DEFAULT_OPENAPI_DISCOVERY_PATHS,\n): readonly string[] {\n  return createOpenApiDiscoveryPlan(rawUrl, conventionalPaths).candidates.map(\n    (candidate) => candidate.url,\n  );\n}\n\n/*** Discovers and imports an OpenAPI document while preserving the requested service boundary. */\nexport async function discoverOpenApi(input: DiscoverOpenApiInput): Promise<DiscoverOpenApiResult> {\n  const conventionalPaths = input.conventionalPaths ?? DEFAULT_OPENAPI_DISCOVERY_PATHS;\n  const plan = createOpenApiDiscoveryPlan(input.url, conventionalPaths);\n  if (plan.candidates.length === 0) {\n    return discoveryFailure(input.id, [], 'OpenAPI discovery requires a valid HTTP or HTTPS URL.');\n  }\n\n  const attempts: OpenApiDiscoveryAttempt[] = [];\n  for (const candidate of plan.candidates) {\n    const requestedScope = candidate.scopeToRequestedService ? plan.requestedScope : undefined;\n    const probed = await probeOpenApiCandidate(input, candidate.url, requestedScope);\n    attempts.push(probed.attempt);\n    if (probed.result === undefined) continue;\n    return probed.result.ok\n      ? {\n          ok: true,\n          data: probed.result.data,\n          documentUrl: candidate.url,\n          attempts,\n          diagnostics: probed.result.diagnostics ?? [],\n        }\n      : { ok: false, attempts, diagnostics: probed.result.diagnostics };\n  }\n\n  return discoveryFailure(\n    input.id,\n    attempts,\n    'No supported OpenAPI document was found at the supplied URL or conventional locations.',\n  );\n}\n\n/*** Introspects a GraphQL endpoint and normalizes its schema into the canonical API definition. */\nexport async function introspectGraphQlApi(\n  input: IntrospectGraphQlApiInput,\n): Promise<IntrospectGraphQlApiResult> {\n  const endpoint = parseHttpUrl(input.endpointUrl);\n  if (endpoint === undefined) {\n    return graphqlFailure(input.id, 'GraphQL introspection requires a valid HTTP or HTTPS URL.');\n  }\n\n  const response = await fetchGraphQlIntrospection(input, endpoint);\n  if (response === undefined) {\n    return graphqlFailure(input.id, 'GraphQL introspection request failed.', 'network-error');\n  }\n  if (!isSuccessfulStatus(response.status)) {\n    return {\n      ...graphqlFailure(\n        input.id,\n        `GraphQL introspection returned HTTP status ${response.status}.`,\n        'network-error',\n      ),\n      status: response.status,\n    };\n  }\n\n  const introspection = readGraphQlIntrospection(await parseJsonResponse(response));\n  if (introspection === undefined) {\n    return graphqlFailure(\n      input.id,\n      'GraphQL introspection response did not contain data.__schema.',\n      'parse-error',\n    );\n  }\n\n  const result = createGraphQlApi({\n    id: input.id,\n    endpointUrl: normalizeCandidateUrl(endpoint),\n    credential: input.credential,\n    name: input.name,\n    description: input.description,\n    introspection,\n    introspectionEnabled: true,\n    schemaVersion: input.schemaVersion,\n    metadata: input.metadata,\n  });\n  return result.ok\n    ? { ok: true, data: result.data, diagnostics: result.diagnostics ?? [] }\n    : { ok: false, diagnostics: result.diagnostics };\n}\n\n/*** Fetches GraphQL introspection without exposing transport failures beyond the discovery boundary. */\nasync function fetchGraphQlIntrospection(\n  input: IntrospectGraphQlApiInput,\n  endpoint: URL,\n): Promise<ExternalApiFetchResponse | undefined> {\n  try {\n    return await input.fetch(normalizeCandidateUrl(endpoint), {\n      method: 'POST',\n      headers: {\n        accept: 'application/json',\n        'content-type': 'application/json',\n        ...(input.headers ?? {}),\n      },\n      body: JSON.stringify(createGraphQlIntrospectionRequest()),\n    });\n  } catch {\n    return undefined;\n  }\n}\n\ninterface OpenApiProbeResult {\n  readonly attempt: OpenApiDiscoveryAttempt;\n  readonly result?: ReturnType<typeof importOpenApiDocument>;\n}\n\n/*** Probes one OpenAPI candidate and scopes origin-root documents before canonical import. */\nasync function probeOpenApiCandidate(\n  input: DiscoverOpenApiInput,\n  candidate: string,\n  requestedScope: string | undefined,\n): Promise<OpenApiProbeResult> {\n  let response: ExternalApiFetchResponse;\n  try {\n    response = await input.fetch(candidate, {\n      method: 'GET',\n      headers: { accept: 'application/json, application/vnd.oai.openapi+json' },\n    });\n  } catch {\n    return { attempt: { url: candidate, outcome: 'network-error' } };\n  }\n\n  if (!isSuccessfulStatus(response.status)) {\n    return { attempt: { url: candidate, outcome: 'http-error', status: response.status } };\n  }\n\n  const parsed = await parseJsonResponse(response);\n  if (parsed === undefined) {\n    return { attempt: { url: candidate, outcome: 'parse-error', status: response.status } };\n  }\n  if (!isOpenApiDocument(parsed)) {\n    return {\n      attempt: { url: candidate, outcome: 'unsupported-document', status: response.status },\n    };\n  }\n\n  const result = importOpenApiCandidate(input, candidate, parsed, requestedScope);\n  return {\n    attempt: {\n      url: candidate,\n      outcome: result.ok ? 'matched' : 'invalid-document',\n      status: response.status,\n    },\n    result,\n  };\n}\n\n/*** Applies service scoping and imports one validated OpenAPI candidate. */\nfunction importOpenApiCandidate(\n  input: DiscoverOpenApiInput,\n  candidate: string,\n  parsed: OpenApiDocumentObject,\n  requestedScope: string | undefined,\n): ReturnType<typeof importOpenApiDocument> {\n  let document = parsed;\n  if (requestedScope !== undefined) {\n    const scoped = scopeOpenApiDocument(parsed, input.id, requestedScope, candidate);\n    if (!scoped.ok) return { ok: false, diagnostics: [scoped.diagnostic] };\n    const { document: scopedDocument } = scoped;\n    document = scopedDocument;\n  }\n  return importOpenApiDocument({\n    id: input.id,\n    document,\n    baseUrl: input.baseUrl,\n    credential: input.credential,\n    documentUrl: candidate,\n    name: input.name,\n    description: input.description,\n    metadata: input.metadata,\n  });\n}\n\n/*** Checks whether parsed JSON has the minimal OpenAPI document shape required for import. */\nfunction isOpenApiDocument(value: unknown): value is OpenApiDocumentObject {\n  const record = readRecord(value);\n  return (\n    record !== undefined &&\n    typeof record.openapi === 'string' &&\n    readRecord(record.paths) !== undefined\n  );\n}\n\n/*** Reads a GraphQL introspection schema from a parsed response payload. */\nfunction readGraphQlIntrospection(value: unknown): GraphQlIntrospectionResult | undefined {\n  const payload = readRecord(value);\n  const data = readRecord(payload?.data);\n  if (readRecord(data?.__schema) === undefined) return undefined;\n  return data;\n}\n\n/*** Builds a canonical OpenAPI discovery failure with safe diagnostics. */\nfunction discoveryFailure(\n  apiId: string,\n  attempts: readonly OpenApiDiscoveryAttempt[],\n  message: string,\n): DiscoverOpenApiResult {\n  return {\n    ok: false,\n    attempts,\n    diagnostics: [{ code: 'missing-schema', apiId, message, severity: 'error' }],\n  };\n}\n\n/*** Builds a canonical GraphQL introspection failure with API identity. */\nfunction graphqlFailure(\n  apiId: string,\n  message: string,\n  code: DataSourceDiagnostic['code'] = 'invalid-config',\n): Extract<IntrospectGraphQlApiResult, { readonly ok: false }> {\n  return {\n    ok: false,\n    diagnostics: [{ code, apiId, message, severity: 'error' }],\n  };\n}\n"]}

package/dist/discovery/openapiDiscoveryPlan.d.ts

@@ -0,0 +1,12 @@
+/*** Builds the ordered OpenAPI probe plan and the normalized service scope requested by the caller. */
+export declare function createOpenApiDiscoveryPlan(rawUrl: string, conventionalPaths: readonly string[]): OpenApiDiscoveryPlan;
+interface OpenApiDiscoveryPlan {
+    readonly candidates: readonly OpenApiDiscoveryCandidate[];
+    readonly requestedScope: string | undefined;
+}
+interface OpenApiDiscoveryCandidate {
+    readonly url: string;
+    readonly scopeToRequestedService: boolean;
+}
+export {};
+//# sourceMappingURL=openapiDiscoveryPlan.d.ts.map

package/dist/discovery/openapiDiscoveryPlan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapiDiscoveryPlan.d.ts","sourceRoot":"","sources":["../../src/discovery/openapiDiscoveryPlan.ts"],"names":[],"mappings":"AAEA,uGAAuG;AACvG,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,MAAM,EACd,iBAAiB,EAAE,SAAS,MAAM,EAAE,GACnC,oBAAoB,CAmCtB;AAED,UAAU,oBAAoB;IAC5B,QAAQ,CAAC,UAAU,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAC1D,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7C;AAED,UAAU,yBAAyB;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,uBAAuB,EAAE,OAAO,CAAC;CAC3C"}

package/dist/discovery/openapiDiscoveryPlan.js

@@ -0,0 +1,41 @@
+import { normalizeCandidateUrl, parseHttpUrl } from './http';
+/*** Builds the ordered OpenAPI probe plan and the normalized service scope requested by the caller. */
+export function createOpenApiDiscoveryPlan(rawUrl, conventionalPaths) {
+    const parsed = parseHttpUrl(rawUrl);
+    if (parsed === undefined)
+        return { candidates: [], requestedScope: undefined };
+    const exact = normalizeCandidateUrl(parsed);
+    const serviceBase = new URL(exact);
+    if (!serviceBase.pathname.endsWith('/'))
+        serviceBase.pathname = `${serviceBase.pathname}/`;
+    const candidates = new Map();
+    candidates.set(exact, { url: exact, scopeToRequestedService: false });
+    for (const path of conventionalPaths) {
+        const normalizedPath = path.replace(/^\/+/, '');
+        const serviceUrl = normalizeCandidateUrl(new URL(normalizedPath, serviceBase));
+        const rootUrl = normalizeCandidateUrl(new URL(normalizedPath, `${parsed.origin}/`));
+        if (!candidates.has(serviceUrl)) {
+            candidates.set(serviceUrl, { url: serviceUrl, scopeToRequestedService: false });
+        }
+        if (!candidates.has(rootUrl)) {
+            candidates.set(rootUrl, { url: rootUrl, scopeToRequestedService: true });
+        }
+    }
+    const requestedPath = normalizeServicePath(parsed.pathname);
+    const isExplicitRootDocument = conventionalPaths.some((path) => {
+        const normalizedPath = path.replace(/^\/+/, '');
+        const rootCandidate = new URL(normalizedPath, `${parsed.origin}/`);
+        return (rootCandidate.origin === parsed.origin &&
+            normalizeServicePath(rootCandidate.pathname) === requestedPath);
+    });
+    return {
+        candidates: [...candidates.values()],
+        requestedScope: requestedPath === '/' || isExplicitRootDocument ? undefined : requestedPath,
+    };
+}
+/*** Normalizes trailing slashes for segment-safe service-path comparisons. */
+function normalizeServicePath(pathname) {
+    const normalized = pathname.replace(/\/+$/g, '');
+    return normalized.length === 0 ? '/' : normalized;
+}
+//# sourceMappingURL=openapiDiscoveryPlan.js.map

package/dist/discovery/openapiDiscoveryPlan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapiDiscoveryPlan.js","sourceRoot":"","sources":["../../src/discovery/openapiDiscoveryPlan.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAE7D,uGAAuG;AACvG,MAAM,UAAU,0BAA0B,CACxC,MAAc,EACd,iBAAoC;IAEpC,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IACpC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,cAAc,EAAE,SAAS,EAAE,CAAC;IAE/E,MAAM,KAAK,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC5C,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IACnC,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,WAAW,CAAC,QAAQ,GAAG,GAAG,WAAW,CAAC,QAAQ,GAAG,CAAC;IAE3F,MAAM,UAAU,GAAG,IAAI,GAAG,EAAqC,CAAC;IAChE,UAAU,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,uBAAuB,EAAE,KAAK,EAAE,CAAC,CAAC;IACtE,KAAK,MAAM,IAAI,IAAI,iBAAiB,EAAE,CAAC;QACrC,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAChD,MAAM,UAAU,GAAG,qBAAqB,CAAC,IAAI,GAAG,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC,CAAC;QAC/E,MAAM,OAAO,GAAG,qBAAqB,CAAC,IAAI,GAAG,CAAC,cAAc,EAAE,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACpF,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;YAChC,UAAU,CAAC,GAAG,CAAC,UAAU,EAAE,EAAE,GAAG,EAAE,UAAU,EAAE,uBAAuB,EAAE,KAAK,EAAE,CAAC,CAAC;QAClF,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YAC7B,UAAU,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,uBAAuB,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3E,CAAC;IACH,CAAC;IAED,MAAM,aAAa,GAAG,oBAAoB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC5D,MAAM,sBAAsB,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;QAC7D,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAChD,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,cAAc,EAAE,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;QACnE,OAAO,CACL,aAAa,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM;YACtC,oBAAoB,CAAC,aAAa,CAAC,QAAQ,CAAC,KAAK,aAAa,CAC/D,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,OAAO;QACL,UAAU,EAAE,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC;QACpC,cAAc,EAAE,aAAa,KAAK,GAAG,IAAI,sBAAsB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa;KAC5F,CAAC;AACJ,CAAC;AAYD,8EAA8E;AAC9E,SAAS,oBAAoB,CAAC,QAAgB;IAC5C,MAAM,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IACjD,OAAO,UAAU,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC;AACpD,CAAC","sourcesContent":["import { normalizeCandidateUrl, parseHttpUrl } from './http';\n\n/*** Builds the ordered OpenAPI probe plan and the normalized service scope requested by the caller. */\nexport function createOpenApiDiscoveryPlan(\n  rawUrl: string,\n  conventionalPaths: readonly string[],\n): OpenApiDiscoveryPlan {\n  const parsed = parseHttpUrl(rawUrl);\n  if (parsed === undefined) return { candidates: [], requestedScope: undefined };\n\n  const exact = normalizeCandidateUrl(parsed);\n  const serviceBase = new URL(exact);\n  if (!serviceBase.pathname.endsWith('/')) serviceBase.pathname = `${serviceBase.pathname}/`;\n\n  const candidates = new Map<string, OpenApiDiscoveryCandidate>();\n  candidates.set(exact, { url: exact, scopeToRequestedService: false });\n  for (const path of conventionalPaths) {\n    const normalizedPath = path.replace(/^\\/+/, '');\n    const serviceUrl = normalizeCandidateUrl(new URL(normalizedPath, serviceBase));\n    const rootUrl = normalizeCandidateUrl(new URL(normalizedPath, `${parsed.origin}/`));\n    if (!candidates.has(serviceUrl)) {\n      candidates.set(serviceUrl, { url: serviceUrl, scopeToRequestedService: false });\n    }\n    if (!candidates.has(rootUrl)) {\n      candidates.set(rootUrl, { url: rootUrl, scopeToRequestedService: true });\n    }\n  }\n\n  const requestedPath = normalizeServicePath(parsed.pathname);\n  const isExplicitRootDocument = conventionalPaths.some((path) => {\n    const normalizedPath = path.replace(/^\\/+/, '');\n    const rootCandidate = new URL(normalizedPath, `${parsed.origin}/`);\n    return (\n      rootCandidate.origin === parsed.origin &&\n      normalizeServicePath(rootCandidate.pathname) === requestedPath\n    );\n  });\n  return {\n    candidates: [...candidates.values()],\n    requestedScope: requestedPath === '/' || isExplicitRootDocument ? undefined : requestedPath,\n  };\n}\n\ninterface OpenApiDiscoveryPlan {\n  readonly candidates: readonly OpenApiDiscoveryCandidate[];\n  readonly requestedScope: string | undefined;\n}\n\ninterface OpenApiDiscoveryCandidate {\n  readonly url: string;\n  readonly scopeToRequestedService: boolean;\n}\n\n/*** Normalizes trailing slashes for segment-safe service-path comparisons. */\nfunction normalizeServicePath(pathname: string): string {\n  const normalized = pathname.replace(/\\/+$/g, '');\n  return normalized.length === 0 ? '/' : normalized;\n}\n"]}

package/dist/discovery/scopeOpenApiDocument.d.ts

@@ -0,0 +1,13 @@
+import type { DataSourceDiagnostic } from '@ankhorage/contracts/data';
+import type { OpenApiDocumentObject } from '../openapi';
+/*** Filters an origin-root OpenAPI document to the requested service path without rewriting paths. */
+export declare function scopeOpenApiDocument(document: OpenApiDocumentObject, apiId: string, requestedScope: string, documentUrl: string): ScopeOpenApiDocumentResult;
+type ScopeOpenApiDocumentResult = {
+    readonly ok: true;
+    readonly document: OpenApiDocumentObject;
+} | {
+    readonly ok: false;
+    readonly diagnostic: DataSourceDiagnostic;
+};
+export {};
+//# sourceMappingURL=scopeOpenApiDocument.d.ts.map

package/dist/discovery/scopeOpenApiDocument.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scopeOpenApiDocument.d.ts","sourceRoot":"","sources":["../../src/discovery/scopeOpenApiDocument.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAEtE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExD,sGAAsG;AACtG,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,qBAAqB,EAC/B,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,MAAM,GAClB,0BAA0B,CAoB5B;AAED,KAAK,0BAA0B,GAC3B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAA;CAAE,GAC/D;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAA;CAAE,CAAC"}

package/dist/discovery/scopeOpenApiDocument.js

@@ -0,0 +1,27 @@
+/*** Filters an origin-root OpenAPI document to the requested service path without rewriting paths. */
+export function scopeOpenApiDocument(document, apiId, requestedScope, documentUrl) {
+    const paths = Object.fromEntries(Object.entries(document.paths ?? {}).filter(([path]) => path === requestedScope || path.startsWith(`${requestedScope}/`)));
+    if (Object.keys(paths).length > 0)
+        return { ok: true, document: { ...document, paths } };
+    return {
+        ok: false,
+        diagnostic: {
+            code: 'missing-schema',
+            apiId,
+            message: `OpenAPI document '${redactDiagnosticUrl(documentUrl)}' contains no paths ` +
+                `within requested service scope '${requestedScope}'.`,
+            path: 'paths',
+            severity: 'error',
+        },
+    };
+}
+/*** Removes credentials, query parameters, and fragments from a URL included in diagnostics. */
+function redactDiagnosticUrl(rawUrl) {
+    const url = new URL(rawUrl);
+    url.username = '';
+    url.password = '';
+    url.search = '';
+    url.hash = '';
+    return url.toString();
+}
+//# sourceMappingURL=scopeOpenApiDocument.js.map

package/dist/discovery/scopeOpenApiDocument.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scopeOpenApiDocument.js","sourceRoot":"","sources":["../../src/discovery/scopeOpenApiDocument.ts"],"names":[],"mappings":"AAIA,sGAAsG;AACtG,MAAM,UAAU,oBAAoB,CAClC,QAA+B,EAC/B,KAAa,EACb,cAAsB,EACtB,WAAmB;IAEnB,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,CAC9B,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,CACzC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,KAAK,cAAc,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,cAAc,GAAG,CAAC,CAC7E,CACF,CAAC;IACF,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,GAAG,QAAQ,EAAE,KAAK,EAAE,EAAE,CAAC;IAEzF,OAAO;QACL,EAAE,EAAE,KAAK;QACT,UAAU,EAAE;YACV,IAAI,EAAE,gBAAgB;YACtB,KAAK;YACL,OAAO,EACL,qBAAqB,mBAAmB,CAAC,WAAW,CAAC,sBAAsB;gBAC3E,mCAAmC,cAAc,IAAI;YACvD,IAAI,EAAE,OAAO;YACb,QAAQ,EAAE,OAAO;SAClB;KACF,CAAC;AACJ,CAAC;AAMD,gGAAgG;AAChG,SAAS,mBAAmB,CAAC,MAAc;IACzC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5B,GAAG,CAAC,QAAQ,GAAG,EAAE,CAAC;IAClB,GAAG,CAAC,QAAQ,GAAG,EAAE,CAAC;IAClB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC;IAChB,GAAG,CAAC,IAAI,GAAG,EAAE,CAAC;IACd,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC;AACxB,CAAC","sourcesContent":["import type { DataSourceDiagnostic } from '@ankhorage/contracts/data';\n\nimport type { OpenApiDocumentObject } from '../openapi';\n\n/*** Filters an origin-root OpenAPI document to the requested service path without rewriting paths. */\nexport function scopeOpenApiDocument(\n  document: OpenApiDocumentObject,\n  apiId: string,\n  requestedScope: string,\n  documentUrl: string,\n): ScopeOpenApiDocumentResult {\n  const paths = Object.fromEntries(\n    Object.entries(document.paths ?? {}).filter(\n      ([path]) => path === requestedScope || path.startsWith(`${requestedScope}/`),\n    ),\n  );\n  if (Object.keys(paths).length > 0) return { ok: true, document: { ...document, paths } };\n\n  return {\n    ok: false,\n    diagnostic: {\n      code: 'missing-schema',\n      apiId,\n      message:\n        `OpenAPI document '${redactDiagnosticUrl(documentUrl)}' contains no paths ` +\n        `within requested service scope '${requestedScope}'.`,\n      path: 'paths',\n      severity: 'error',\n    },\n  };\n}\n\ntype ScopeOpenApiDocumentResult =\n  | { readonly ok: true; readonly document: OpenApiDocumentObject }\n  | { readonly ok: false; readonly diagnostic: DataSourceDiagnostic };\n\n/*** Removes credentials, query parameters, and fragments from a URL included in diagnostics. */\nfunction redactDiagnosticUrl(rawUrl: string): string {\n  const url = new URL(rawUrl);\n  url.username = '';\n  url.password = '';\n  url.search = '';\n  url.hash = '';\n  return url.toString();\n}\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ankhorage/data-sources",
   "type": "module",
-  "version": "2.0.4",
+  "version": "2.0.5",
   "description": "Headless toolkit for importing, normalizing, and executing canonical Ankhorage API and data-source configs.",
   "homepage": "https://github.com/ankhorage/data-sources#readme",
   "bugs": {

package/src/discovery/index.test.ts

@@ -1,5 +1,6 @@
 import { expect, it } from 'bun:test';
 
+import { buildEndpointTestRequest } from '../test-runner';
 import {
   createOpenApiDiscoveryCandidates,
   discoverOpenApi,
@@ -25,6 +26,34 @@ function openApiDocument() {
   } as const;
 }
 
+function gatewayOpenApiDocument() {
+  return {
+    openapi: '3.1.0',
+    info: { title: 'Shared Gateway', version: '1.0.0' },
+    servers: [{ url: 'https://api.example.com' }],
+    paths: {
+      '/health': { get: {} },
+      '/v1/chess/openings': { get: {} },
+      '/v1/poker/health': { get: {} },
+      '/v1/poker/training/tasks': { get: {} },
+      '/v1/poker/training/tasks/{taskId}': { get: {} },
+      '/v1/poker/training/tasks/{taskId}/answer': { post: {} },
+      '/v1/poker/training/tasks/by-slug/{slug}': { get: {} },
+      '/v1/poker-admin/status': { get: {} },
+      '/v1/pokerface/status': { get: {} },
+    },
+  } as const;
+}
+
+function serviceLocalOpenApiDocument() {
+  return {
+    openapi: '3.1.0',
+    info: { title: 'Poker API', version: '1.0.0' },
+    servers: [{ url: 'https://api.example.com/v1/poker' }],
+    paths: { '/health': { get: {} } },
+  } as const;
+}
+
 function graphQlPayload() {
   return {
     data: {
@@ -100,6 +129,124 @@ it('falls back to OpenAPI conventional locations without leaking response data',
   expect(JSON.stringify(result)).not.toContain('hidden');
 });
 
+it('scopes root OpenAPI discovery to the requested service and preserves runtime URLs', async () => {
+  const calls: string[] = [];
+  const fetch: ExternalApiFetch = (url) => {
+    calls.push(url);
+    return Promise.resolve(
+      url === 'https://api.example.com/openapi.json'
+        ? jsonResponse(gatewayOpenApiDocument())
+        : jsonResponse({ private: 'hidden' }, 404),
+    );
+  };
+  const result = await discoverOpenApi({
+    id: 'poker',
+    url: 'https://api.example.com/v1/poker/?tenant=private#fragment',
+    conventionalPaths: ['openapi.json'],
+    fetch,
+  });
+
+  expect(calls).toEqual([
+    'https://api.example.com/v1/poker/?tenant=private',
+    'https://api.example.com/v1/poker/openapi.json',
+    'https://api.example.com/openapi.json',
+  ]);
+  expect(result.ok).toBe(true);
+  if (result.ok) {
+    expect(result.documentUrl).toBe('https://api.example.com/openapi.json');
+    expect(result.data.baseUrl).toBe('https://api.example.com');
+    expect(result.data.openApi?.url).toBe('https://api.example.com/openapi.json');
+    expect(
+      Object.values(result.data.endpoints)
+        .map((endpoint) => endpoint.path)
+        .sort(),
+    ).toEqual([
+      '/v1/poker/health',
+      '/v1/poker/training/tasks',
+      '/v1/poker/training/tasks/by-slug/{slug}',
+      '/v1/poker/training/tasks/{taskId}',
+      '/v1/poker/training/tasks/{taskId}/answer',
+    ]);
+    const request = await buildEndpointTestRequest({
+      api: result.data,
+      endpointId: 'v1-poker-training-tasks',
+      operationId: 'get-v1-poker-training-tasks',
+      dryRun: true,
+    });
+    expect(request.ok).toBe(true);
+    if (request.ok) {
+      expect(request.request.url).toBe('https://api.example.com/v1/poker/training/tasks');
+    }
+  }
+});
+
+it('keeps service-local OpenAPI documents unscoped', async () => {
+  const fetch: ExternalApiFetch = (url) =>
+    Promise.resolve(
+      url === 'https://api.example.com/v1/poker/openapi.json'
+        ? jsonResponse(serviceLocalOpenApiDocument())
+        : jsonResponse({}, 404),
+    );
+  const result = await discoverOpenApi({
+    id: 'poker',
+    url: 'https://api.example.com/v1/poker/',
+    conventionalPaths: ['openapi.json'],
+    fetch,
+  });
+
+  expect(result.ok).toBe(true);
+  if (result.ok) {
+    expect(result.documentUrl).toBe('https://api.example.com/v1/poker/openapi.json');
+    expect(result.data.baseUrl).toBe('https://api.example.com/v1/poker');
+    expect(result.data.endpoints.health?.path).toBe('/health');
+  }
+});
+
+it('keeps root host and explicit root-document discovery unscoped', async () => {
+  for (const url of ['https://api.example.com/', 'https://api.example.com/openapi.json']) {
+    const result = await discoverOpenApi({
+      id: 'gateway',
+      url,
+      conventionalPaths: ['openapi.json'],
+      fetch: (candidate) =>
+        Promise.resolve(
+          candidate === 'https://api.example.com/openapi.json'
+            ? jsonResponse(gatewayOpenApiDocument())
+            : jsonResponse({}, 404),
+        ),
+    });
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(Object.keys(result.data.endpoints)).toHaveLength(9);
+  }
+});
+
+it('fails safely when a root document has no paths in the requested scope', async () => {
+  const result = await discoverOpenApi({
+    id: 'missing',
+    url: 'https://api.example.com/v1/missing',
+    conventionalPaths: ['openapi.json'],
+    fetch: (url) =>
+      Promise.resolve(
+        url === 'https://api.example.com/openapi.json'
+          ? jsonResponse(gatewayOpenApiDocument())
+          : jsonResponse({ private: 'hidden' }, 404),
+      ),
+  });
+
+  expect(result.ok).toBe(false);
+  if (!result.ok) {
+    expect(result.attempts.at(-1)).toEqual({
+      url: 'https://api.example.com/openapi.json',
+      outcome: 'invalid-document',
+      status: 200,
+    });
+    expect(result.diagnostics[0]).toMatchObject({ code: 'missing-schema', path: 'paths' });
+    expect(result.diagnostics[0]?.message).toContain("requested service scope '/v1/missing'");
+    expect(result.diagnostics[0]?.message).toContain('https://api.example.com/openapi.json');
+    expect(JSON.stringify(result)).not.toContain('hidden');
+  }
+});
+
 it('introspects GraphQL without echoing trusted headers', async () => {
   const result = await introspectGraphQlApi({
     id: 'catalog',

package/src/discovery/index.ts

@@ -19,6 +19,8 @@ import {
   parseJsonResponse,
   readRecord,
 } from './http';
+import { createOpenApiDiscoveryPlan } from './openapiDiscoveryPlan';
+import { scopeOpenApiDocument } from './scopeOpenApiDocument';
 
 export const DEFAULT_OPENAPI_DISCOVERY_PATHS = [
   'openapi.json',
@@ -107,43 +109,35 @@ export type IntrospectGraphQlApiResult =
       readonly status?: number;
     };
 
+/*** Creates the ordered, deduplicated URLs probed during OpenAPI discovery. */
 export function createOpenApiDiscoveryCandidates(
   rawUrl: string,
   conventionalPaths: readonly string[] = DEFAULT_OPENAPI_DISCOVERY_PATHS,
 ): readonly string[] {
-  const parsed = parseHttpUrl(rawUrl);
-  if (parsed === undefined) return [];
-
-  const exact = normalizeCandidateUrl(parsed);
-  const serviceBase = new URL(exact);
-  if (!serviceBase.pathname.endsWith('/')) serviceBase.pathname = `${serviceBase.pathname}/`;
-
-  const candidates = [exact];
-  for (const path of conventionalPaths) {
-    const normalizedPath = path.replace(/^\/+/, '');
-    candidates.push(normalizeCandidateUrl(new URL(normalizedPath, serviceBase)));
-    candidates.push(normalizeCandidateUrl(new URL(normalizedPath, `${parsed.origin}/`)));
-  }
-
-  return [...new Set(candidates)];
+  return createOpenApiDiscoveryPlan(rawUrl, conventionalPaths).candidates.map(
+    (candidate) => candidate.url,
+  );
 }
 
+/*** Discovers and imports an OpenAPI document while preserving the requested service boundary. */
 export async function discoverOpenApi(input: DiscoverOpenApiInput): Promise<DiscoverOpenApiResult> {
-  const candidates = createOpenApiDiscoveryCandidates(input.url, input.conventionalPaths);
-  if (candidates.length === 0) {
+  const conventionalPaths = input.conventionalPaths ?? DEFAULT_OPENAPI_DISCOVERY_PATHS;
+  const plan = createOpenApiDiscoveryPlan(input.url, conventionalPaths);
+  if (plan.candidates.length === 0) {
     return discoveryFailure(input.id, [], 'OpenAPI discovery requires a valid HTTP or HTTPS URL.');
   }
 
   const attempts: OpenApiDiscoveryAttempt[] = [];
-  for (const candidate of candidates) {
-    const probed = await probeOpenApiCandidate(input, candidate);
+  for (const candidate of plan.candidates) {
+    const requestedScope = candidate.scopeToRequestedService ? plan.requestedScope : undefined;
+    const probed = await probeOpenApiCandidate(input, candidate.url, requestedScope);
     attempts.push(probed.attempt);
     if (probed.result === undefined) continue;
     return probed.result.ok
       ? {
           ok: true,
           data: probed.result.data,
-          documentUrl: candidate,
+          documentUrl: candidate.url,
           attempts,
           diagnostics: probed.result.diagnostics ?? [],
         }
@@ -157,6 +151,7 @@ export async function discoverOpenApi(input: DiscoverOpenApiInput): Promise<Disc
   );
 }
 
+/*** Introspects a GraphQL endpoint and normalizes its schema into the canonical API definition. */
 export async function introspectGraphQlApi(
   input: IntrospectGraphQlApiInput,
 ): Promise<IntrospectGraphQlApiResult> {
@@ -205,6 +200,7 @@ export async function introspectGraphQlApi(
     : { ok: false, diagnostics: result.diagnostics };
 }
 
+/*** Fetches GraphQL introspection without exposing transport failures beyond the discovery boundary. */
 async function fetchGraphQlIntrospection(
   input: IntrospectGraphQlApiInput,
   endpoint: URL,
@@ -229,9 +225,11 @@ interface OpenApiProbeResult {
   readonly result?: ReturnType<typeof importOpenApiDocument>;
 }
 
+/*** Probes one OpenAPI candidate and scopes origin-root documents before canonical import. */
 async function probeOpenApiCandidate(
   input: DiscoverOpenApiInput,
   candidate: string,
+  requestedScope: string | undefined,
 ): Promise<OpenApiProbeResult> {
   let response: ExternalApiFetchResponse;
   try {
@@ -257,16 +255,7 @@ async function probeOpenApiCandidate(
     };
   }
 
-  const result = importOpenApiDocument({
-    id: input.id,
-    document: parsed,
-    baseUrl: input.baseUrl,
-    credential: input.credential,
-    documentUrl: candidate,
-    name: input.name,
-    description: input.description,
-    metadata: input.metadata,
-  });
+  const result = importOpenApiCandidate(input, candidate, parsed, requestedScope);
   return {
     attempt: {
       url: candidate,
@@ -277,6 +266,33 @@ async function probeOpenApiCandidate(
   };
 }
 
+/*** Applies service scoping and imports one validated OpenAPI candidate. */
+function importOpenApiCandidate(
+  input: DiscoverOpenApiInput,
+  candidate: string,
+  parsed: OpenApiDocumentObject,
+  requestedScope: string | undefined,
+): ReturnType<typeof importOpenApiDocument> {
+  let document = parsed;
+  if (requestedScope !== undefined) {
+    const scoped = scopeOpenApiDocument(parsed, input.id, requestedScope, candidate);
+    if (!scoped.ok) return { ok: false, diagnostics: [scoped.diagnostic] };
+    const { document: scopedDocument } = scoped;
+    document = scopedDocument;
+  }
+  return importOpenApiDocument({
+    id: input.id,
+    document,
+    baseUrl: input.baseUrl,
+    credential: input.credential,
+    documentUrl: candidate,
+    name: input.name,
+    description: input.description,
+    metadata: input.metadata,
+  });
+}
+
+/*** Checks whether parsed JSON has the minimal OpenAPI document shape required for import. */
 function isOpenApiDocument(value: unknown): value is OpenApiDocumentObject {
   const record = readRecord(value);
   return (
@@ -286,6 +302,7 @@ function isOpenApiDocument(value: unknown): value is OpenApiDocumentObject {
   );
 }
 
+/*** Reads a GraphQL introspection schema from a parsed response payload. */
 function readGraphQlIntrospection(value: unknown): GraphQlIntrospectionResult | undefined {
   const payload = readRecord(value);
   const data = readRecord(payload?.data);
@@ -293,6 +310,7 @@ function readGraphQlIntrospection(value: unknown): GraphQlIntrospectionResult |
   return data;
 }
 
+/*** Builds a canonical OpenAPI discovery failure with safe diagnostics. */
 function discoveryFailure(
   apiId: string,
   attempts: readonly OpenApiDiscoveryAttempt[],
@@ -305,6 +323,7 @@ function discoveryFailure(
   };
 }
 
+/*** Builds a canonical GraphQL introspection failure with API identity. */
 function graphqlFailure(
   apiId: string,
   message: string,

package/src/discovery/openapiDiscoveryPlan.ts

@@ -0,0 +1,58 @@
+import { normalizeCandidateUrl, parseHttpUrl } from './http';
+
+/*** Builds the ordered OpenAPI probe plan and the normalized service scope requested by the caller. */
+export function createOpenApiDiscoveryPlan(
+  rawUrl: string,
+  conventionalPaths: readonly string[],
+): OpenApiDiscoveryPlan {
+  const parsed = parseHttpUrl(rawUrl);
+  if (parsed === undefined) return { candidates: [], requestedScope: undefined };
+
+  const exact = normalizeCandidateUrl(parsed);
+  const serviceBase = new URL(exact);
+  if (!serviceBase.pathname.endsWith('/')) serviceBase.pathname = `${serviceBase.pathname}/`;
+
+  const candidates = new Map<string, OpenApiDiscoveryCandidate>();
+  candidates.set(exact, { url: exact, scopeToRequestedService: false });
+  for (const path of conventionalPaths) {
+    const normalizedPath = path.replace(/^\/+/, '');
+    const serviceUrl = normalizeCandidateUrl(new URL(normalizedPath, serviceBase));
+    const rootUrl = normalizeCandidateUrl(new URL(normalizedPath, `${parsed.origin}/`));
+    if (!candidates.has(serviceUrl)) {
+      candidates.set(serviceUrl, { url: serviceUrl, scopeToRequestedService: false });
+    }
+    if (!candidates.has(rootUrl)) {
+      candidates.set(rootUrl, { url: rootUrl, scopeToRequestedService: true });
+    }
+  }
+
+  const requestedPath = normalizeServicePath(parsed.pathname);
+  const isExplicitRootDocument = conventionalPaths.some((path) => {
+    const normalizedPath = path.replace(/^\/+/, '');
+    const rootCandidate = new URL(normalizedPath, `${parsed.origin}/`);
+    return (
+      rootCandidate.origin === parsed.origin &&
+      normalizeServicePath(rootCandidate.pathname) === requestedPath
+    );
+  });
+  return {
+    candidates: [...candidates.values()],
+    requestedScope: requestedPath === '/' || isExplicitRootDocument ? undefined : requestedPath,
+  };
+}
+
+interface OpenApiDiscoveryPlan {
+  readonly candidates: readonly OpenApiDiscoveryCandidate[];
+  readonly requestedScope: string | undefined;
+}
+
+interface OpenApiDiscoveryCandidate {
+  readonly url: string;
+  readonly scopeToRequestedService: boolean;
+}
+
+/*** Normalizes trailing slashes for segment-safe service-path comparisons. */
+function normalizeServicePath(pathname: string): string {
+  const normalized = pathname.replace(/\/+$/g, '');
+  return normalized.length === 0 ? '/' : normalized;
+}

package/src/discovery/scopeOpenApiDocument.ts

@@ -0,0 +1,45 @@
+import type { DataSourceDiagnostic } from '@ankhorage/contracts/data';
+
+import type { OpenApiDocumentObject } from '../openapi';
+
+/*** Filters an origin-root OpenAPI document to the requested service path without rewriting paths. */
+export function scopeOpenApiDocument(
+  document: OpenApiDocumentObject,
+  apiId: string,
+  requestedScope: string,
+  documentUrl: string,
+): ScopeOpenApiDocumentResult {
+  const paths = Object.fromEntries(
+    Object.entries(document.paths ?? {}).filter(
+      ([path]) => path === requestedScope || path.startsWith(`${requestedScope}/`),
+    ),
+  );
+  if (Object.keys(paths).length > 0) return { ok: true, document: { ...document, paths } };
+
+  return {
+    ok: false,
+    diagnostic: {
+      code: 'missing-schema',
+      apiId,
+      message:
+        `OpenAPI document '${redactDiagnosticUrl(documentUrl)}' contains no paths ` +
+        `within requested service scope '${requestedScope}'.`,
+      path: 'paths',
+      severity: 'error',
+    },
+  };
+}
+
+type ScopeOpenApiDocumentResult =
+  | { readonly ok: true; readonly document: OpenApiDocumentObject }
+  | { readonly ok: false; readonly diagnostic: DataSourceDiagnostic };
+
+/*** Removes credentials, query parameters, and fragments from a URL included in diagnostics. */
+function redactDiagnosticUrl(rawUrl: string): string {
+  const url = new URL(rawUrl);
+  url.username = '';
+  url.password = '';
+  url.search = '';
+  url.hash = '';
+  return url.toString();
+}