move ir into kernel

Rhys Sullivan committed 8 months ago

Commit e2dcd001 parent b2b2e8023 files · +94 −32Browse files

Showing the changes to packages/kernel (8 of 23 files). Show all

Unified · Split

8 files

packages/kernel/ir/README.md +34 −0
packages/kernel/ir/package.json +27 −0
packages/kernel/ir/src/catalog.test.ts +748 −0
packages/kernel/ir/src/catalog.ts +2018 −0
packages/kernel/ir/src/ids.ts +58 −0
packages/kernel/ir/src/index.ts +3 −0
packages/kernel/ir/src/model.ts +971 −0
packages/kernel/ir/tsconfig.json +15 −0

@@ -0,0 +1,34 @@
	1	# IR v1
	2
	3	`@executor/ir` is the greenfield semantic center for imported sources.
	4
	5	## Boundary
	6
	7	- `CatalogSnapshotV1` is the canonical persisted import artifact.
	8	- `CatalogV1` is the normalized semantic graph.
	9	- `CatalogFragmentV1` is the adapter/importer output contract.
	10	- `ToolDescriptor`, search docs, inspect views, and `InvocationPlan` are projections.
	11
	12	## Direction
	13
	14	Importers should move toward:
	15
	16	`source -> CatalogFragmentV1 -> merge -> CatalogV1 -> projectors -> InvocationPlan`
	17
	18	The existing runtime-specific compiled payload blobs are no longer the target semantic center.
	19
	20	## Package Surface
	21
	22	Use either:
	23
	24	- `@executor/ir`
	25	- `@executor/control-plane/ir` as a compatibility shim
	26	- `import { ir } from "@executor/control-plane"`
	27
	28	## Guarantees
	29
	30	- provenance is required on entities
	31	- synthetic entities are marked explicitly
	32	- lossy normalization is represented by diagnostics
	33	- inheritance is preserved in scopes and resolved at projection/planning time
	34	- invocation plans remain connection-bound runtime artifacts, not canonical IR

packages/kernel/ir/package.json+27−0

@@ -0,0 +1,27 @@
	1	{
	2	"name": "@executor/ir",
	3	"private": true,
	4	"type": "module",
	5	"exports": {
	6	".": "./src/index.ts",
	7	"./catalog": "./src/catalog.ts",
	8	"./ids": "./src/ids.ts",
	9	"./model": "./src/model.ts"
	10	},
	11	"scripts": {
	12	"typecheck": "bunx tsc --noEmit -p tsconfig.json",
	13	"test": "vitest run",
	14	"test:watch": "vitest"
	15	},
	16	"dependencies": {
	17	"@executor/codemode-core": "workspace:*",
	18	"effect": "catalog:"
	19	},
	20	"devDependencies": {
	21	"@effect/vitest": "catalog:",
	22	"@types/node": "catalog:",
	23	"bun-types": "catalog:",
	24	"vitest": "catalog:"
	25	},
	26	"version": "0.0.0"
	27	}

packages/kernel/ir/src/catalog.test.ts+748−0

@@ -0,0 +1,748 @@
	1	import { describe, expect, it } from "@effect/vitest";
	2
	3	import {
	4	buildInvocationPlan,
	5	createCatalogSnapshotV1,
	6	createEmptyCatalogV1,
	7	decodeCatalogSnapshotV1,
	8	mergeCatalogFragments,
	9	projectCatalogForAgentSdk,
	10	projectSymbolExpandedView,
	11	projectSymbolShallowView,
	12	validateCatalogInvariants,
	13	} from "./catalog";
	14	import {
	15	CapabilityIdSchema,
	16	DiagnosticIdSchema,
	17	DocumentIdSchema,
	18	ExecutableIdSchema,
	19	ExampleSymbolIdSchema,
	20	HeaderSymbolIdSchema,
	21	ParameterSymbolIdSchema,
	22	RequestBodySymbolIdSchema,
	23	ResourceIdSchema,
	24	ResponseSetIdSchema,
	25	ResponseSymbolIdSchema,
	26	ScopeIdSchema,
	27	SecuritySchemeSymbolIdSchema,
	28	ShapeSymbolIdSchema,
	29	} from "./ids";
	30	import type { CatalogV1, CatalogFragmentV1, ProvenanceRef } from "./model";
	31
	32	const put = <K extends string, V>(record: Record<K, V>, key: K, value: V) => {
	33	record[key] = value;
	34	};
	35
	36	const expectNullableShapeContains = (
	37	catalog: CatalogV1,
	38	nullableShapeId: ReturnType<typeof ShapeSymbolIdSchema.make>,
	39	expectedInnerShapeId: ReturnType<typeof ShapeSymbolIdSchema.make>,
	40	) => {
	41	const shape = catalog.symbols[nullableShapeId];
	42	if (shape?.kind !== "shape" \|\| shape.node.type !== "anyOf") {
	43	throw new Error("Expected nullable anyOf shape");
	44	}
	45
	46	expect(shape.node.items).toContain(expectedInnerShapeId);
	47	};
	48
	49	const docId = DocumentIdSchema.make("doc_primary");
	50	const baseProvenance = (pointer: string): ProvenanceRef[] => [{
	51	relation: "declared",
	52	documentId: docId,
	53	pointer,
	54	}];
	55
	56	const createHttpCatalog = (input: {
	57	collideIds?: boolean;
	58	method?: string;
	59	} = {}): CatalogV1 => {
	60	const catalog = createEmptyCatalogV1();
	61
	62	const resourceId = ResourceIdSchema.make("res_primary");
	63	const scopeId = ScopeIdSchema.make("scope_service");
	64	const authSchemeId = SecuritySchemeSymbolIdSchema.make("sym_security_oauth");
	65	const bodyShapeId = ShapeSymbolIdSchema.make("shape_event_body");
	66	const resultShapeId = ShapeSymbolIdSchema.make("shape_event_result");
	67	const stringShapeId = ShapeSymbolIdSchema.make("shape_string");
	68	const idPathParamId = ParameterSymbolIdSchema.make("sym_param_path_event_id");
	69	const calendarParamId = ParameterSymbolIdSchema.make("sym_param_path_calendar_id");
	70	const queryParamId = ParameterSymbolIdSchema.make(
	71	input.collideIds ? "sym_param_query_id" : "sym_param_query_send_updates",
	72	);
	73	const requestBodyId = RequestBodySymbolIdSchema.make("sym_request_body_event");
	74	const responseId = ResponseSymbolIdSchema.make("sym_response_200");
	75	const responseSetId = ResponseSetIdSchema.make("response_set_events_update");
	76	const executableId = ExecutableIdSchema.make("exec_http_events_update");
	77	const capabilityId = CapabilityIdSchema.make("cap_events_update");
	78	const exampleId = ExampleSymbolIdSchema.make("sym_example_event_body");
	79
	80	put(catalog.documents as Record<typeof docId, CatalogV1["documents"][typeof docId]>, docId, {
	81	id: docId,
	82	kind: "openapi",
	83	title: "Calendar API",
	84	fetchedAt: "2026-03-14T00:00:00.000Z",
	85	rawRef: "memory://calendar/openapi.json",
	86	});
	87
	88	put(catalog.resources as Record<typeof resourceId, CatalogV1["resources"][typeof resourceId]>, resourceId, {
	89	id: resourceId,
	90	documentId: docId,
	91	canonicalUri: "https://example.test/openapi.json",
	92	baseUri: "https://example.test/openapi.json",
	93	anchors: {},
	94	dynamicAnchors: {},
	95	synthetic: false,
	96	provenance: baseProvenance("#"),
	97	});
	98
	99	put(catalog.scopes as Record<typeof scopeId, CatalogV1["scopes"][typeof scopeId]>, scopeId, {
	100	id: scopeId,
	101	kind: "service",
	102	name: "Calendar",
	103	namespace: "google.calendar",
	104	docs: {
	105	summary: "Calendar service",
	106	description: "Manage calendar events.",
	107	},
	108	synthetic: false,
	109	provenance: baseProvenance("#/servers/0"),
	110	});
	111
	112	put(catalog.symbols as Record<typeof authSchemeId, CatalogV1["symbols"][typeof authSchemeId]>, authSchemeId, {
	113	id: authSchemeId,
	114	kind: "securityScheme",
	115	schemeType: "oauth2",
	116	docs: {
	117	summary: "OAuth 2.0",
	118	},
	119	oauth: {
	120	scopes: {
	121	"calendar.events": "Manage calendar events",
	122	},
	123	},
	124	synthetic: false,
	125	provenance: baseProvenance("#/components/securitySchemes/oauth2"),
	126	});
	127
	128	put(catalog.symbols as Record<typeof stringShapeId, CatalogV1["symbols"][typeof stringShapeId]>, stringShapeId, {
	129	id: stringShapeId,
	130	kind: "shape",
	131	resourceId,
	132	title: "String",
	133	node: {
	134	type: "scalar",
	135	scalar: "string",
	136	},
	137	synthetic: false,
	138	provenance: baseProvenance("#/components/schemas/String"),
	139	});
	140
	141	put(catalog.symbols as Record<typeof bodyShapeId, CatalogV1["symbols"][typeof bodyShapeId]>, bodyShapeId, {
	142	id: bodyShapeId,
	143	kind: "shape",
	144	resourceId,
	145	title: "EventUpdateBody",
	146	node: {
	147	type: "object",
	148	fields: {
	149	summary: {
	150	shapeId: stringShapeId,
	151	},
	152	},
	153	additionalProperties: false,
	154	},
	155	synthetic: false,
	156	provenance: baseProvenance("#/components/schemas/EventUpdateBody"),
	157	});
	158
	159	put(catalog.symbols as Record<typeof resultShapeId, CatalogV1["symbols"][typeof resultShapeId]>, resultShapeId, {
	160	id: resultShapeId,
	161	kind: "shape",
	162	resourceId,
	163	title: "Event",
	164	node: {
	165	type: "object",
	166	fields: {
	167	id: {
	168	shapeId: stringShapeId,
	169	},
	170	summary: {
	171	shapeId: stringShapeId,
	172	},
	173	},
	174	required: ["id"],
	175	additionalProperties: false,
	176	},
	177	synthetic: false,
	178	provenance: baseProvenance("#/components/schemas/Event"),
	179	});
	180
	181	put(catalog.symbols as Record<typeof exampleId, CatalogV1["symbols"][typeof exampleId]>, exampleId, {
	182	id: exampleId,
	183	kind: "example",
	184	exampleKind: "value",
	185	name: "Event body example",
	186	value: {
	187	summary: "Team sync",
	188	},
	189	synthetic: false,
	190	provenance: baseProvenance("#/components/examples/EventBody"),
	191	});
	192
	193	put(catalog.symbols as Record<typeof calendarParamId, CatalogV1["symbols"][typeof calendarParamId]>, calendarParamId, {
	194	id: calendarParamId,
	195	kind: "parameter",
	196	name: input.collideIds ? "id" : "calendarId",
	197	location: "path",
	198	required: true,
	199	docs: {
	200	summary: "Calendar identifier",
	201	description: "The target calendar.",
	202	},
	203	schemaShapeId: stringShapeId,
	204	synthetic: false,
	205	provenance: baseProvenance("#/paths/~1events~1{calendarId}/parameters/0"),
	206	});
	207
	208	put(catalog.symbols as Record<typeof idPathParamId, CatalogV1["symbols"][typeof idPathParamId]>, idPathParamId, {
	209	id: idPathParamId,
	210	kind: "parameter",
	211	name: "eventId",
	212	location: "path",
	213	required: true,
	214	docs: {
	215	summary: "Event identifier",
	216	},
	217	schemaShapeId: stringShapeId,
	218	synthetic: false,
	219	provenance: baseProvenance("#/paths/~1events~1{eventId}/parameters/0"),
	220	});
	221
	222	put(catalog.symbols as Record<typeof queryParamId, CatalogV1["symbols"][typeof queryParamId]>, queryParamId, {
	223	id: queryParamId,
	224	kind: "parameter",
	225	name: input.collideIds ? "id" : "sendUpdates",
	226	location: "query",
	227	docs: {
	228	summary: "Notification mode",
	229	},
	230	schemaShapeId: stringShapeId,
	231	synthetic: false,
	232	provenance: baseProvenance("#/paths/~1events/parameters/0"),
	233	});
	234
	235	put(catalog.symbols as Record<typeof requestBodyId, CatalogV1["symbols"][typeof requestBodyId]>, requestBodyId, {
	236	id: requestBodyId,
	237	kind: "requestBody",
	238	required: true,
	239	docs: {
	240	summary: "Event payload",
	241	},
	242	contents: [
	243	{
	244	mediaType: "application/json",
	245	shapeId: bodyShapeId,
	246	exampleIds: [exampleId],
	247	},
	248	],
	249	synthetic: false,
	250	provenance: baseProvenance("#/paths/~1events/requestBody"),
	251	});
	252
	253	put(catalog.symbols as Record<typeof responseId, CatalogV1["symbols"][typeof responseId]>, responseId, {
	254	id: responseId,
	255	kind: "response",
	256	docs: {
	257	summary: "Updated event",
	258	},
	259	contents: [
	260	{
	261	mediaType: "application/json",
	262	shapeId: resultShapeId,
	263	},
	264	],
	265	synthetic: false,
	266	provenance: baseProvenance("#/paths/~1events/responses/200"),
	267	});
	268
	269	put(catalog.responseSets as Record<typeof responseSetId, CatalogV1["responseSets"][typeof responseSetId]>, responseSetId, {
	270	id: responseSetId,
	271	variants: [
	272	{
	273	match: {
	274	kind: "exact",
	275	status: 200,
	276	},
	277	responseId,
	278	traits: ["success"],
	279	},
	280	],
	281	synthetic: false,
	282	provenance: baseProvenance("#/paths/~1events/responses"),
	283	});
	284
	285	put(catalog.executables as Record<typeof executableId, CatalogV1["executables"][typeof executableId]>, executableId, {
	286	id: executableId,
	287	protocol: "http",
	288	capabilityId,
	289	scopeId,
	290	method: input.method ?? "PATCH",
	291	pathTemplate: "/calendars/{calendarId}/events/{eventId}",
	292	pathParameterIds: [calendarParamId, idPathParamId],
	293	queryParameterIds: [queryParamId],
	294	requestBodyId,
	295	responseSetId,
	296	synthetic: false,
	297	provenance: baseProvenance("#/paths/~1events/patch"),
	298	});
	299
	300	put(catalog.capabilities as Record<typeof capabilityId, CatalogV1["capabilities"][typeof capabilityId]>, capabilityId, {
	301	id: capabilityId,
	302	serviceScopeId: scopeId,
	303	surface: {
	304	toolPath: ["google", "calendar", "events", "update"],
	305	title: "Update event",
	306	summary: "Update a calendar event.",
	307	description: "Updates an existing event by ID.",
	308	tags: ["calendar", "events"],
	309	},
	310	semantics: {
	311	effect: "write",
	312	safe: false,
	313	idempotent: false,
	314	destructive: false,
	315	},
	316	auth: {
	317	kind: "scheme",
	318	schemeId: authSchemeId,
	319	scopes: ["calendar.events"],
	320	},
	321	interaction: {
	322	approval: {
	323	mayRequire: true,
	324	reasons: ["write"],
	325	},
	326	elicitation: {
	327	mayRequest: false,
	328	},
	329	resume: {
	330	supported: true,
	331	},
	332	},
	333	executableIds: [executableId],
	334	preferredExecutableId: executableId,
	335	synthetic: false,
	336	provenance: baseProvenance("#/paths/~1events/patch"),
	337	});
	338
	339	return catalog;
	340	};
	341
	342	const createGraphqlCatalog = (): CatalogV1 => {
	343	const catalog = createEmptyCatalogV1();
	344
	345	const resourceId = ResourceIdSchema.make("res_graphql");
	346	const scopeId = ScopeIdSchema.make("scope_graphql_service");
	347	const argShapeId = ShapeSymbolIdSchema.make("shape_graphql_args");
	348	const inputShapeId = ShapeSymbolIdSchema.make("shape_graphql_input");
	349	const selectShapeId = ShapeSymbolIdSchema.make("shape_graphql_select");
	350	const resultShapeId = ShapeSymbolIdSchema.make("shape_graphql_result");
	351	const stringShapeId = ShapeSymbolIdSchema.make("shape_graphql_string");
	352	const responseId = ResponseSymbolIdSchema.make("sym_graphql_response");
	353	const responseSetId = ResponseSetIdSchema.make("response_set_graphql");
	354	const executableId = ExecutableIdSchema.make("exec_graphql_update");
	355	const capabilityId = CapabilityIdSchema.make("cap_graphql_update");
	356
	357	put(catalog.documents as Record<typeof docId, CatalogV1["documents"][typeof docId]>, docId, {
	358	id: docId,
	359	kind: "graphql-schema",
	360	title: "GraphQL schema",
	361	fetchedAt: "2026-03-14T00:00:00.000Z",
	362	rawRef: "memory://graphql/schema.json",
	363	});
	364
	365	put(catalog.resources as Record<typeof resourceId, CatalogV1["resources"][typeof resourceId]>, resourceId, {
	366	id: resourceId,
	367	documentId: docId,
	368	canonicalUri: "https://example.test/graphql",
	369	baseUri: "https://example.test/graphql",
	370	anchors: {},
	371	dynamicAnchors: {},
	372	synthetic: false,
	373	provenance: baseProvenance("#"),
	374	});
	375
	376	put(catalog.scopes as Record<typeof scopeId, CatalogV1["scopes"][typeof scopeId]>, scopeId, {
	377	id: scopeId,
	378	kind: "service",
	379	name: "GraphQL",
	380	synthetic: false,
	381	provenance: baseProvenance("#/schema"),
	382	});
	383
	384	put(catalog.symbols as Record<typeof stringShapeId, CatalogV1["symbols"][typeof stringShapeId]>, stringShapeId, {
	385	id: stringShapeId,
	386	kind: "shape",
	387	resourceId,
	388	title: "String",
	389	node: {
	390	type: "scalar",
	391	scalar: "string",
	392	},
	393	synthetic: false,
	394	provenance: baseProvenance("#/$defs/String"),
	395	});
	396
	397	put(catalog.symbols as Record<typeof inputShapeId, CatalogV1["symbols"][typeof inputShapeId]>, inputShapeId, {
	398	id: inputShapeId,
	399	kind: "shape",
	400	resourceId,
	401	title: "UserInput",
	402	node: {
	403	type: "object",
	404	fields: {
	405	name: {
	406	shapeId: stringShapeId,
	407	},
	408	},
	409	additionalProperties: false,
	410	},
	411	synthetic: false,
	412	provenance: baseProvenance("#/$defs/UserInput"),
	413	});
	414
	415	put(catalog.symbols as Record<typeof argShapeId, CatalogV1["symbols"][typeof argShapeId]>, argShapeId, {
	416	id: argShapeId,
	417	kind: "shape",
	418	resourceId,
	419	title: "UpdateUserArgs",
	420	node: {
	421	type: "object",
	422	fields: {
	423	id: {
	424	shapeId: stringShapeId,
	425	},
	426	input: {
	427	shapeId: inputShapeId,
	428	},
	429	},
	430	required: ["id", "input"],
	431	additionalProperties: false,
	432	},
	433	synthetic: false,
	434	provenance: baseProvenance("#/$defs/UpdateUserArgs"),
	435	});
	436
	437	put(catalog.symbols as Record<typeof selectShapeId, CatalogV1["symbols"][typeof selectShapeId]>, selectShapeId, {
	438	id: selectShapeId,
	439	kind: "shape",
	440	resourceId,
	441	title: "UserSelection",
	442	node: {
	443	type: "object",
	444	fields: {
	445	id: {
	446	shapeId: stringShapeId,
	447	},
	448	name: {
	449	shapeId: stringShapeId,
	450	},
	451	},
	452	additionalProperties: false,
	453	},
	454	synthetic: false,
	455	provenance: baseProvenance("#/$defs/UserSelection"),
	456	});
	457
	458	put(catalog.symbols as Record<typeof resultShapeId, CatalogV1["symbols"][typeof resultShapeId]>, resultShapeId, {
	459	id: resultShapeId,
	460	kind: "shape",
	461	resourceId,
	462	title: "User",
	463	node: {
	464	type: "object",
	465	fields: {
	466	id: {
	467	shapeId: stringShapeId,
	468	},
	469	name: {
	470	shapeId: stringShapeId,
	471	},
	472	},
	473	required: ["id"],
	474	additionalProperties: false,
	475	},
	476	synthetic: false,
	477	provenance: baseProvenance("#/$defs/User"),
	478	});
	479
	480	put(catalog.symbols as Record<typeof responseId, CatalogV1["symbols"][typeof responseId]>, responseId, {
	481	id: responseId,
	482	kind: "response",
	483	contents: [
	484	{
	485	mediaType: "application/json",
	486	shapeId: resultShapeId,
	487	},
	488	],
	489	synthetic: false,
	490	provenance: baseProvenance("#/responses/default"),
	491	});
	492
	493	put(catalog.responseSets as Record<typeof responseSetId, CatalogV1["responseSets"][typeof responseSetId]>, responseSetId, {
	494	id: responseSetId,
	495	variants: [
	496	{
	497	match: {
	498	kind: "default",
	499	},
	500	responseId,
	501	traits: ["success"],
	502	},
	503	],
	504	synthetic: false,
	505	provenance: baseProvenance("#/responses"),
	506	});
	507
	508	put(catalog.executables as Record<typeof executableId, CatalogV1["executables"][typeof executableId]>, executableId, {
	509	id: executableId,
	510	protocol: "graphql",
	511	capabilityId,
	512	scopeId,
	513	toolKind: "field",
	514	operationType: "mutation",
	515	rootField: "updateUser",
	516	argumentShapeId: argShapeId,
	517	resultShapeId,
	518	selectionShapeId: selectShapeId,
	519	selectionMode: "caller",
	520	responseSetId,
	521	synthetic: false,
	522	provenance: baseProvenance("#/mutations/updateUser"),
	523	});
	524
	525	put(catalog.capabilities as Record<typeof capabilityId, CatalogV1["capabilities"][typeof capabilityId]>, capabilityId, {
	526	id: capabilityId,
	527	serviceScopeId: scopeId,
	528	surface: {
	529	toolPath: ["graphql", "users", "update"],
	530	title: "Update user",
	531	summary: "Update a user.",
	532	},
	533	semantics: {
	534	effect: "write",
	535	},
	536	auth: {
	537	kind: "none",
	538	},
	539	interaction: {
	540	approval: {
	541	mayRequire: true,
	542	reasons: ["write"],
	543	},
	544	elicitation: {
	545	mayRequest: false,
	546	},
	547	resume: {
	548	supported: false,
	549	},
	550	},
	551	executableIds: [executableId],
	552	preferredExecutableId: executableId,
	553	synthetic: false,
	554	provenance: baseProvenance("#/mutations/updateUser"),
	555	});
	556
	557	return catalog;
	558	};
	559
	560	describe("IR catalog", () => {
	561	it("decodes a snapshot through the canonical schema", () => {
	562	const catalog = createHttpCatalog();
	563	const snapshot = createCatalogSnapshotV1({
	564	import: {
	565	sourceKind: "openapi",
	566	adapterKey: "openapi",
	567	importerVersion: "1.0.0",
	568	importedAt: "2026-03-14T00:00:00.000Z",
	569	sourceConfigHash: "hash_source",
	570	},
	571	catalog,
	572	});
	573
	574	const decoded = decodeCatalogSnapshotV1(snapshot);
	575	expect(decoded.version).toBe("ir.v1.snapshot");
	576	expect(decoded.catalog.capabilities[CapabilityIdSchema.make("cap_events_update")]?.surface.title).toBe(
	577	"Update event",
	578	);
	579	});
	580
	581	it("merges fragments and emits diagnostics on conflicting IDs", () => {
	582	const fragmentA: CatalogFragmentV1 = {
	583	version: "ir.v1.fragment",
	584	documents: {
	585	[docId]: {
	586	id: docId,
	587	kind: "openapi",
	588	title: "A",
	589	fetchedAt: "2026-03-14T00:00:00.000Z",
	590	rawRef: "memory://a",
	591	},
	592	},
	593	};
	594	const fragmentB: CatalogFragmentV1 = {
	595	version: "ir.v1.fragment",
	596	documents: {
	597	[docId]: {
	598	id: docId,
	599	kind: "openapi",
	600	title: "B",
	601	fetchedAt: "2026-03-14T00:00:00.000Z",
	602	rawRef: "memory://b",
	603	},
	604	},
	605	};
	606
	607	const merged = mergeCatalogFragments([fragmentA, fragmentB]);
	608	expect(merged.documents[docId]?.title).toBe("A");
	609	expect(Object.values(merged.diagnostics).some((diagnostic) => diagnostic.code === "merge_conflict_preserved_first")).toBe(true);
	610	});
	611
	612	it("reports invariant violations for unresolved shapes without diagnostics", () => {
	613	const catalog = createEmptyCatalogV1();
	614	const shapeId = ShapeSymbolIdSchema.make("shape_unresolved");
	615
	616	put(catalog.documents as Record<typeof docId, CatalogV1["documents"][typeof docId]>, docId, {
	617	id: docId,
	618	kind: "custom",
	619	fetchedAt: "2026-03-14T00:00:00.000Z",
	620	rawRef: "memory://custom",
	621	});
	622
	623	put(catalog.symbols as Record<typeof shapeId, CatalogV1["symbols"][typeof shapeId]>, shapeId, {
	624	id: shapeId,
	625	kind: "shape",
	626	title: "Unresolved",
	627	node: {
	628	type: "unknown",
	629	reason: "unresolved reference #/components/schemas/Missing",
	630	},
	631	synthetic: false,
	632	provenance: baseProvenance("#/components/schemas/Missing"),
	633	});
	634
	635	const violations = validateCatalogInvariants(catalog);
	636	expect(violations.map((violation) => violation.code)).toContain("missing_resource_context");
	637	expect(violations.map((violation) => violation.code)).toContain("missing_unresolved_ref_diagnostic");
	638	});
	639
	640	it("projects HTTP capabilities into ergonomic call and result shapes", () => {
	641	const projected = projectCatalogForAgentSdk({
	642	catalog: createHttpCatalog(),
	643	});
	644
	645	const descriptor = projected.toolDescriptors[CapabilityIdSchema.make("cap_events_update")];
	646	expect(descriptor.toolPath).toEqual(["google", "calendar", "events", "update"]);
	647
	648	const callShape = projected.catalog.symbols[descriptor.callShapeId];
	649	expect(callShape?.kind).toBe("shape");
	650	if (callShape?.kind !== "shape" \|\| callShape.node.type !== "object") {
	651	throw new Error("Expected projected call shape object");
	652	}
	653
	654	expect(Object.keys(callShape.node.fields)).toEqual([
	655	"calendarId",
	656	"eventId",
	657	"sendUpdates",
	658	"body",
	659	]);
	660	expect(callShape.node.required).toEqual(["calendarId", "eventId", "body"]);
	661
	662	const resultShape = descriptor.resultShapeId
	663	? projected.catalog.symbols[descriptor.resultShapeId]
	664	: undefined;
	665	if (resultShape?.kind !== "shape" \|\| resultShape.node.type !== "object") {
	666	throw new Error("Expected projected HTTP result envelope");
	667	}
	668	expect(Object.keys(resultShape.node.fields)).toEqual(["data", "error", "headers", "status"]);
	669	expectNullableShapeContains(
	670	projected.catalog,
	671	resultShape.node.fields.data.shapeId,
	672	ShapeSymbolIdSchema.make("shape_event_result"),
	673	);
	674
	675	const searchDoc = projected.searchDocs[CapabilityIdSchema.make("cap_events_update")];
	676	expect(searchDoc.authHints).toContain("oauth2");
	677	expect(searchDoc.tags).toEqual(["calendar", "events"]);
	678	});
	679
	680	it("groups colliding HTTP parameter names into path/query containers", () => {
	681	const projected = projectCatalogForAgentSdk({
	682	catalog: createHttpCatalog({ collideIds: true }),
	683	});
	684
	685	const descriptor = projected.toolDescriptors[CapabilityIdSchema.make("cap_events_update")];
	686	const callShape = projected.catalog.symbols[descriptor.callShapeId];
	687	if (callShape?.kind !== "shape" \|\| callShape.node.type !== "object") {
	688	throw new Error("Expected projected call shape object");
	689	}
	690
	691	expect(Object.keys(callShape.node.fields)).toContain("path");
	692	expect(Object.keys(callShape.node.fields)).toContain("query");
	693	expect(Object.keys(callShape.node.fields)).not.toContain("id");
	694	expect(Object.values(projected.catalog.diagnostics).some((diagnostic) => diagnostic.code === "projection_collision_grouped_fields")).toBe(true);
	695	});
	696
	697	it("keeps GraphQL selection explicit for caller-driven outputs", () => {
	698	const projected = projectCatalogForAgentSdk({
	699	catalog: createGraphqlCatalog(),
	700	});
	701
	702	const descriptor = projected.toolDescriptors[CapabilityIdSchema.make("cap_graphql_update")];
	703	const callShape = projected.catalog.symbols[descriptor.callShapeId];
	704	if (callShape?.kind !== "shape" \|\| callShape.node.type !== "object") {
	705	throw new Error("Expected projected GraphQL call shape object");
	706	}
	707
	708	expect(Object.keys(callShape.node.fields)).toEqual(["id", "input", "select"]);
	709	const resultShape = descriptor.resultShapeId
	710	? projected.catalog.symbols[descriptor.resultShapeId]
	711	: undefined;
	712	if (resultShape?.kind !== "shape" \|\| resultShape.node.type !== "object") {
	713	throw new Error("Expected projected GraphQL result envelope");
	714	}
	715	expect(Object.keys(resultShape.node.fields)).toEqual(["data", "error", "headers", "status"]);
	716	expectNullableShapeContains(
	717	projected.catalog,
	718	resultShape.node.fields.data.shapeId,
	719	ShapeSymbolIdSchema.make("shape_graphql_result"),
	720	);
	721	});
	722
	723	it("builds inspect views and invocation plans from the projected graph", () => {
	724	const projected = projectCatalogForAgentSdk({
	725	catalog: createHttpCatalog(),
	726	});
	727	const capabilityId = CapabilityIdSchema.make("cap_events_update");
	728	const descriptor = projected.toolDescriptors[capabilityId];
	729	const shallow = projectSymbolShallowView(projected.catalog, descriptor.callShapeId);
	730	const expanded = projectSymbolExpandedView(projected.catalog, descriptor.callShapeId);
	731	const plan = buildInvocationPlan({
	732	catalog: projected.catalog,
	733	capabilityId,
	734	connectionBindingId: "binding_primary",
	735	resolvedEndpoint: "https://example.test",
	736	requestPlan: {
	737	method: "PATCH",
	738	path: "/calendars/primary/events/abc",
	739	},
	740	});
	741
	742	expect(shallow.edges.some((edge) => edge.label === "field:body")).toBe(true);
	743	expect(expanded.symbol.id).toBe(descriptor.callShapeId);
	744	expect(plan.connectionBindingId).toBe("binding_primary");
	745	expect(plan.resolvedScopeChain).toEqual([ScopeIdSchema.make("scope_service")]);
	746	expect(plan.resolvedInteraction?.requiresApproval).toBe(true);
	747	});
	748	});

packages/kernel/ir/src/catalog.ts+2018−0

@@ -0,0 +1,2018 @@
	1	import { sha256Hex } from "@executor/codemode-core";
	2	import * as ParseResult from "effect/ParseResult";
	3	import { Schema } from "effect";
	4
	5	import {
	6	CapabilityIdSchema,
	7	type CapabilityId,
	8	DiagnosticIdSchema,
	9	type DiagnosticId,
	10	DocumentIdSchema,
	11	type DocumentId,
	12	ExecutableIdSchema,
	13	type ExecutableId,
	14	ExampleSymbolIdSchema,
	15	type ExampleSymbolId,
	16	HeaderSymbolIdSchema,
	17	type HeaderSymbolId,
	18	ParameterSymbolIdSchema,
	19	type ParameterSymbolId,
	20	type RequestBodySymbolId,
	21	ResourceIdSchema,
	22	type ResourceId,
	23	type ResponseSymbolId,
	24	type ResponseSetId,
	25	ScopeIdSchema,
	26	type ScopeId,
	27	type ShapeSymbolId,
	28	ShapeSymbolIdSchema,
	29	type SymbolId,
	30	} from "./ids";
	31	import {
	32	CatalogFragmentV1Schema,
	33	type CatalogFragmentV1,
	34	CatalogSnapshotV1Schema,
	35	CatalogV1Schema,
	36	type CatalogV1,
	37	type Capability,
	38	type ContentSpec,
	39	type DocumentationBlock,
	40	type Executable,
	41	type GraphQLExecutable,
	42	type HttpExecutable,
	43	type ImportDiagnostic,
	44	type ImportMetadata,
	45	type InteractionSpec,
	46	type McpExecutable,
	47	type ParameterSymbol,
	48	type HeaderSymbol,
	49	type ResponseSet,
	50	type ResponseSymbol,
	51	type Scope,
	52	type ScopeDefaults,
	53	type ShapeSymbol,
	54	type StatusMatch,
	55	type Symbol as IrSymbol,
	56	} from "./model";
	57
	58	export interface ToolDescriptor {
	59	toolPath: string[];
	60	capabilityId: CapabilityId;
	61	title?: string;
	62	summary?: string;
	63	effect: Capability["semantics"]["effect"];
	64	interaction: {
	65	mayRequireApproval: boolean;
	66	mayElicit: boolean;
	67	};
	68	callShapeId: ShapeSymbolId;
	69	resultShapeId?: ShapeSymbolId;
	70	responseSetId: ResponseSetId;
	71	diagnosticCounts: {
	72	warning: number;
	73	error: number;
	74	};
	75	}
	76
	77	export interface ToolSearchDoc {
	78	capabilityId: CapabilityId;
	79	toolPath: string[];
	80	title?: string;
	81	summary?: string;
	82	tags?: string[];
	83	protocolHints: string[];
	84	authHints: string[];
	85	effect: Capability["semantics"]["effect"];
	86	}
	87
	88	export interface CapabilitySummaryView {
	89	capabilityId: CapabilityId;
	90	toolPath: string[];
	91	summary?: string;
	92	executableIds: ExecutableId[];
	93	auth: Capability["auth"];
	94	interaction: InteractionSpec;
	95	callShapeId: ShapeSymbolId;
	96	resultShapeId?: ShapeSymbolId;
	97	responseSetId: ResponseSetId;
	98	diagnosticIds?: DiagnosticId[];
	99	}
	100
	101	export interface SymbolShallowView {
	102	symbolId: SymbolId;
	103	kind: IrSymbol["kind"];
	104	title?: string;
	105	summary?: string;
	106	edges: Array<{ label: string; targetId: SymbolId }>;
	107	}
	108
	109	export interface SymbolExpandedView {
	110	symbolId: SymbolId;
	111	symbol: IrSymbol;
	112	diagnostics?: ImportDiagnostic[];
	113	}
	114
	115	export interface InvocationPlan {
	116	capabilityId: CapabilityId;
	117	executableId: ExecutableId;
	118	connectionBindingId: string;
	119	resolvedScopeChain: ScopeId[];
	120	resolvedEndpoint?: string;
	121	resolvedAuth?: unknown;
	122	resolvedInteraction?: {
	123	requiresApproval: boolean;
	124	mayPauseForElicitation: boolean;
	125	resumable: boolean;
	126	};
	127	requestPlan: unknown;
	128	provenance: CatalogV1["capabilities"][CapabilityId]["provenance"];
	129	}
	130
	131	export interface ProjectedCatalog {
	132	catalog: CatalogV1;
	133	toolDescriptors: Record<CapabilityId, ToolDescriptor>;
	134	searchDocs: Record<CapabilityId, ToolSearchDoc>;
	135	capabilityViews: Record<CapabilityId, CapabilitySummaryView>;
	136	}
	137
	138	export interface CatalogInvariantViolation {
	139	code:
	140	\| "missing_symbol_provenance"
	141	\| "missing_entity_provenance"
	142	\| "missing_document"
	143	\| "missing_provenance_document"
	144	\| "missing_resource_context"
	145	\| "missing_reference_target"
	146	\| "missing_unresolved_ref_diagnostic"
	147	\| "missing_executable"
	148	\| "missing_response_set"
	149	\| "missing_scope"
	150	\| "missing_service_scope"
	151	\| "invalid_preferred_executable"
	152	\| "missing_projection_synthetic_marker";
	153	message: string;
	154	entityId?: string;
	155	}
	156
	157	export type DecodeCatalogError = Error;
	158
	159	type MutableScopeDefaults = {
	160	servers?: ScopeDefaults["servers"];
	161	auth?: ScopeDefaults["auth"];
	162	parameterIds?: ParameterSymbolId[];
	163	headerIds?: HeaderSymbolId[];
	164	variables?: Record<string, string>;
	165	};
	166
	167	type CatalogSnapshotV1 = {
	168	version: "ir.v1.snapshot";
	169	import: ImportMetadata;
	170	catalog: CatalogV1;
	171	};
	172
	173	const decodeCatalogSync = Schema.decodeUnknownSync(
	174	CatalogV1Schema as Schema.Schema<CatalogV1, unknown, never>,
	175	);
	176	const decodeCatalogSnapshotSync = Schema.decodeUnknownSync(
	177	CatalogSnapshotV1Schema as Schema.Schema<CatalogSnapshotV1, unknown, never>,
	178	);
	179	const decodeCatalogFragmentSync = Schema.decodeUnknownSync(
	180	CatalogFragmentV1Schema as Schema.Schema<CatalogFragmentV1, unknown, never>,
	181	);
	182
	183	const stableStringify = (value: unknown): string => {
	184	if (value === null \|\| typeof value !== "object") {
	185	return JSON.stringify(value);
	186	}
	187
	188	if (Array.isArray(value)) {
	189	return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
	190	}
	191
	192	const entries = Object.entries(value as Record<string, unknown>)
	193	.sort(([left], [right]) => left.localeCompare(right))
	194	.map(([key, entry]) => `${JSON.stringify(key)}:${stableStringify(entry)}`);
	195	return `{${entries.join(",")}}`;
	196	};
	197
	198	const stableHash = (value: unknown): string => sha256Hex(stableStringify(value)).slice(0, 16);
	199
	200	const unique = <T>(values: readonly T[]): T[] => [...new Set(values)];
	201
	202	const cloneCatalog = (catalog: CatalogV1): CatalogV1 => ({
	203	version: catalog.version,
	204	documents: { ...catalog.documents },
	205	resources: { ...catalog.resources },
	206	scopes: { ...catalog.scopes },
	207	symbols: { ...catalog.symbols },
	208	capabilities: { ...catalog.capabilities },
	209	executables: { ...catalog.executables },
	210	responseSets: { ...catalog.responseSets },
	211	diagnostics: { ...catalog.diagnostics },
	212	});
	213
	214	const mutableRecord = <K extends string, V>(value: Readonly<Record<K, V>>): Record<K, V> =>
	215	value as unknown as Record<K, V>;
	216
	217	const createStableEntityId = <A extends string>(
	218	make: (value: string) => A,
	219	prefix: string,
	220	value: unknown,
	221	): A => make(`${prefix}_${stableHash(value)}`);
	222
	223	const emptyCatalog = (): CatalogV1 => ({
	224	version: "ir.v1",
	225	documents: {},
	226	resources: {},
	227	scopes: {},
	228	symbols: {},
	229	capabilities: {},
	230	executables: {},
	231	responseSets: {},
	232	diagnostics: {},
	233	});
	234
	235	const authHintStrings = (catalog: CatalogV1, auth: Capability["auth"]): string[] => {
	236	switch (auth.kind) {
	237	case "none":
	238	return ["none"];
	239	case "scheme": {
	240	const scheme = catalog.symbols[auth.schemeId];
	241	if (!scheme \|\| scheme.kind !== "securityScheme") {
	242	return ["unknown"];
	243	}
	244	return [
	245	scheme.schemeType,
	246	...((auth.scopes ?? []).map((scope: string) => `scope:${scope}`)),
	247	];
	248	}
	249	case "allOf":
	250	case "anyOf":
	251	return unique(auth.items.flatMap((item: Capability["auth"]) => authHintStrings(catalog, item)));
	252	}
	253	};
	254
	255	const docsSummary = (docs: DocumentationBlock \| undefined): string \| undefined =>
	256	docs?.summary ?? docs?.description;
	257
	258	const getShape = (catalog: CatalogV1, shapeId: ShapeSymbolId): ShapeSymbol \| undefined => {
	259	const symbol = catalog.symbols[shapeId];
	260	return symbol && symbol.kind === "shape" ? symbol : undefined;
	261	};
	262
	263	const getParameter = (
	264	catalog: CatalogV1,
	265	parameterId: ParameterSymbolId,
	266	): ParameterSymbol \| undefined => {
	267	const symbol = catalog.symbols[parameterId];
	268	return symbol && symbol.kind === "parameter" ? symbol : undefined;
	269	};
	270
	271	const getResponseSymbol = (
	272	catalog: CatalogV1,
	273	responseId: ResponseSymbolId,
	274	): ResponseSymbol \| undefined => {
	275	const symbol = catalog.symbols[responseId];
	276	return symbol && symbol.kind === "response" ? symbol : undefined;
	277	};
	278
	279	const getHeader = (
	280	catalog: CatalogV1,
	281	headerId: HeaderSymbolId,
	282	): HeaderSymbol \| undefined => {
	283	const symbol = catalog.symbols[headerId];
	284	return symbol && symbol.kind === "header" ? symbol : undefined;
	285	};
	286
	287	const scopeChain = (catalog: CatalogV1, scopeId: ScopeId): Scope[] => {
	288	const chain: Scope[] = [];
	289	let currentId: ScopeId \| undefined = scopeId;
	290
	291	while (currentId) {
	292	const scope: Scope \| undefined = catalog.scopes[currentId];
	293	if (!scope) {
	294	break;
	295	}
	296	chain.unshift(scope);
	297	currentId = scope.parentId;
	298	}
	299
	300	return chain;
	301	};
	302
	303	const mergeScopeDefaults = (chain: readonly Scope[]): ScopeDefaults => {
	304	const merged: MutableScopeDefaults = {};
	305
	306	for (const scope of chain) {
	307	const defaults = scope.defaults;
	308	if (!defaults) {
	309	continue;
	310	}
	311
	312	if (defaults.servers) {
	313	merged.servers = [...defaults.servers];
	314	}
	315
	316	if (defaults.auth) {
	317	merged.auth = defaults.auth;
	318	}
	319
	320	if (defaults.parameterIds) {
	321	merged.parameterIds = unique([
	322	...(merged.parameterIds ?? []),
	323	...defaults.parameterIds,
	324	]);
	325	}
	326
	327	if (defaults.headerIds) {
	328	merged.headerIds = unique([
	329	...(merged.headerIds ?? []),
	330	...defaults.headerIds,
	331	]);
	332	}
	333
	334	if (defaults.variables) {
	335	merged.variables = {
	336	...(merged.variables ?? {}),
	337	...defaults.variables,
	338	};
	339	}
	340	}
	341
	342	return merged as ScopeDefaults;
	343	};
	344
	345	const isJsonMediaType = (mediaType: string): boolean => {
	346	const normalized = mediaType.trim().toLowerCase();
	347	return normalized === "application/json"
	348	\|\| normalized.endsWith("+json")
	349	\|\| normalized === "text/json";
	350	};
	351
	352	const createDiagnostic = (
	353	catalog: CatalogV1,
	354	input: Omit<ImportDiagnostic, "id"> & { idSeed: unknown },
	355	): DiagnosticId => {
	356	const diagnosticId = createStableEntityId(
	357	DiagnosticIdSchema.make,
	358	"diag",
	359	input.idSeed,
	360	);
	361
	362	mutableRecord(catalog.diagnostics)[diagnosticId] = {
	363	id: diagnosticId,
	364	level: input.level,
	365	code: input.code,
	366	message: input.message,
	367	...(input.relatedSymbolIds ? { relatedSymbolIds: input.relatedSymbolIds } : {}),
	368	provenance: input.provenance,
	369	};
	370
	371	return diagnosticId;
	372	};
	373
	374	const ensureProjectionResource = (
	375	catalog: CatalogV1,
	376	capability: Capability,
	377	): ResourceId => {
	378	const resourceId = createStableEntityId(
	379	ResourceIdSchema.make,
	380	"res",
	381	{
	382	kind: "projection",
	383	capabilityId: capability.id,
	384	},
	385	);
	386
	387	if (!catalog.resources[resourceId]) {
	388	const serviceScope = catalog.scopes[capability.serviceScopeId];
	389	const documentId = serviceScope?.provenance[0]?.documentId
	390	?? DocumentIdSchema.make(`doc_projection_${stableHash(capability.id)}`);
	391
	392	if (!catalog.documents[documentId]) {
	393	mutableRecord(catalog.documents)[documentId] = {
	394	id: documentId,
	395	kind: "custom",
	396	title: `Projection resource for ${capability.id}`,
	397	fetchedAt: new Date(0).toISOString(),
	398	rawRef: `synthetic://projection/${capability.id}`,
	399	};
	400	}
	401
	402	mutableRecord(catalog.resources)[resourceId] = {
	403	id: resourceId,
	404	documentId,
	405	canonicalUri: `synthetic://projection/${capability.id}`,
	406	baseUri: `synthetic://projection/${capability.id}`,
	407	anchors: {},
	408	dynamicAnchors: {},
	409	synthetic: true,
	410	provenance: capability.provenance,
	411	};
	412
	413	createDiagnostic(catalog, {
	414	idSeed: {
	415	code: "synthetic_resource_context_created",
	416	capabilityId: capability.id,
	417	},
	418	level: "info",
	419	code: "synthetic_resource_context_created",
	420	message: `Created synthetic projection resource for ${capability.id}`,
	421	provenance: capability.provenance,
	422	});
	423	}
	424
	425	return resourceId;
	426	};
	427
	428	const createSyntheticShape = (
	429	catalog: CatalogV1,
	430	input: {
	431	capability: Capability;
	432	label: string;
	433	node: ShapeSymbol["node"];
	434	title?: string;
	435	docs?: DocumentationBlock;
	436	diagnostic?:
	437	\| {
	438	level: ImportDiagnostic["level"];
	439	code: ImportDiagnostic["code"];
	440	message: string;
	441	relatedSymbolIds?: SymbolId[];
	442	}
	443	\| undefined;
	444	},
	445	): ShapeSymbolId => {
	446	const resourceId = ensureProjectionResource(catalog, input.capability);
	447	const shapeId = createStableEntityId(
	448	ShapeSymbolIdSchema.make,
	449	"shape",
	450	{
	451	capabilityId: input.capability.id,
	452	label: input.label,
	453	node: input.node,
	454	},
	455	);
	456
	457	if (!catalog.symbols[shapeId]) {
	458	const diagnostics = input.diagnostic
	459	? [
	460	createDiagnostic(catalog, {
	461	idSeed: {
	462	code: input.diagnostic.code,
	463	shapeId,
	464	},
	465	level: input.diagnostic.level,
	466	code: input.diagnostic.code,
	467	message: input.diagnostic.message,
	468	...(input.diagnostic.relatedSymbolIds
	469	? { relatedSymbolIds: input.diagnostic.relatedSymbolIds }
	470	: {}),
	471	provenance: input.capability.provenance,
	472	}),
	473	]
	474	: undefined;
	475
	476	mutableRecord(catalog.symbols)[shapeId] = {
	477	id: shapeId,
	478	kind: "shape",
	479	resourceId,
	480	...(input.title ? { title: input.title } : {}),
	481	...(input.docs ? { docs: input.docs } : {}),
	482	node: input.node,
	483	synthetic: true,
	484	provenance: input.capability.provenance,
	485	...(diagnostics ? { diagnosticIds: diagnostics } : {}),
	486	};
	487	}
	488
	489	return shapeId;
	490	};
	491
	492	const contentShapeId = (
	493	catalog: CatalogV1,
	494	capability: Capability,
	495	contents: readonly ContentSpec[] \| undefined,
	496	label: string,
	497	): ShapeSymbolId \| undefined => {
	498	const shapeIds = unique(
	499	(contents ?? [])
	500	.map((content) => content.shapeId)
	501	.filter((shapeId): shapeId is ShapeSymbolId => shapeId !== undefined),
	502	);
	503
	504	if (shapeIds.length === 0) {
	505	return undefined;
	506	}
	507
	508	if (shapeIds.length === 1) {
	509	return shapeIds[0];
	510	}
	511
	512	return createSyntheticShape(catalog, {
	513	capability,
	514	label,
	515	title: `${capability.surface.title ?? capability.id} content union`,
	516	node: {
	517	type: "anyOf",
	518	items: shapeIds,
	519	},
	520	diagnostic: {
	521	level: "warning",
	522	code: "projection_result_shape_synthesized",
	523	message: `Synthesized content union for ${capability.id}`,
	524	relatedSymbolIds: shapeIds,
	525	},
	526	});
	527	};
	528
	529	const parameterShapeId = (
	530	catalog: CatalogV1,
	531	capability: Capability,
	532	parameter: ParameterSymbol,
	533	): ShapeSymbolId => {
	534	if (parameter.schemaShapeId) {
	535	return parameter.schemaShapeId;
	536	}
	537
	538	const contentShape = contentShapeId(
	539	catalog,
	540	capability,
	541	parameter.content,
	542	`parameter:${parameter.id}`,
	543	);
	544	if (contentShape) {
	545	return contentShape;
	546	}
	547
	548	return createSyntheticShape(catalog, {
	549	capability,
	550	label: `parameter:${parameter.id}:unknown`,
	551	title: parameter.name,
	552	docs: parameter.docs,
	553	node: {
	554	type: "unknown",
	555	reason: `Missing shape for parameter ${parameter.id}`,
	556	},
	557	diagnostic: {
	558	level: "warning",
	559	code: "projection_call_shape_synthesized",
	560	message: `Missing parameter shape for ${parameter.name}; using unknown`,
	561	relatedSymbolIds: [parameter.id],
	562	},
	563	});
	564	};
	565
	566	const requestBodyShapeId = (
	567	catalog: CatalogV1,
	568	capability: Capability,
	569	requestBodyId: RequestBodySymbolId \| undefined,
	570	): ShapeSymbolId \| undefined => {
	571	if (!requestBodyId) {
	572	return undefined;
	573	}
	574
	575	const requestBody = catalog.symbols[requestBodyId];
	576	if (!requestBody \|\| requestBody.kind !== "requestBody") {
	577	return undefined;
	578	}
	579
	580	return contentShapeId(
	581	catalog,
	582	capability,
	583	requestBody.contents,
	584	`requestBody:${requestBody.id}`,
	585	);
	586	};
	587
	588	const chooseExecutable = (catalog: CatalogV1, capability: Capability): Executable => {
	589	const preferredId = capability.preferredExecutableId;
	590	if (preferredId) {
	591	const preferred = catalog.executables[preferredId];
	592	if (preferred) {
	593	return preferred;
	594	}
	595	}
	596
	597	const executables = capability.executableIds
	598	.map((executableId) => catalog.executables[executableId])
	599	.filter((executable): executable is Executable => executable !== undefined);
	600
	601	if (executables.length === 0) {
	602	throw new Error(`Capability ${capability.id} has no executables`);
	603	}
	604
	605	return executables[0];
	606	};
	607
	608	const scoreStatusMatch = (match: StatusMatch): number => {
	609	switch (match.kind) {
	610	case "exact":
	611	return match.status === 200 ? 100 : match.status >= 200 && match.status < 300 ? 80 : 10;
	612	case "range":
	613	return match.value === "2XX" ? 60 : 5;
	614	case "default":
	615	return 40;
	616	}
	617	};
	618
	619	const responseContentCandidates = (
	620	response: ResponseSymbol,
	621	): Array<{ mediaType: string; shapeId: ShapeSymbolId }> =>
	622	(response.contents ?? [])
	623	.flatMap((content) =>
	624	content.shapeId ? [{ mediaType: content.mediaType, shapeId: content.shapeId }] : [],
	625	);
	626
	627	type RankedResponseVariantEntry = {
	628	variant: ResponseSet["variants"][number];
	629	response: ResponseSymbol;
	630	score: number;
	631	};
	632
	633	const responseVariantEntries = (
	634	catalog: CatalogV1,
	635	responseSet: ResponseSet,
	636	): RankedResponseVariantEntry[] =>
	637	[...responseSet.variants]
	638	.map((variant) => {
	639	const response = getResponseSymbol(catalog, variant.responseId);
	640	return response
	641	? {
	642	variant,
	643	response,
	644	score: scoreStatusMatch(variant.match),
	645	}
	646	: null;
	647	})
	648	.filter((entry): entry is RankedResponseVariantEntry => entry !== null);
	649
	650	const isSuccessStatusMatch = (match: StatusMatch): boolean => {
	651	switch (match.kind) {
	652	case "exact":
	653	return match.status >= 200 && match.status < 300;
	654	case "range":
	655	return match.value === "2XX";
	656	case "default":
	657	return false;
	658	}
	659	};
	660
	661	const contentShapeIdFromResponseEntries = (
	662	catalog: CatalogV1,
	663	capability: Capability,
	664	label: string,
	665	title: string,
	666	entries: readonly RankedResponseVariantEntry[],
	667	): ShapeSymbolId \| undefined => {
	668	const jsonCandidates = entries.flatMap(({ response }) =>
	669	responseContentCandidates(response).filter((candidate) => isJsonMediaType(candidate.mediaType)),
	670	);
	671
	672	if (jsonCandidates.length > 0) {
	673	return contentShapeId(
	674	catalog,
	675	capability,
	676	jsonCandidates.map((candidate) => ({
	677	mediaType: candidate.mediaType,
	678	shapeId: candidate.shapeId,
	679	})),
	680	`${label}:json`,
	681	);
	682	}
	683
	684	const fallbackShapeIds = unique(
	685	entries.flatMap(({ response }) =>
	686	responseContentCandidates(response).map((candidate) => candidate.shapeId),
	687	),
	688	);
	689
	690	if (fallbackShapeIds.length === 0) {
	691	return undefined;
	692	}
	693
	694	if (fallbackShapeIds.length === 1) {
	695	return fallbackShapeIds[0];
	696	}
	697
	698	return createSyntheticShape(catalog, {
	699	capability,
	700	label: `${label}:union`,
	701	title,
	702	node: {
	703	type: "anyOf",
	704	items: fallbackShapeIds,
	705	},
	706	diagnostic: {
	707	level: "warning",
	708	code: "multi_response_union_synthesized",
	709	message: `Synthesized response union for ${capability.id}`,
	710	relatedSymbolIds: fallbackShapeIds,
	711	},
	712	});
	713	};
	714
	715	const projectResultShapeFromResponses = (
	716	catalog: CatalogV1,
	717	capability: Capability,
	718	responseSet: ResponseSet,
	719	): ShapeSymbolId \| undefined =>
	720	contentShapeIdFromResponseEntries(
	721	catalog,
	722	capability,
	723	`responseSet:${responseSet.id}`,
	724	`${capability.surface.title ?? capability.id} result`,
	725	responseVariantEntries(catalog, responseSet).filter(({ variant }) => isSuccessStatusMatch(variant.match)),
	726	);
	727
	728	const projectErrorShapeFromResponses = (
	729	catalog: CatalogV1,
	730	capability: Capability,
	731	responseSet: ResponseSet,
	732	): ShapeSymbolId \| undefined =>
	733	contentShapeIdFromResponseEntries(
	734	catalog,
	735	capability,
	736	`responseSet:${responseSet.id}:error`,
	737	`${capability.surface.title ?? capability.id} error`,
	738	responseVariantEntries(catalog, responseSet).filter(({ variant }) => !isSuccessStatusMatch(variant.match)),
	739	);
	740
	741	const scalarShape = (
	742	catalog: CatalogV1,
	743	capability: Capability,
	744	input: {
	745	label: string;
	746	title: string;
	747	scalar: "string" \| "number" \| "integer" \| "boolean" \| "null" \| "bytes";
	748	},
	749	): ShapeSymbolId =>
	750	createSyntheticShape(catalog, {
	751	capability,
	752	label: input.label,
	753	title: input.title,
	754	node: {
	755	type: "scalar",
	756	scalar: input.scalar,
	757	},
	758	});
	759
	760	const constNullShape = (
	761	catalog: CatalogV1,
	762	capability: Capability,
	763	label: string,
	764	): ShapeSymbolId =>
	765	createSyntheticShape(catalog, {
	766	capability,
	767	label,
	768	title: "null",
	769	node: {
	770	type: "const",
	771	value: null,
	772	},
	773	});
	774
	775	const unknownShape = (
	776	catalog: CatalogV1,
	777	capability: Capability,
	778	input: {
	779	label: string;
	780	title: string;
	781	reason: string;
	782	},
	783	): ShapeSymbolId =>
	784	createSyntheticShape(catalog, {
	785	capability,
	786	label: input.label,
	787	title: input.title,
	788	node: {
	789	type: "unknown",
	790	reason: input.reason,
	791	},
	792	});
	793
	794	const nullableShape = (
	795	catalog: CatalogV1,
	796	capability: Capability,
	797	input: {
	798	label: string;
	799	title: string;
	800	baseShapeId: ShapeSymbolId;
	801	},
	802	): ShapeSymbolId => {
	803	const nullShapeId = constNullShape(catalog, capability, `${input.label}:null`);
	804	if (input.baseShapeId === nullShapeId) {
	805	return nullShapeId;
	806	}
	807
	808	return createSyntheticShape(catalog, {
	809	capability,
	810	label: `${input.label}:nullable`,
	811	title: input.title,
	812	node: {
	813	type: "anyOf",
	814	items: unique([input.baseShapeId, nullShapeId]),
	815	},
	816	});
	817	};
	818
	819	const headersShape = (
	820	catalog: CatalogV1,
	821	capability: Capability,
	822	label: string,
	823	): ShapeSymbolId => {
	824	const valueShapeId = scalarShape(catalog, capability, {
	825	label: `${label}:value`,
	826	title: "Header value",
	827	scalar: "string",
	828	});
	829
	830	return createSyntheticShape(catalog, {
	831	capability,
	832	label,
	833	title: "Response headers",
	834	node: {
	835	type: "object",
	836	fields: {},
	837	additionalProperties: valueShapeId,
	838	},
	839	});
	840	};
	841
	842	const shapeFieldShapeId = (
	843	catalog: CatalogV1,
	844	shapeId: ShapeSymbolId \| undefined,
	845	fieldName: string,
	846	seen = new Set<ShapeSymbolId>(),
	847	): ShapeSymbolId \| undefined => {
	848	if (!shapeId \|\| seen.has(shapeId)) {
	849	return undefined;
	850	}
	851
	852	const shape = getShape(catalog, shapeId);
	853	if (!shape) {
	854	return undefined;
	855	}
	856
	857	const nextSeen = new Set(seen);
	858	nextSeen.add(shapeId);
	859
	860	switch (shape.node.type) {
	861	case "ref":
	862	return shapeFieldShapeId(catalog, shape.node.target, fieldName, nextSeen);
	863	case "object":
	864	return shape.node.fields[fieldName]?.shapeId;
	865	case "allOf":
	866	for (const item of shape.node.items) {
	867	const found = shapeFieldShapeId(catalog, item, fieldName, nextSeen);
	868	if (found) {
	869	return found;
	870	}
	871	}
	872	return undefined;
	873	default:
	874	return undefined;
	875	}
	876	};
	877
	878	const projectExecutionResultShape = (
	879	catalog: CatalogV1,
	880	capability: Capability,
	881	executable: Executable,
	882	responseSet: ResponseSet,
	883	): ShapeSymbolId => {
	884	const genericDataShape = unknownShape(catalog, capability, {
	885	label: `executionResult:${capability.id}:data:unknown`,
	886	title: "Response data",
	887	reason: `Execution result data for ${capability.id} is not statically known`,
	888	});
	889	const genericErrorShape = unknownShape(catalog, capability, {
	890	label: `executionResult:${capability.id}:error:unknown`,
	891	title: "Response error",
	892	reason: `Execution result error for ${capability.id} is not statically known`,
	893	});
	894	const genericHeadersShape = headersShape(
	895	catalog,
	896	capability,
	897	`executionResult:${capability.id}:headers`,
	898	);
	899	const genericStatusShape = scalarShape(catalog, capability, {
	900	label: `executionResult:${capability.id}:status`,
	901	title: "Response status",
	902	scalar: "integer",
	903	});
	904
	905	let dataShapeId: ShapeSymbolId \| undefined;
	906	let errorShapeId: ShapeSymbolId \| undefined;
	907	let headersShapeId: ShapeSymbolId = genericHeadersShape;
	908	let statusShapeId: ShapeSymbolId = genericStatusShape;
	909
	910	switch (executable.protocol) {
	911	case "http":
	912	dataShapeId = projectResultShapeFromResponses(catalog, capability, responseSet);
	913	errorShapeId = projectErrorShapeFromResponses(catalog, capability, responseSet);
	914	break;
	915	case "graphql":
	916	dataShapeId =
	917	shapeFieldShapeId(catalog, executable.resultShapeId, "data")
	918	?? shapeFieldShapeId(catalog, executable.resultShapeId, "body")
	919	?? executable.resultShapeId;
	920	errorShapeId =
	921	shapeFieldShapeId(catalog, executable.resultShapeId, "error")
	922	?? shapeFieldShapeId(catalog, executable.resultShapeId, "errors");
	923	headersShapeId =
	924	shapeFieldShapeId(catalog, executable.resultShapeId, "headers")
	925	?? genericHeadersShape;
	926	statusShapeId =
	927	shapeFieldShapeId(catalog, executable.resultShapeId, "status")
	928	?? genericStatusShape;
	929	break;
	930	case "mcp":
	931	dataShapeId = executable.outputShapeId;
	932	errorShapeId = undefined;
	933	statusShapeId = constNullShape(
	934	catalog,
	935	capability,
	936	`executionResult:${capability.id}:status:null`,
	937	);
	938	break;
	939	}
	940
	941	const dataFieldShapeId = nullableShape(catalog, capability, {
	942	label: `executionResult:${capability.id}:data`,
	943	title: "Result data",
	944	baseShapeId: dataShapeId ?? genericDataShape,
	945	});
	946	const errorFieldShapeId = nullableShape(catalog, capability, {
	947	label: `executionResult:${capability.id}:error`,
	948	title: "Result error",
	949	baseShapeId: errorShapeId ?? genericErrorShape,
	950	});
	951	const statusFieldShapeId = nullableShape(catalog, capability, {
	952	label: `executionResult:${capability.id}:status`,
	953	title: "Result status",
	954	baseShapeId: statusShapeId,
	955	});
	956
	957	return createSyntheticShape(catalog, {
	958	capability,
	959	label: `executionResult:${capability.id}`,
	960	title: `${capability.surface.title ?? capability.id} result`,
	961	node: {
	962	type: "object",
	963	fields: {
	964	data: {
	965	shapeId: dataFieldShapeId,
	966	docs: {
	967	description: "Successful result payload when available.",
	968	},
	969	},
	970	error: {
	971	shapeId: errorFieldShapeId,
	972	docs: {
	973	description: "Error payload when the remote execution completed but failed.",
	974	},
	975	},
	976	headers: {
	977	shapeId: headersShapeId,
	978	docs: {
	979	description: "Response headers when available.",
	980	},
	981	},
	982	status: {
	983	shapeId: statusFieldShapeId,
	984	docs: {
	985	description: "Transport status code when available.",
	986	},
	987	},
	988	},
	989	required: ["data", "error", "headers", "status"],
	990	additionalProperties: false,
	991	},
	992	diagnostic: {
	993	level: "info",
	994	code: "projection_result_shape_synthesized",
	995	message: `Synthesized execution result envelope for ${capability.id}`,
	996	relatedSymbolIds: unique([
	997	dataFieldShapeId,
	998	errorFieldShapeId,
	999	headersShapeId,
	1000	statusFieldShapeId,
	1001	]),
	1002	},
	1003	});
	1004	};
	1005
	1006	const groupFieldShape = (
	1007	catalog: CatalogV1,
	1008	capability: Capability,
	1009	location: "path" \| "query" \| "headers" \| "cookies",
	1010	fields: Record<string, { shapeId: ShapeSymbolId; docs?: DocumentationBlock }>,
	1011	required: string[],
	1012	): ShapeSymbolId =>
	1013	createSyntheticShape(catalog, {
	1014	capability,
	1015	label: `group:${capability.id}:${location}`,
	1016	title: `${location} parameters`,
	1017	node: {
	1018	type: "object",
	1019	fields: Object.fromEntries(
	1020	Object.entries(fields).map(([name, field]) => [
	1021	name,
	1022	{
	1023	shapeId: field.shapeId,
	1024	...(field.docs ? { docs: field.docs } : {}),
	1025	},
	1026	]),
	1027	),
	1028	...(required.length > 0 ? { required } : {}),
	1029	additionalProperties: false,
	1030	},
	1031	});
	1032
	1033	const projectHttpCallShape = (
	1034	catalog: CatalogV1,
	1035	capability: Capability,
	1036	executable: HttpExecutable,
	1037	): ShapeSymbolId => {
	1038	const chain = scopeChain(catalog, executable.scopeId);
	1039	const defaults = mergeScopeDefaults(chain);
	1040
	1041	const byLocation: Record<
	1042	"path" \| "query" \| "header" \| "cookie",
	1043	ParameterSymbol[]
	1044	> = {
	1045	path: [],
	1046	query: [],
	1047	header: [],
	1048	cookie: [],
	1049	};
	1050
	1051	const pushParameter = (parameterId: ParameterSymbolId) => {
	1052	const parameter = getParameter(catalog, parameterId);
	1053	if (parameter) {
	1054	byLocation[parameter.location].push(parameter);
	1055	}
	1056	};
	1057
	1058	for (const parameterId of defaults.parameterIds ?? []) {
	1059	pushParameter(parameterId);
	1060	}
	1061	for (const parameterId of executable.pathParameterIds ?? []) {
	1062	pushParameter(parameterId);
	1063	}
	1064	for (const parameterId of executable.queryParameterIds ?? []) {
	1065	pushParameter(parameterId);
	1066	}
	1067	for (const parameterId of executable.headerParameterIds ?? []) {
	1068	pushParameter(parameterId);
	1069	}
	1070	for (const parameterId of executable.cookieParameterIds ?? []) {
	1071	pushParameter(parameterId);
	1072	}
	1073
	1074	const explicitHeaders = unique([
	1075	...(defaults.headerIds ?? []),
	1076	])
	1077	.map((headerId: HeaderSymbolId) => getHeader(catalog, headerId))
	1078	.filter((symbol): symbol is HeaderSymbol => symbol !== undefined);
	1079
	1080	const reservedTopLevel = new Set(["body", "args", "select", "path", "query", "headers", "cookies"]);
	1081	const allNames = [
	1082	...byLocation.path.map((parameter) => parameter.name),
	1083	...byLocation.query.map((parameter) => parameter.name),
	1084	...byLocation.header.map((parameter) => parameter.name),
	1085	...byLocation.cookie.map((parameter) => parameter.name),
	1086	];
	1087
	1088	const hasCollision = allNames.some((name, index) =>
	1089	reservedTopLevel.has(name) \|\| allNames.indexOf(name) !== index
	1090	);
	1091
	1092	const topLevelFields: Record<string, { shapeId: ShapeSymbolId; docs?: DocumentationBlock }> = {};
	1093	const topLevelRequired: string[] = [];
	1094
	1095	const groupedFieldNames: Array<keyof typeof byLocation> = hasCollision
	1096	? ["path", "query", "header", "cookie"]
	1097	: [];
	1098
	1099	if (hasCollision) {
	1100	createDiagnostic(catalog, {
	1101	idSeed: {
	1102	code: "projection_collision_grouped_fields",
	1103	capabilityId: capability.id,
	1104	},
	1105	level: "info",
	1106	code: "projection_collision_grouped_fields",
	1107	message: `Grouped parameter fields for ${capability.id} to avoid collisions`,
	1108	provenance: capability.provenance,
	1109	});
	1110	}
	1111
	1112	for (const location of Object.keys(byLocation) as Array<keyof typeof byLocation>) {
	1113	const parameters = byLocation[location];
	1114	if (parameters.length === 0) {
	1115	continue;
	1116	}
	1117
	1118	if (groupedFieldNames.includes(location)) {
	1119	const groupFields: Record<string, { shapeId: ShapeSymbolId; docs?: DocumentationBlock }> = {};
	1120	const groupRequired: string[] = [];
	1121	for (const parameter of parameters) {
	1122	groupFields[parameter.name] = {
	1123	shapeId: parameterShapeId(catalog, capability, parameter),
	1124	docs: parameter.docs,
	1125	};
	1126	if (parameter.required) {
	1127	groupRequired.push(parameter.name);
	1128	}
	1129	}
	1130
	1131	const groupKey = location === "header" ? "headers" : location === "cookie" ? "cookies" : location;
	1132	topLevelFields[groupKey] = {
	1133	shapeId: groupFieldShape(catalog, capability, groupKey, groupFields, groupRequired),
	1134	};
	1135	if (groupRequired.length > 0) {
	1136	topLevelRequired.push(groupKey);
	1137	}
	1138	continue;
	1139	}
	1140
	1141	for (const parameter of parameters) {
	1142	topLevelFields[parameter.name] = {
	1143	shapeId: parameterShapeId(catalog, capability, parameter),
	1144	docs: parameter.docs,
	1145	};
	1146	if (parameter.required) {
	1147	topLevelRequired.push(parameter.name);
	1148	}
	1149	}
	1150	}
	1151
	1152	for (const header of explicitHeaders) {
	1153	if (hasCollision) {
	1154	const existing = topLevelFields.headers
	1155	? getShape(catalog, topLevelFields.headers.shapeId)
	1156	: undefined;
	1157	const fields = existing && existing.node.type === "object"
	1158	? ({ ...existing.node.fields } as Record<string, { shapeId: ShapeSymbolId; docs?: DocumentationBlock }>)
	1159	: {};
	1160	fields[header.name] = {
	1161	shapeId: header.schemaShapeId
	1162	?? createSyntheticShape(catalog, {
	1163	capability,
	1164	label: `header:${header.id}:unknown`,
	1165	title: header.name,
	1166	docs: header.docs,
	1167	node: {
	1168	type: "unknown",
	1169	reason: `Missing shape for header ${header.id}`,
	1170	},
	1171	}),
	1172	...(header.docs ? { docs: header.docs } : {}),
	1173	};
	1174	topLevelFields.headers = {
	1175	shapeId: groupFieldShape(
	1176	catalog,
	1177	capability,
	1178	"headers",
	1179	Object.fromEntries(
	1180	Object.entries(fields).map(([name, field]) => [name, { shapeId: field.shapeId, docs: field.docs }]),
	1181	),
	1182	[],
	1183	),
	1184	};
	1185	continue;
	1186	}
	1187
	1188	topLevelFields[header.name] = {
	1189	shapeId: header.schemaShapeId
	1190	?? createSyntheticShape(catalog, {
	1191	capability,
	1192	label: `header:${header.id}:unknown`,
	1193	title: header.name,
	1194	docs: header.docs,
	1195	node: {
	1196	type: "unknown",
	1197	reason: `Missing shape for header ${header.id}`,
	1198	},
	1199	}),
	1200	docs: header.docs,
	1201	};
	1202	}
	1203
	1204	const bodyShapeId = requestBodyShapeId(catalog, capability, executable.requestBodyId);
	1205	if (bodyShapeId) {
	1206	topLevelFields.body = { shapeId: bodyShapeId };
	1207	const requestBody = executable.requestBodyId
	1208	? catalog.symbols[executable.requestBodyId]
	1209	: undefined;
	1210	if (requestBody && requestBody.kind === "requestBody" && requestBody.required) {
	1211	topLevelRequired.push("body");
	1212	}
	1213	}
	1214
	1215	return createSyntheticShape(catalog, {
	1216	capability,
	1217	label: `call:${capability.id}`,
	1218	title: `${capability.surface.title ?? capability.id} call`,
	1219	node: {
	1220	type: "object",
	1221	fields: Object.fromEntries(
	1222	Object.entries(topLevelFields).map(([name, field]) => [
	1223	name,
	1224	{
	1225	shapeId: field.shapeId,
	1226	...(field.docs ? { docs: field.docs } : {}),
	1227	},
	1228	]),
	1229	),
	1230	...(topLevelRequired.length > 0 ? { required: unique(topLevelRequired) } : {}),
	1231	additionalProperties: false,
	1232	},
	1233	diagnostic: {
	1234	level: "info",
	1235	code: "projection_call_shape_synthesized",
	1236	message: `Synthesized HTTP call shape for ${capability.id}`,
	1237	},
	1238	});
	1239	};
	1240
	1241	const projectGraphqlCallShape = (
	1242	catalog: CatalogV1,
	1243	capability: Capability,
	1244	executable: GraphQLExecutable,
	1245	): ShapeSymbolId => {
	1246	const argumentShape = getShape(catalog, executable.argumentShapeId);
	1247	const reserved = new Set(["body", "args", "select", "path", "query", "headers", "cookies"]);
	1248
	1249	const canFlatten =
	1250	argumentShape?.node.type === "object"
	1251	&& Object.keys(argumentShape.node.fields).every((name) => !reserved.has(name));
	1252
	1253	const fields: Record<string, { shapeId: ShapeSymbolId; docs?: DocumentationBlock }> = {};
	1254	const required: string[] = [];
	1255
	1256	if (canFlatten && argumentShape.node.type === "object") {
	1257	for (const [name, field] of Object.entries(argumentShape.node.fields)) {
	1258	fields[name] = {
	1259	shapeId: field.shapeId,
	1260	docs: field.docs,
	1261	};
	1262	}
	1263	required.push(...(argumentShape.node.required ?? []));
	1264	} else {
	1265	fields.args = {
	1266	shapeId: executable.argumentShapeId,
	1267	docs: argumentShape?.docs,
	1268	};
	1269	required.push("args");
	1270	}
	1271
	1272	if (executable.selectionMode === "caller") {
	1273	fields.select = {
	1274	shapeId:
	1275	executable.selectionShapeId
	1276	?? createSyntheticShape(catalog, {
	1277	capability,
	1278	label: `select:${capability.id}:unknown`,
	1279	title: `${capability.surface.title ?? capability.id} selection`,
	1280	node: {
	1281	type: "unknown",
	1282	reason: `Missing selection shape for ${capability.id}`,
	1283	},
	1284	diagnostic: {
	1285	level: "warning",
	1286	code: "selection_shape_missing",
	1287	message: `Missing selection shape for ${capability.id}`,
	1288	},
	1289	}),
	1290	};
	1291	required.push("select");
	1292	}
	1293
	1294	return createSyntheticShape(catalog, {
	1295	capability,
	1296	label: `call:${capability.id}`,
	1297	title: `${capability.surface.title ?? capability.id} call`,
	1298	node: {
	1299	type: "object",
	1300	fields: Object.fromEntries(
	1301	Object.entries(fields).map(([name, field]) => [
	1302	name,
	1303	{
	1304	shapeId: field.shapeId,
	1305	...(field.docs ? { docs: field.docs } : {}),
	1306	},
	1307	]),
	1308	),
	1309	...(required.length > 0 ? { required: unique(required) } : {}),
	1310	additionalProperties: false,
	1311	},
	1312	diagnostic: {
	1313	level: "info",
	1314	code: "projection_call_shape_synthesized",
	1315	message: `Synthesized GraphQL call shape for ${capability.id}`,
	1316	},
	1317	});
	1318	};
	1319
	1320	const projectMcpCallShape = (
	1321	catalog: CatalogV1,
	1322	capability: Capability,
	1323	executable: McpExecutable,
	1324	): ShapeSymbolId => {
	1325	if (!executable.inputShapeId) {
	1326	return createSyntheticShape(catalog, {
	1327	capability,
	1328	label: `call:${capability.id}:empty`,
	1329	title: `${capability.surface.title ?? capability.id} call`,
	1330	node: {
	1331	type: "object",
	1332	fields: {},
	1333	additionalProperties: false,
	1334	},
	1335	diagnostic: {
	1336	level: "info",
	1337	code: "projection_call_shape_synthesized",
	1338	message: `Synthesized empty MCP call shape for ${capability.id}`,
	1339	},
	1340	});
	1341	}
	1342
	1343	const inputShape = getShape(catalog, executable.inputShapeId);
	1344	if (inputShape?.node.type === "object") {
	1345	return executable.inputShapeId;
	1346	}
	1347
	1348	return createSyntheticShape(catalog, {
	1349	capability,
	1350	label: `call:${capability.id}`,
	1351	title: `${capability.surface.title ?? capability.id} call`,
	1352	node: {
	1353	type: "object",
	1354	fields: {
	1355	input: {
	1356	shapeId: executable.inputShapeId,
	1357	},
	1358	},
	1359	required: ["input"],
	1360	additionalProperties: false,
	1361	},
	1362	diagnostic: {
	1363	level: "info",
	1364	code: "projection_call_shape_synthesized",
	1365	message: `Wrapped non-object MCP input shape for ${capability.id}`,
	1366	},
	1367	});
	1368	};
	1369
	1370	const projectCapability = (
	1371	catalog: CatalogV1,
	1372	capability: Capability,
	1373	): ToolDescriptor => {
	1374	const executable = chooseExecutable(catalog, capability);
	1375	const responseSet = catalog.responseSets[executable.responseSetId];
	1376
	1377	if (!responseSet) {
	1378	throw new Error(`Missing response set ${executable.responseSetId} for ${capability.id}`);
	1379	}
	1380
	1381	let callShapeId: ShapeSymbolId;
	1382	let resultShapeId: ShapeSymbolId \| undefined;
	1383
	1384	switch (executable.protocol) {
	1385	case "http":
	1386	callShapeId = projectHttpCallShape(catalog, capability, executable);
	1387	resultShapeId = projectExecutionResultShape(catalog, capability, executable, responseSet);
	1388	break;
	1389	case "graphql":
	1390	callShapeId = projectGraphqlCallShape(catalog, capability, executable);
	1391	resultShapeId = projectExecutionResultShape(catalog, capability, executable, responseSet);
	1392	break;
	1393	case "mcp":
	1394	callShapeId = projectMcpCallShape(catalog, capability, executable);
	1395	resultShapeId = projectExecutionResultShape(catalog, capability, executable, responseSet);
	1396	break;
	1397	}
	1398
	1399	const diagnosticIds = unique([
	1400	...(capability.diagnosticIds ?? []),
	1401	...(executable.diagnosticIds ?? []),
	1402	...(responseSet.diagnosticIds ?? []),
	1403	...(callShapeId ? catalog.symbols[callShapeId]?.diagnosticIds ?? [] : []),
	1404	...(resultShapeId ? catalog.symbols[resultShapeId]?.diagnosticIds ?? [] : []),
	1405	]);
	1406	const diagnostics = diagnosticIds
	1407	.map((diagnosticId) => catalog.diagnostics[diagnosticId])
	1408	.filter((diagnostic): diagnostic is ImportDiagnostic => diagnostic !== undefined);
	1409
	1410	return {
	1411	toolPath: [...capability.surface.toolPath],
	1412	capabilityId: capability.id,
	1413	...(capability.surface.title ? { title: capability.surface.title } : {}),
	1414	...(capability.surface.summary ? { summary: capability.surface.summary } : {}),
	1415	effect: capability.semantics.effect,
	1416	interaction: {
	1417	mayRequireApproval: capability.interaction.approval.mayRequire,
	1418	mayElicit: capability.interaction.elicitation.mayRequest,
	1419	},
	1420	callShapeId,
	1421	...(resultShapeId ? { resultShapeId } : {}),
	1422	responseSetId: executable.responseSetId,
	1423	diagnosticCounts: {
	1424	warning: diagnostics.filter((diagnostic) => diagnostic.level === "warning").length,
	1425	error: diagnostics.filter((diagnostic) => diagnostic.level === "error").length,
	1426	},
	1427	};
	1428	};
	1429
	1430	const summaryView = (
	1431	catalog: CatalogV1,
	1432	capability: Capability,
	1433	descriptor: ToolDescriptor,
	1434	): CapabilitySummaryView => ({
	1435	capabilityId: capability.id,
	1436	toolPath: [...capability.surface.toolPath],
	1437	...(capability.surface.summary ? { summary: capability.surface.summary } : {}),
	1438	executableIds: [...capability.executableIds],
	1439	auth: capability.auth,
	1440	interaction: capability.interaction,
	1441	callShapeId: descriptor.callShapeId,
	1442	...(descriptor.resultShapeId ? { resultShapeId: descriptor.resultShapeId } : {}),
	1443	responseSetId: descriptor.responseSetId,
	1444	...(capability.diagnosticIds ? { diagnosticIds: [...capability.diagnosticIds] } : {}),
	1445	});
	1446
	1447	const searchDoc = (
	1448	catalog: CatalogV1,
	1449	capability: Capability,
	1450	): ToolSearchDoc => ({
	1451	capabilityId: capability.id,
	1452	toolPath: [...capability.surface.toolPath],
	1453	...(capability.surface.title ? { title: capability.surface.title } : {}),
	1454	...(capability.surface.summary ? { summary: capability.surface.summary } : {}),
	1455	...(capability.surface.tags ? { tags: [...capability.surface.tags] } : {}),
	1456	protocolHints: unique(
	1457	capability.executableIds
	1458	.map((executableId: ExecutableId) => catalog.executables[executableId]?.protocol)
	1459	.filter((protocol): protocol is Executable["protocol"] => protocol !== undefined),
	1460	),
	1461	authHints: authHintStrings(catalog, capability.auth),
	1462	effect: capability.semantics.effect,
	1463	});
	1464
	1465	const symbolTitle = (symbol: IrSymbol): string \| undefined => {
	1466	switch (symbol.kind) {
	1467	case "shape":
	1468	return symbol.title ?? symbol.docs?.summary;
	1469	case "parameter":
	1470	case "header":
	1471	return symbol.name;
	1472	case "example":
	1473	return symbol.name ?? symbol.docs?.summary;
	1474	case "requestBody":
	1475	case "response":
	1476	case "securityScheme":
	1477	return symbol.docs?.summary;
	1478	}
	1479	};
	1480
	1481	const symbolSummary = (symbol: IrSymbol): string \| undefined =>
	1482	symbol.docs?.summary ?? docsSummary(symbol.docs);
	1483
	1484	const symbolEdges = (symbol: IrSymbol): Array<{ label: string; targetId: SymbolId }> => {
	1485	switch (symbol.kind) {
	1486	case "shape": {
	1487	const edges: Array<{ label: string; targetId: SymbolId }> = [];
	1488	switch (symbol.node.type) {
	1489	case "object":
	1490	for (const [name, field] of Object.entries(symbol.node.fields)) {
	1491	edges.push({ label: `field:${name}`, targetId: field.shapeId });
	1492	}
	1493	if (typeof symbol.node.additionalProperties !== "boolean" && symbol.node.additionalProperties) {
	1494	edges.push({
	1495	label: "additionalProperties",
	1496	targetId: symbol.node.additionalProperties,
	1497	});
	1498	}
	1499	for (const [pattern, targetId] of Object.entries(symbol.node.patternProperties ?? {})) {
	1500	edges.push({ label: `pattern:${pattern}`, targetId });
	1501	}
	1502	break;
	1503	case "array":
	1504	edges.push({ label: "item", targetId: symbol.node.itemShapeId });
	1505	break;
	1506	case "tuple":
	1507	symbol.node.itemShapeIds.forEach((targetId, index) => {
	1508	edges.push({ label: `item:${String(index)}`, targetId });
	1509	});
	1510	if (typeof symbol.node.additionalItems !== "boolean" && symbol.node.additionalItems) {
	1511	edges.push({ label: "additionalItems", targetId: symbol.node.additionalItems });
	1512	}
	1513	break;
	1514	case "map":
	1515	edges.push({ label: "value", targetId: symbol.node.valueShapeId });
	1516	break;
	1517	case "allOf":
	1518	case "anyOf":
	1519	case "oneOf":
	1520	symbol.node.items.forEach((targetId, index) => {
	1521	edges.push({ label: `${symbol.node.type}:${String(index)}`, targetId });
	1522	});
	1523	if (symbol.node.type === "oneOf") {
	1524	for (const [key, targetId] of Object.entries(symbol.node.discriminator?.mapping ?? {})) {
	1525	edges.push({ label: `discriminator:${key}`, targetId });
	1526	}
	1527	}
	1528	break;
	1529	case "nullable":
	1530	edges.push({ label: "item", targetId: symbol.node.itemShapeId });
	1531	break;
	1532	case "ref":
	1533	edges.push({ label: "target", targetId: symbol.node.target });
	1534	break;
	1535	case "not":
	1536	edges.push({ label: "not", targetId: symbol.node.itemShapeId });
	1537	break;
	1538	case "conditional":
	1539	edges.push({ label: "if", targetId: symbol.node.ifShapeId });
	1540	if (symbol.node.thenShapeId) {
	1541	edges.push({ label: "then", targetId: symbol.node.thenShapeId });
	1542	}
	1543	if (symbol.node.elseShapeId) {
	1544	edges.push({ label: "else", targetId: symbol.node.elseShapeId });
	1545	}
	1546	break;
	1547	case "graphqlInterface":
	1548	for (const [name, field] of Object.entries(symbol.node.fields)) {
	1549	edges.push({ label: `field:${name}`, targetId: field.shapeId });
	1550	}
	1551	symbol.node.possibleTypeIds.forEach((targetId) => {
	1552	edges.push({ label: "possibleType", targetId });
	1553	});
	1554	break;
	1555	case "graphqlUnion":
	1556	symbol.node.memberTypeIds.forEach((targetId) => {
	1557	edges.push({ label: "member", targetId });
	1558	});
	1559	break;
	1560	default:
	1561	break;
	1562	}
	1563	return edges;
	1564	}
	1565	case "parameter":
	1566	case "header":
	1567	return unique([
	1568	...(symbol.schemaShapeId ? [{ label: "schema", targetId: symbol.schemaShapeId as SymbolId }] : []),
	1569	...((symbol.content ?? []).flatMap((content, index) => [
	1570	...(content.shapeId ? [{ label: `content:${String(index)}`, targetId: content.shapeId as SymbolId }] : []),
	1571	...((content.exampleIds ?? []).map((targetId) => ({
	1572	label: `example:${String(index)}`,
	1573	targetId: targetId as SymbolId,
	1574	}))),
	1575	])),
	1576	...((symbol.exampleIds ?? []).map((targetId) => ({
	1577	label: "example",
	1578	targetId: targetId as SymbolId,
	1579	}))),
	1580	]);
	1581	case "requestBody":
	1582	return (symbol.contents ?? []).flatMap((content, index) => [
	1583	...(content.shapeId ? [{ label: `content:${String(index)}`, targetId: content.shapeId as SymbolId }] : []),
	1584	...((content.exampleIds ?? []).map((targetId) => ({
	1585	label: `example:${String(index)}`,
	1586	targetId: targetId as SymbolId,
	1587	}))),
	1588	]);
	1589	case "response":
	1590	return [
	1591	...((symbol.headerIds ?? []).map((targetId) => ({
	1592	label: "header",
	1593	targetId: targetId as SymbolId,
	1594	}))),
	1595	...((symbol.contents ?? []).flatMap((content, index) => [
	1596	...(content.shapeId ? [{ label: `content:${String(index)}`, targetId: content.shapeId as SymbolId }] : []),
	1597	...((content.exampleIds ?? []).map((targetId) => ({
	1598	label: `example:${String(index)}`,
	1599	targetId: targetId as SymbolId,
	1600	}))),
	1601	])),
	1602	];
	1603	case "example":
	1604	case "securityScheme":
	1605	return [];
	1606	}
	1607	};
	1608
	1609	export const decodeCatalogV1 = (input: unknown): CatalogV1 => {
	1610	try {
	1611	return decodeCatalogSync(input);
	1612	} catch (cause) {
	1613	throw new Error(ParseResult.TreeFormatter.formatErrorSync(cause as never));
	1614	}
	1615	};
	1616
	1617	export const decodeCatalogFragmentV1 = (input: unknown): CatalogFragmentV1 => {
	1618	try {
	1619	return decodeCatalogFragmentSync(input);
	1620	} catch (cause) {
	1621	throw new Error(ParseResult.TreeFormatter.formatErrorSync(cause as never));
	1622	}
	1623	};
	1624
	1625	export const decodeCatalogSnapshotV1 = (input: unknown) => {
	1626	try {
	1627	const snapshot = decodeCatalogSnapshotSync(input);
	1628	assertCatalogInvariants(snapshot.catalog);
	1629	return snapshot;
	1630	} catch (cause) {
	1631	if (cause instanceof Error) {
	1632	throw cause;
	1633	}
	1634	throw new Error(ParseResult.TreeFormatter.formatErrorSync(cause as never));
	1635	}
	1636	};
	1637
	1638	export const createEmptyCatalogV1 = (): CatalogV1 => emptyCatalog();
	1639
	1640	export const createCatalogSnapshotV1 = (input: {
	1641	import: ImportMetadata;
	1642	catalog: CatalogV1;
	1643	}) => {
	1644	const catalog = assertCatalogInvariants(decodeCatalogV1(input.catalog));
	1645
	1646	return {
	1647	version: "ir.v1.snapshot" as const,
	1648	import: input.import,
	1649	catalog,
	1650	};
	1651	};
	1652
	1653	export const createCatalogSnapshotV1FromFragments = (input: {
	1654	import: ImportMetadata;
	1655	fragments: readonly CatalogFragmentV1[];
	1656	}) =>
	1657	createCatalogSnapshotV1({
	1658	import: input.import,
	1659	catalog: mergeCatalogFragments(input.fragments),
	1660	});
	1661
	1662	export const mergeCatalogFragments = (fragments: readonly CatalogFragmentV1[]): CatalogV1 => {
	1663	const catalog = emptyCatalog();
	1664	const seenByCollection = new Map<string, string>();
	1665
	1666	const mergeRecord = <T extends { id: string }>(
	1667	collectionName: keyof CatalogV1,
	1668	entries: Record<string, T> \| undefined,
	1669	) => {
	1670	if (!entries) {
	1671	return;
	1672	}
	1673
	1674	const target = catalog[collectionName] as Record<string, T>;
	1675	for (const [id, entry] of Object.entries(entries)) {
	1676	const existing = target[id];
	1677	if (!existing) {
	1678	target[id] = entry;
	1679	seenByCollection.set(`${String(collectionName)}:${id}`, stableStringify(entry));
	1680	continue;
	1681	}
	1682
	1683	const existingHash = seenByCollection.get(`${String(collectionName)}:${id}`) ?? stableStringify(existing);
	1684	const nextHash = stableStringify(entry);
	1685	if (existingHash === nextHash) {
	1686	continue;
	1687	}
	1688
	1689	if (collectionName !== "diagnostics") {
	1690	createDiagnostic(catalog, {
	1691	idSeed: {
	1692	collectionName,
	1693	id,
	1694	existingHash,
	1695	nextHash,
	1696	},
	1697	level: "error",
	1698	code: "merge_conflict_preserved_first",
	1699	message: `Conflicting ${String(collectionName)} entry for ${id}; preserved first value`,
	1700	provenance: "provenance" in existing
	1701	? (existing as { provenance: ImportDiagnostic["provenance"] }).provenance
	1702	: [],
	1703	});
	1704	}
	1705	}
	1706	};
	1707
	1708	for (const fragment of fragments) {
	1709	mergeRecord("documents", fragment.documents);
	1710	mergeRecord("resources", fragment.resources);
	1711	mergeRecord("scopes", fragment.scopes);
	1712	mergeRecord("symbols", fragment.symbols);
	1713	mergeRecord("capabilities", fragment.capabilities);
	1714	mergeRecord("executables", fragment.executables);
	1715	mergeRecord("responseSets", fragment.responseSets);
	1716	mergeRecord("diagnostics", fragment.diagnostics);
	1717	}
	1718
	1719	return assertCatalogInvariants(decodeCatalogV1(catalog));
	1720	};
	1721
	1722	export const validateCatalogInvariants = (
	1723	catalog: CatalogV1,
	1724	): CatalogInvariantViolation[] => {
	1725	const violations: CatalogInvariantViolation[] = [];
	1726
	1727	const checkProvenanceDocuments = (input: {
	1728	entityId: string;
	1729	provenance: readonly { documentId: DocumentId }[];
	1730	}) => {
	1731	for (const provenance of input.provenance) {
	1732	if (!catalog.documents[provenance.documentId]) {
	1733	violations.push({
	1734	code: "missing_provenance_document",
	1735	entityId: input.entityId,
	1736	message: `Entity ${input.entityId} references missing provenance document ${provenance.documentId}`,
	1737	});
	1738	}
	1739	}
	1740	};
	1741
	1742	for (const symbol of Object.values(catalog.symbols)) {
	1743	if (symbol.provenance.length === 0) {
	1744	violations.push({
	1745	code: "missing_symbol_provenance",
	1746	entityId: symbol.id,
	1747	message: `Symbol ${symbol.id} is missing provenance`,
	1748	});
	1749	}
	1750
	1751	if (symbol.kind === "shape") {
	1752	if (!symbol.resourceId && !symbol.synthetic) {
	1753	violations.push({
	1754	code: "missing_resource_context",
	1755	entityId: symbol.id,
	1756	message: `Shape ${symbol.id} must belong to a resource or be synthetic`,
	1757	});
	1758	}
	1759
	1760	if (symbol.node.type === "ref" && !catalog.symbols[symbol.node.target]) {
	1761	violations.push({
	1762	code: "missing_reference_target",
	1763	entityId: symbol.id,
	1764	message: `Shape ${symbol.id} references missing shape ${symbol.node.target}`,
	1765	});
	1766	}
	1767
	1768	if (symbol.node.type === "unknown" && symbol.node.reason?.includes("unresolved")) {
	1769	const hasDiagnostic = (symbol.diagnosticIds ?? [])
	1770	.map((diagnosticId) => catalog.diagnostics[diagnosticId])
	1771	.some((diagnostic) => diagnostic?.code === "unresolved_ref");
	1772
	1773	if (!hasDiagnostic) {
	1774	violations.push({
	1775	code: "missing_unresolved_ref_diagnostic",
	1776	entityId: symbol.id,
	1777	message: `Shape ${symbol.id} is unresolved but has no unresolved_ref diagnostic`,
	1778	});
	1779	}
	1780	}
	1781
	1782	if (symbol.synthetic && symbol.resourceId && !catalog.resources[symbol.resourceId]) {
	1783	violations.push({
	1784	code: "missing_resource_context",
	1785	entityId: symbol.id,
	1786	message: `Synthetic shape ${symbol.id} references missing resource ${symbol.resourceId}`,
	1787	});
	1788	}
	1789	}
	1790
	1791	checkProvenanceDocuments({
	1792	entityId: symbol.id,
	1793	provenance: symbol.provenance,
	1794	});
	1795	}
	1796
	1797	for (const collection of [
	1798	...Object.values(catalog.resources),
	1799	...Object.values(catalog.scopes),
	1800	...Object.values(catalog.capabilities),
	1801	...Object.values(catalog.executables),
	1802	...Object.values(catalog.responseSets),
	1803	]) {
	1804	if ("provenance" in collection && collection.provenance.length === 0) {
	1805	violations.push({
	1806	code: "missing_entity_provenance",
	1807	entityId: "id" in collection ? collection.id : undefined,
	1808	message: `Entity ${"id" in collection ? collection.id : "unknown"} is missing provenance`,
	1809	});
	1810	}
	1811
	1812	if ("id" in collection) {
	1813	checkProvenanceDocuments({
	1814	entityId: collection.id,
	1815	provenance: collection.provenance,
	1816	});
	1817	}
	1818	}
	1819
	1820	for (const resource of Object.values(catalog.resources)) {
	1821	if (!catalog.documents[resource.documentId]) {
	1822	violations.push({
	1823	code: "missing_document",
	1824	entityId: resource.id,
	1825	message: `Resource ${resource.id} references missing document ${resource.documentId}`,
	1826	});
	1827	}
	1828	}
	1829
	1830	for (const capability of Object.values(catalog.capabilities)) {
	1831	if (!catalog.scopes[capability.serviceScopeId]) {
	1832	violations.push({
	1833	code: "missing_service_scope",
	1834	entityId: capability.id,
	1835	message: `Capability ${capability.id} references missing scope ${capability.serviceScopeId}`,
	1836	});
	1837	}
	1838
	1839	if (
	1840	capability.preferredExecutableId
	1841	&& !capability.executableIds.includes(capability.preferredExecutableId)
	1842	) {
	1843	violations.push({
	1844	code: "invalid_preferred_executable",
	1845	entityId: capability.id,
	1846	message: `Capability ${capability.id} preferred executable is not in executableIds`,
	1847	});
	1848	}
	1849
	1850	for (const executableId of capability.executableIds) {
	1851	if (!catalog.executables[executableId]) {
	1852	violations.push({
	1853	code: "missing_executable",
	1854	entityId: capability.id,
	1855	message: `Capability ${capability.id} references missing executable ${executableId}`,
	1856	});
	1857	}
	1858	}
	1859	}
	1860
	1861	for (const executable of Object.values(catalog.executables)) {
	1862	if (!catalog.capabilities[executable.capabilityId]) {
	1863	violations.push({
	1864	code: "missing_executable",
	1865	entityId: executable.id,
	1866	message: `Executable ${executable.id} references missing capability ${executable.capabilityId}`,
	1867	});
	1868	}
	1869
	1870	if (!catalog.scopes[executable.scopeId]) {
	1871	violations.push({
	1872	code: "missing_scope",
	1873	entityId: executable.id,
	1874	message: `Executable ${executable.id} references missing scope ${executable.scopeId}`,
	1875	});
	1876	}
	1877
	1878	if (!catalog.responseSets[executable.responseSetId]) {
	1879	violations.push({
	1880	code: "missing_response_set",
	1881	entityId: executable.id,
	1882	message: `Executable ${executable.id} references missing response set ${executable.responseSetId}`,
	1883	});
	1884	}
	1885	}
	1886
	1887	return violations;
	1888	};
	1889
	1890	const assertCatalogInvariants = (catalog: CatalogV1): CatalogV1 => {
	1891	const violations = validateCatalogInvariants(catalog);
	1892	if (violations.length === 0) {
	1893	return catalog;
	1894	}
	1895
	1896	const preview = violations
	1897	.slice(0, 5)
	1898	.map((violation) => `${violation.code}: ${violation.message}`)
	1899	.join("\n");
	1900
	1901	throw new Error(
	1902	[
	1903	`Invalid IR catalog (${violations.length} invariant violation${violations.length === 1 ? "" : "s"}).`,
	1904	preview,
	1905	...(violations.length > 5 ? [`...and ${String(violations.length - 5)} more`] : []),
	1906	].join("\n"),
	1907	);
	1908	};
	1909
	1910	export const projectCatalogForAgentSdk = (input: {
	1911	catalog: CatalogV1;
	1912	}): ProjectedCatalog => {
	1913	const workingCatalog = cloneCatalog(input.catalog);
	1914	const toolDescriptors = {} as Record<CapabilityId, ToolDescriptor>;
	1915	const searchDocs = {} as Record<CapabilityId, ToolSearchDoc>;
	1916	const capabilityViews = {} as Record<CapabilityId, CapabilitySummaryView>;
	1917
	1918	const capabilities = Object.values(workingCatalog.capabilities)
	1919	.sort((left, right) => left.id.localeCompare(right.id));
	1920
	1921	for (const capability of capabilities) {
	1922	const descriptor = projectCapability(workingCatalog, capability);
	1923	toolDescriptors[capability.id] = descriptor;
	1924	searchDocs[capability.id] = searchDoc(workingCatalog, capability);
	1925	capabilityViews[capability.id] = summaryView(workingCatalog, capability, descriptor);
	1926	}
	1927
	1928	return {
	1929	catalog: workingCatalog,
	1930	toolDescriptors,
	1931	searchDocs,
	1932	capabilityViews,
	1933	};
	1934	};
	1935
	1936	export const projectSymbolShallowView = (
	1937	catalog: CatalogV1,
	1938	symbolId: SymbolId,
	1939	): SymbolShallowView => {
	1940	const symbol = catalog.symbols[symbolId];
	1941	if (!symbol) {
	1942	throw new Error(`Unknown symbol ${symbolId}`);
	1943	}
	1944
	1945	return {
	1946	symbolId,
	1947	kind: symbol.kind,
	1948	...(symbolTitle(symbol) ? { title: symbolTitle(symbol) } : {}),
	1949	...(symbolSummary(symbol) ? { summary: symbolSummary(symbol) } : {}),
	1950	edges: symbolEdges(symbol),
	1951	};
	1952	};
	1953
	1954	export const projectSymbolExpandedView = (
	1955	catalog: CatalogV1,
	1956	symbolId: SymbolId,
	1957	): SymbolExpandedView => {
	1958	const symbol = catalog.symbols[symbolId];
	1959	if (!symbol) {
	1960	throw new Error(`Unknown symbol ${symbolId}`);
	1961	}
	1962
	1963	return {
	1964	symbolId,
	1965	symbol,
	1966	...(symbol.diagnosticIds
	1967	? {
	1968	diagnostics: symbol.diagnosticIds
	1969	.map((diagnosticId) => catalog.diagnostics[diagnosticId])
	1970	.filter((diagnostic): diagnostic is ImportDiagnostic => diagnostic !== undefined),
	1971	}
	1972	: {}),
	1973	};
	1974	};
	1975
	1976	export const buildInvocationPlan = (input: {
	1977	catalog: CatalogV1;
	1978	capabilityId: CapabilityId;
	1979	executableId?: ExecutableId;
	1980	connectionBindingId: string;
	1981	resolvedEndpoint?: string;
	1982	resolvedAuth?: unknown;
	1983	resolvedInteraction?: Partial<InvocationPlan["resolvedInteraction"]>;
	1984	requestPlan: unknown;
	1985	}): InvocationPlan => {
	1986	const capability = input.catalog.capabilities[input.capabilityId];
	1987	if (!capability) {
	1988	throw new Error(`Unknown capability ${input.capabilityId}`);
	1989	}
	1990
	1991	const executable = input.executableId
	1992	? input.catalog.executables[input.executableId]
	1993	: chooseExecutable(input.catalog, capability);
	1994	if (!executable) {
	1995	throw new Error(`Unknown executable for capability ${input.capabilityId}`);
	1996	}
	1997
	1998	const scopes = scopeChain(input.catalog, executable.scopeId).map((scope) => scope.id);
	1999
	2000	return {
	2001	capabilityId: capability.id,
	2002	executableId: executable.id,
	2003	connectionBindingId: input.connectionBindingId,
	2004	resolvedScopeChain: scopes,
	2005	...(input.resolvedEndpoint ? { resolvedEndpoint: input.resolvedEndpoint } : {}),
	2006	...(input.resolvedAuth !== undefined ? { resolvedAuth: input.resolvedAuth } : {}),
	2007	resolvedInteraction: {
	2008	requiresApproval: input.resolvedInteraction?.requiresApproval
	2009	?? capability.interaction.approval.mayRequire,
	2010	mayPauseForElicitation: input.resolvedInteraction?.mayPauseForElicitation
	2011	?? capability.interaction.elicitation.mayRequest,
	2012	resumable: input.resolvedInteraction?.resumable
	2013	?? capability.interaction.resume.supported,
	2014	},
	2015	requestPlan: input.requestPlan,
	2016	provenance: capability.provenance,
	2017	};
	2018	};

packages/kernel/ir/src/ids.ts+58−0

@@ -0,0 +1,58 @@
	1	import { Schema } from "effect";
	2
	3	export const DocumentIdSchema = Schema.String.pipe(Schema.brand("DocumentId"));
	4	export const ResourceIdSchema = Schema.String.pipe(Schema.brand("ResourceId"));
	5	export const ScopeIdSchema = Schema.String.pipe(Schema.brand("ScopeId"));
	6	export const CapabilityIdSchema = Schema.String.pipe(Schema.brand("CapabilityId"));
	7	export const ExecutableIdSchema = Schema.String.pipe(Schema.brand("ExecutableId"));
	8	export const ResponseSetIdSchema = Schema.String.pipe(Schema.brand("ResponseSetId"));
	9	export const DiagnosticIdSchema = Schema.String.pipe(Schema.brand("DiagnosticId"));
	10
	11	export const ShapeSymbolIdSchema = Schema.String.pipe(Schema.brand("ShapeSymbolId"));
	12	export const ParameterSymbolIdSchema = Schema.String.pipe(Schema.brand("ParameterSymbolId"));
	13	export const RequestBodySymbolIdSchema = Schema.String.pipe(
	14	Schema.brand("RequestBodySymbolId"),
	15	);
	16	export const ResponseSymbolIdSchema = Schema.String.pipe(
	17	Schema.brand("ResponseSymbolId"),
	18	);
	19	export const HeaderSymbolIdSchema = Schema.String.pipe(Schema.brand("HeaderSymbolId"));
	20	export const ExampleSymbolIdSchema = Schema.String.pipe(Schema.brand("ExampleSymbolId"));
	21	export const SecuritySchemeSymbolIdSchema = Schema.String.pipe(
	22	Schema.brand("SecuritySchemeSymbolId"),
	23	);
	24
	25	export type DocumentId = typeof DocumentIdSchema.Type;
	26	export type ResourceId = typeof ResourceIdSchema.Type;
	27	export type ScopeId = typeof ScopeIdSchema.Type;
	28	export type CapabilityId = typeof CapabilityIdSchema.Type;
	29	export type ExecutableId = typeof ExecutableIdSchema.Type;
	30	export type ResponseSetId = typeof ResponseSetIdSchema.Type;
	31	export type DiagnosticId = typeof DiagnosticIdSchema.Type;
	32
	33	export type ShapeSymbolId = typeof ShapeSymbolIdSchema.Type;
	34	export type ParameterSymbolId = typeof ParameterSymbolIdSchema.Type;
	35	export type RequestBodySymbolId = typeof RequestBodySymbolIdSchema.Type;
	36	export type ResponseSymbolId = typeof ResponseSymbolIdSchema.Type;
	37	export type HeaderSymbolId = typeof HeaderSymbolIdSchema.Type;
	38	export type ExampleSymbolId = typeof ExampleSymbolIdSchema.Type;
	39	export type SecuritySchemeSymbolId = typeof SecuritySchemeSymbolIdSchema.Type;
	40
	41	export type SymbolId =
	42	\| ShapeSymbolId
	43	\| ParameterSymbolId
	44	\| RequestBodySymbolId
	45	\| ResponseSymbolId
	46	\| HeaderSymbolId
	47	\| ExampleSymbolId
	48	\| SecuritySchemeSymbolId;
	49
	50	export const SymbolIdSchema = Schema.Union(
	51	ShapeSymbolIdSchema,
	52	ParameterSymbolIdSchema,
	53	RequestBodySymbolIdSchema,
	54	ResponseSymbolIdSchema,
	55	HeaderSymbolIdSchema,
	56	ExampleSymbolIdSchema,
	57	SecuritySchemeSymbolIdSchema,
	58	);

packages/kernel/ir/src/index.ts+3−0

@@ -0,0 +1,3 @@
	1	export * from "./ids";
	2	export * from "./model";
	3	export * from "./catalog";

packages/kernel/ir/src/model.ts+971−0

@@ -0,0 +1,971 @@
	1	import { Schema } from "effect";
	2
	3	import {
	4	CapabilityIdSchema,
	5	type CapabilityId,
	6	DiagnosticIdSchema,
	7	type DiagnosticId,
	8	DocumentIdSchema,
	9	type DocumentId,
	10	ExecutableIdSchema,
	11	type ExecutableId,
	12	ExampleSymbolIdSchema,
	13	type ExampleSymbolId,
	14	HeaderSymbolIdSchema,
	15	type HeaderSymbolId,
	16	ParameterSymbolIdSchema,
	17	type ParameterSymbolId,
	18	RequestBodySymbolIdSchema,
	19	type RequestBodySymbolId,
	20	ResourceIdSchema,
	21	type ResourceId,
	22	ResponseSetIdSchema,
	23	type ResponseSetId,
	24	ResponseSymbolIdSchema,
	25	type ResponseSymbolId,
	26	ScopeIdSchema,
	27	type ScopeId,
	28	SecuritySchemeSymbolIdSchema,
	29	type SecuritySchemeSymbolId,
	30	ShapeSymbolIdSchema,
	31	type ShapeSymbolId,
	32	SymbolIdSchema,
	33	type SymbolId,
	34	} from "./ids";
	35
	36	export const SourceKindSchema = Schema.Literal(
	37	"openapi",
	38	"graphql-schema",
	39	"google-discovery",
	40	"mcp",
	41	"custom",
	42	);
	43
	44	export const ScopeKindSchema = Schema.Literal(
	45	"service",
	46	"document",
	47	"resource",
	48	"pathItem",
	49	"operation",
	50	"folder",
	51	);
	52
	53	export const EffectKindSchema = Schema.Literal(
	54	"read",
	55	"write",
	56	"delete",
	57	"action",
	58	"subscribe",
	59	);
	60
	61	export const ParameterLocationSchema = Schema.Literal(
	62	"path",
	63	"query",
	64	"header",
	65	"cookie",
	66	);
	67
	68	export const ResponseTraitSchema = Schema.Literal(
	69	"success",
	70	"redirect",
	71	"stream",
	72	"download",
	73	"upload",
	74	"longRunning",
	75	);
	76
	77	export const SecuritySchemeTypeSchema = Schema.Literal(
	78	"oauth2",
	79	"http",
	80	"apiKey",
	81	"basic",
	82	"bearer",
	83	"custom",
	84	);
	85
	86	export const SelectionModeSchema = Schema.Literal(
	87	"caller",
	88	"fixed",
	89	"persisted",
	90	);
	91
	92	export const GraphQLToolKindSchema = Schema.Literal(
	93	"request",
	94	"field",
	95	);
	96
	97	export const StatusRangeSchema = Schema.Literal(
	98	"1XX",
	99	"2XX",
	100	"3XX",
	101	"4XX",
	102	"5XX",
	103	);
	104
	105	export const PaginationHintKindSchema = Schema.Literal(
	106	"cursor",
	107	"offset",
	108	"token",
	109	"unknown",
	110	);
	111
	112	export const DiagnosticLevelSchema = Schema.Literal(
	113	"info",
	114	"warning",
	115	"error",
	116	);
	117
	118	export const DiagnosticCodeSchema = Schema.Literal(
	119	"external_ref_bundled",
	120	"relative_ref_rebased",
	121	"schema_hoisted",
	122	"selection_shape_synthesized",
	123	"opaque_hook_imported",
	124	"discriminator_lost",
	125	"multi_response_union_synthesized",
	126	"unsupported_link_preserved_native",
	127	"unsupported_callback_preserved_native",
	128	"unresolved_ref",
	129	"merge_conflict_preserved_first",
	130	"projection_call_shape_synthesized",
	131	"projection_result_shape_synthesized",
	132	"projection_collision_grouped_fields",
	133	"synthetic_resource_context_created",
	134	"selection_shape_missing",
	135	);
	136
	137	export const NativeEncodingSchema = Schema.Literal(
	138	"json",
	139	"yaml",
	140	"graphql",
	141	"text",
	142	"unknown",
	143	);
	144
	145	export const ProvenanceRelationSchema = Schema.Literal(
	146	"declared",
	147	"hoisted",
	148	"derived",
	149	"merged",
	150	"projected",
	151	);
	152
	153	export const DocumentationBlockSchema = Schema.Struct({
	154	summary: Schema.optional(Schema.String),
	155	description: Schema.optional(Schema.String),
	156	externalDocsUrl: Schema.optional(Schema.String),
	157	});
	158
	159	export const ProvenanceRefSchema = Schema.Struct({
	160	relation: ProvenanceRelationSchema,
	161	documentId: DocumentIdSchema,
	162	resourceId: Schema.optional(ResourceIdSchema),
	163	pointer: Schema.optional(Schema.String),
	164	line: Schema.optional(Schema.Number),
	165	column: Schema.optional(Schema.Number),
	166	});
	167
	168	export const NativeBlobSchema = Schema.Struct({
	169	sourceKind: SourceKindSchema,
	170	kind: Schema.String,
	171	pointer: Schema.optional(Schema.String),
	172	encoding: Schema.optional(NativeEncodingSchema),
	173	summary: Schema.optional(Schema.String),
	174	value: Schema.optional(Schema.Unknown),
	175	});
	176
	177	export const EntityBaseSchema = Schema.Struct({
	178	synthetic: Schema.Boolean,
	179	provenance: Schema.Array(ProvenanceRefSchema),
	180	diagnosticIds: Schema.optional(Schema.Array(DiagnosticIdSchema)),
	181	native: Schema.optional(Schema.Array(NativeBlobSchema)),
	182	});
	183
	184	export const ImportMetadataSchema = Schema.Struct({
	185	sourceKind: SourceKindSchema,
	186	adapterKey: Schema.String,
	187	importerVersion: Schema.String,
	188	importedAt: Schema.String,
	189	sourceConfigHash: Schema.String,
	190	});
	191
	192	export const SourceDocumentSchema = Schema.Struct({
	193	id: DocumentIdSchema,
	194	kind: SourceKindSchema,
	195	title: Schema.optional(Schema.String),
	196	versionHint: Schema.optional(Schema.String),
	197	fetchedAt: Schema.String,
	198	rawRef: Schema.String,
	199	entryUri: Schema.optional(Schema.String),
	200	native: Schema.optional(Schema.Array(NativeBlobSchema)),
	201	});
	202
	203	export const FieldSpecSchema = Schema.Struct({
	204	shapeId: ShapeSymbolIdSchema,
	205	docs: Schema.optional(DocumentationBlockSchema),
	206	deprecated: Schema.optional(Schema.Boolean),
	207	exampleIds: Schema.optional(Schema.Array(ExampleSymbolIdSchema)),
	208	});
	209
	210	export const DiscriminatorSpecSchema = Schema.Struct({
	211	propertyName: Schema.String,
	212	mapping: Schema.optional(
	213	Schema.Record({
	214	key: Schema.String,
	215	value: ShapeSymbolIdSchema,
	216	}),
	217	),
	218	});
	219
	220	export const ScalarShapeSchema = Schema.Struct({
	221	type: Schema.Literal("scalar"),
	222	scalar: Schema.Literal("string", "number", "integer", "boolean", "null", "bytes"),
	223	format: Schema.optional(Schema.String),
	224	constraints: Schema.optional(
	225	Schema.Record({
	226	key: Schema.String,
	227	value: Schema.Unknown,
	228	}),
	229	),
	230	});
	231
	232	export const UnknownShapeSchema = Schema.Struct({
	233	type: Schema.Literal("unknown"),
	234	reason: Schema.optional(Schema.String),
	235	});
	236
	237	export const ConstShapeSchema = Schema.Struct({
	238	type: Schema.Literal("const"),
	239	value: Schema.Unknown,
	240	});
	241
	242	export const EnumShapeSchema = Schema.Struct({
	243	type: Schema.Literal("enum"),
	244	values: Schema.Array(Schema.Unknown),
	245	});
	246
	247	export const ObjectShapeSchema = Schema.Struct({
	248	type: Schema.Literal("object"),
	249	fields: Schema.Record({
	250	key: Schema.String,
	251	value: FieldSpecSchema,
	252	}),
	253	required: Schema.optional(Schema.Array(Schema.String)),
	254	additionalProperties: Schema.optional(
	255	Schema.Union(Schema.Boolean, ShapeSymbolIdSchema),
	256	),
	257	patternProperties: Schema.optional(
	258	Schema.Record({
	259	key: Schema.String,
	260	value: ShapeSymbolIdSchema,
	261	}),
	262	),
	263	});
	264
	265	export const ArrayShapeSchema = Schema.Struct({
	266	type: Schema.Literal("array"),
	267	itemShapeId: ShapeSymbolIdSchema,
	268	minItems: Schema.optional(Schema.Number),
	269	maxItems: Schema.optional(Schema.Number),
	270	});
	271
	272	export const TupleShapeSchema = Schema.Struct({
	273	type: Schema.Literal("tuple"),
	274	itemShapeIds: Schema.Array(ShapeSymbolIdSchema),
	275	additionalItems: Schema.optional(
	276	Schema.Union(Schema.Boolean, ShapeSymbolIdSchema),
	277	),
	278	});
	279
	280	export const MapShapeSchema = Schema.Struct({
	281	type: Schema.Literal("map"),
	282	valueShapeId: ShapeSymbolIdSchema,
	283	});
	284
	285	export const AllOfShapeSchema = Schema.Struct({
	286	type: Schema.Literal("allOf"),
	287	items: Schema.Array(ShapeSymbolIdSchema),
	288	});
	289
	290	export const AnyOfShapeSchema = Schema.Struct({
	291	type: Schema.Literal("anyOf"),
	292	items: Schema.Array(ShapeSymbolIdSchema),
	293	});
	294
	295	export const OneOfShapeSchema = Schema.Struct({
	296	type: Schema.Literal("oneOf"),
	297	items: Schema.Array(ShapeSymbolIdSchema),
	298	discriminator: Schema.optional(DiscriminatorSpecSchema),
	299	});
	300
	301	export const NullableShapeSchema = Schema.Struct({
	302	type: Schema.Literal("nullable"),
	303	itemShapeId: ShapeSymbolIdSchema,
	304	});
	305
	306	export const RefShapeSchema = Schema.Struct({
	307	type: Schema.Literal("ref"),
	308	target: ShapeSymbolIdSchema,
	309	});
	310
	311	export const NotShapeSchema = Schema.Struct({
	312	type: Schema.Literal("not"),
	313	itemShapeId: ShapeSymbolIdSchema,
	314	});
	315
	316	export const ConditionalShapeSchema = Schema.Struct({
	317	type: Schema.Literal("conditional"),
	318	ifShapeId: ShapeSymbolIdSchema,
	319	thenShapeId: Schema.optional(ShapeSymbolIdSchema),
	320	elseShapeId: Schema.optional(ShapeSymbolIdSchema),
	321	});
	322
	323	export const GraphQLInterfaceShapeSchema = Schema.Struct({
	324	type: Schema.Literal("graphqlInterface"),
	325	fields: Schema.Record({
	326	key: Schema.String,
	327	value: FieldSpecSchema,
	328	}),
	329	possibleTypeIds: Schema.Array(ShapeSymbolIdSchema),
	330	});
	331
	332	export const GraphQLUnionShapeSchema = Schema.Struct({
	333	type: Schema.Literal("graphqlUnion"),
	334	memberTypeIds: Schema.Array(ShapeSymbolIdSchema),
	335	});
	336
	337	export const ShapeNodeSchema = Schema.Union(
	338	UnknownShapeSchema,
	339	ScalarShapeSchema,
	340	ConstShapeSchema,
	341	EnumShapeSchema,
	342	ObjectShapeSchema,
	343	ArrayShapeSchema,
	344	TupleShapeSchema,
	345	MapShapeSchema,
	346	AllOfShapeSchema,
	347	AnyOfShapeSchema,
	348	OneOfShapeSchema,
	349	NullableShapeSchema,
	350	RefShapeSchema,
	351	NotShapeSchema,
	352	ConditionalShapeSchema,
	353	GraphQLInterfaceShapeSchema,
	354	GraphQLUnionShapeSchema,
	355	);
	356
	357	export const AnchorTargetSchema = Schema.Struct({
	358	shapeId: ShapeSymbolIdSchema,
	359	pointer: Schema.optional(Schema.String),
	360	});
	361
	362	export const SchemaResourceSchema = Schema.extend(
	363	Schema.Struct({
	364	id: ResourceIdSchema,
	365	documentId: DocumentIdSchema,
	366	canonicalUri: Schema.String,
	367	baseUri: Schema.String,
	368	dialectUri: Schema.optional(Schema.String),
	369	rootShapeId: Schema.optional(ShapeSymbolIdSchema),
	370	anchors: Schema.Record({
	371	key: Schema.String,
	372	value: AnchorTargetSchema,
	373	}),
	374	dynamicAnchors: Schema.Record({
	375	key: Schema.String,
	376	value: AnchorTargetSchema,
	377	}),
	378	}),
	379	EntityBaseSchema,
	380	);
	381
	382	export const RequestPlacementHintSchema = Schema.Union(
	383	Schema.Struct({
	384	location: Schema.Literal("header", "query", "cookie"),
	385	name: Schema.String,
	386	}),
	387	Schema.Struct({
	388	location: Schema.Literal("body"),
	389	path: Schema.String,
	390	}),
	391	);
	392
	393	export const OAuthFlowSchema = Schema.Struct({
	394	authorizationUrl: Schema.optional(Schema.String),
	395	tokenUrl: Schema.optional(Schema.String),
	396	refreshUrl: Schema.optional(Schema.String),
	397	scopes: Schema.optional(
	398	Schema.Record({
	399	key: Schema.String,
	400	value: Schema.String,
	401	}),
	402	),
	403	});
	404
	405	export const SecurityPlacementSchema = Schema.Struct({
	406	in: Schema.optional(Schema.Literal("header", "query", "cookie")),
	407	name: Schema.optional(Schema.String),
	408	});
	409
	410	export const SecuritySchemeSymbolSchema = Schema.extend(
	411	Schema.Struct({
	412	id: SecuritySchemeSymbolIdSchema,
	413	kind: Schema.Literal("securityScheme"),
	414	schemeType: SecuritySchemeTypeSchema,
	415	docs: Schema.optional(DocumentationBlockSchema),
	416	placement: Schema.optional(SecurityPlacementSchema),
	417	http: Schema.optional(
	418	Schema.Struct({
	419	scheme: Schema.String,
	420	bearerFormat: Schema.optional(Schema.String),
	421	}),
	422	),
	423	apiKey: Schema.optional(
	424	Schema.Struct({
	425	in: Schema.Literal("header", "query", "cookie"),
	426	name: Schema.String,
	427	}),
	428	),
	429	oauth: Schema.optional(
	430	Schema.Struct({
	431	flows: Schema.optional(
	432	Schema.Record({
	433	key: Schema.String,
	434	value: OAuthFlowSchema,
	435	}),
	436	),
	437	scopes: Schema.optional(
	438	Schema.Record({
	439	key: Schema.String,
	440	value: Schema.String,
	441	}),
	442	),
	443	}),
	444	),
	445	custom: Schema.optional(
	446	Schema.Struct({
	447	placementHints: Schema.optional(Schema.Array(RequestPlacementHintSchema)),
	448	}),
	449	),
	450	}),
	451	EntityBaseSchema,
	452	);
	453
	454	export const EncodingSpecSchema = Schema.Struct({
	455	contentType: Schema.optional(Schema.String),
	456	style: Schema.optional(Schema.String),
	457	explode: Schema.optional(Schema.Boolean),
	458	allowReserved: Schema.optional(Schema.Boolean),
	459	headers: Schema.optional(Schema.Array(HeaderSymbolIdSchema)),
	460	});
	461
	462	export const ContentSpecSchema = Schema.Struct({
	463	mediaType: Schema.String,
	464	shapeId: Schema.optional(ShapeSymbolIdSchema),
	465	exampleIds: Schema.optional(Schema.Array(ExampleSymbolIdSchema)),
	466	encoding: Schema.optional(
	467	Schema.Record({
	468	key: Schema.String,
	469	value: EncodingSpecSchema,
	470	}),
	471	),
	472	});
	473
	474	export const ShapeSymbolSchema = Schema.extend(
	475	Schema.Struct({
	476	id: ShapeSymbolIdSchema,
	477	kind: Schema.Literal("shape"),
	478	resourceId: Schema.optional(ResourceIdSchema),
	479	title: Schema.optional(Schema.String),
	480	docs: Schema.optional(DocumentationBlockSchema),
	481	deprecated: Schema.optional(Schema.Boolean),
	482	node: ShapeNodeSchema,
	483	}),
	484	EntityBaseSchema,
	485	);
	486
	487	export const ParameterSymbolSchema = Schema.extend(
	488	Schema.Struct({
	489	id: ParameterSymbolIdSchema,
	490	kind: Schema.Literal("parameter"),
	491	name: Schema.String,
	492	location: ParameterLocationSchema,
	493	required: Schema.optional(Schema.Boolean),
	494	docs: Schema.optional(DocumentationBlockSchema),
	495	deprecated: Schema.optional(Schema.Boolean),
	496	exampleIds: Schema.optional(Schema.Array(ExampleSymbolIdSchema)),
	497	schemaShapeId: Schema.optional(ShapeSymbolIdSchema),
	498	content: Schema.optional(Schema.Array(ContentSpecSchema)),
	499	style: Schema.optional(Schema.String),
	500	explode: Schema.optional(Schema.Boolean),
	501	allowReserved: Schema.optional(Schema.Boolean),
	502	}),
	503	EntityBaseSchema,
	504	);
	505
	506	export const HeaderSymbolSchema = Schema.extend(
	507	Schema.Struct({
	508	id: HeaderSymbolIdSchema,
	509	kind: Schema.Literal("header"),
	510	name: Schema.String,
	511	docs: Schema.optional(DocumentationBlockSchema),
	512	deprecated: Schema.optional(Schema.Boolean),
	513	exampleIds: Schema.optional(Schema.Array(ExampleSymbolIdSchema)),
	514	schemaShapeId: Schema.optional(ShapeSymbolIdSchema),
	515	content: Schema.optional(Schema.Array(ContentSpecSchema)),
	516	style: Schema.optional(Schema.String),
	517	explode: Schema.optional(Schema.Boolean),
	518	}),
	519	EntityBaseSchema,
	520	);
	521
	522	export const RequestBodySymbolSchema = Schema.extend(
	523	Schema.Struct({
	524	id: RequestBodySymbolIdSchema,
	525	kind: Schema.Literal("requestBody"),
	526	docs: Schema.optional(DocumentationBlockSchema),
	527	required: Schema.optional(Schema.Boolean),
	528	contents: Schema.Array(ContentSpecSchema),
	529	}),
	530	EntityBaseSchema,
	531	);
	532
	533	export const ResponseSymbolSchema = Schema.extend(
	534	Schema.Struct({
	535	id: ResponseSymbolIdSchema,
	536	kind: Schema.Literal("response"),
	537	docs: Schema.optional(DocumentationBlockSchema),
	538	headerIds: Schema.optional(Schema.Array(HeaderSymbolIdSchema)),
	539	contents: Schema.optional(Schema.Array(ContentSpecSchema)),
	540	}),
	541	EntityBaseSchema,
	542	);
	543
	544	export const ExampleSymbolSchema = Schema.extend(
	545	Schema.Struct({
	546	id: ExampleSymbolIdSchema,
	547	kind: Schema.Literal("example"),
	548	name: Schema.optional(Schema.String),
	549	docs: Schema.optional(DocumentationBlockSchema),
	550	exampleKind: Schema.Literal("value", "call"),
	551	value: Schema.optional(Schema.Unknown),
	552	externalValue: Schema.optional(Schema.String),
	553	call: Schema.optional(
	554	Schema.Struct({
	555	args: Schema.Record({
	556	key: Schema.String,
	557	value: Schema.Unknown,
	558	}),
	559	result: Schema.optional(Schema.Unknown),
	560	}),
	561	),
	562	}),
	563	EntityBaseSchema,
	564	);
	565
	566	export const SymbolSchema = Schema.Union(
	567	ShapeSymbolSchema,
	568	ParameterSymbolSchema,
	569	RequestBodySymbolSchema,
	570	ResponseSymbolSchema,
	571	HeaderSymbolSchema,
	572	ExampleSymbolSchema,
	573	SecuritySchemeSymbolSchema,
	574	);
	575
	576	export type AuthRequirement =
	577	\| {
	578	readonly kind: "none";
	579	}
	580	\| {
	581	readonly kind: "scheme";
	582	readonly schemeId: SecuritySchemeSymbolId;
	583	readonly scopes?: readonly string[];
	584	}
	585	\| {
	586	readonly kind: "allOf";
	587	readonly items: readonly AuthRequirement[];
	588	}
	589	\| {
	590	readonly kind: "anyOf";
	591	readonly items: readonly AuthRequirement[];
	592	};
	593
	594	export const AuthRequirementSchema = Schema.suspend(() =>
	595	Schema.Union(
	596	Schema.Struct({
	597	kind: Schema.Literal("none"),
	598	}),
	599	Schema.Struct({
	600	kind: Schema.Literal("scheme"),
	601	schemeId: SecuritySchemeSymbolIdSchema,
	602	scopes: Schema.optional(Schema.Array(Schema.String)),
	603	}),
	604	Schema.Struct({
	605	kind: Schema.Literal("allOf"),
	606	items: Schema.Array(AuthRequirementSchema),
	607	}),
	608	Schema.Struct({
	609	kind: Schema.Literal("anyOf"),
	610	items: Schema.Array(AuthRequirementSchema),
	611	}),
	612	)
	613	) as Schema.Schema<AuthRequirement, AuthRequirement, never>;
	614
	615	export const ServerSpecSchema = Schema.Struct({
	616	url: Schema.String,
	617	description: Schema.optional(Schema.String),
	618	variables: Schema.optional(
	619	Schema.Record({
	620	key: Schema.String,
	621	value: Schema.String,
	622	}),
	623	),
	624	});
	625
	626	export const ScopeDefaultsSchema = Schema.Struct({
	627	servers: Schema.optional(Schema.Array(ServerSpecSchema)),
	628	auth: Schema.optional(AuthRequirementSchema),
	629	parameterIds: Schema.optional(Schema.Array(ParameterSymbolIdSchema)),
	630	headerIds: Schema.optional(Schema.Array(HeaderSymbolIdSchema)),
	631	variables: Schema.optional(
	632	Schema.Record({
	633	key: Schema.String,
	634	value: Schema.String,
	635	}),
	636	),
	637	});
	638
	639	export const ScopeSchema = Schema.extend(
	640	Schema.Struct({
	641	id: ScopeIdSchema,
	642	kind: ScopeKindSchema,
	643	parentId: Schema.optional(ScopeIdSchema),
	644	name: Schema.optional(Schema.String),
	645	namespace: Schema.optional(Schema.String),
	646	docs: Schema.optional(DocumentationBlockSchema),
	647	defaults: Schema.optional(ScopeDefaultsSchema),
	648	}),
	649	EntityBaseSchema,
	650	);
	651
	652	export const InteractionSpecSchema = Schema.Struct({
	653	approval: Schema.Struct({
	654	mayRequire: Schema.Boolean,
	655	reasons: Schema.optional(
	656	Schema.Array(
	657	Schema.Literal("write", "delete", "sensitive", "externalSideEffect"),
	658	),
	659	),
	660	}),
	661	elicitation: Schema.Struct({
	662	mayRequest: Schema.Boolean,
	663	shapeId: Schema.optional(ShapeSymbolIdSchema),
	664	}),
	665	resume: Schema.Struct({
	666	supported: Schema.Boolean,
	667	}),
	668	});
	669
	670	export const CapabilitySchema = Schema.extend(
	671	Schema.Struct({
	672	id: CapabilityIdSchema,
	673	serviceScopeId: ScopeIdSchema,
	674	surface: Schema.Struct({
	675	toolPath: Schema.Array(Schema.String),
	676	title: Schema.optional(Schema.String),
	677	summary: Schema.optional(Schema.String),
	678	description: Schema.optional(Schema.String),
	679	aliases: Schema.optional(Schema.Array(Schema.String)),
	680	tags: Schema.optional(Schema.Array(Schema.String)),
	681	}),
	682	semantics: Schema.Struct({
	683	effect: EffectKindSchema,
	684	safe: Schema.optional(Schema.Boolean),
	685	idempotent: Schema.optional(Schema.Boolean),
	686	destructive: Schema.optional(Schema.Boolean),
	687	}),
	688	docs: Schema.optional(DocumentationBlockSchema),
	689	auth: AuthRequirementSchema,
	690	interaction: InteractionSpecSchema,
	691	executableIds: Schema.Array(ExecutableIdSchema),
	692	preferredExecutableId: Schema.optional(ExecutableIdSchema),
	693	exampleIds: Schema.optional(Schema.Array(ExampleSymbolIdSchema)),
	694	}),
	695	EntityBaseSchema,
	696	);
	697
	698	export const HttpExecutableSchema = Schema.extend(
	699	Schema.Struct({
	700	id: ExecutableIdSchema,
	701	protocol: Schema.Literal("http"),
	702	capabilityId: CapabilityIdSchema,
	703	scopeId: ScopeIdSchema,
	704	method: Schema.String,
	705	pathTemplate: Schema.String,
	706	pathParameterIds: Schema.optional(Schema.Array(ParameterSymbolIdSchema)),
	707	queryParameterIds: Schema.optional(Schema.Array(ParameterSymbolIdSchema)),
	708	headerParameterIds: Schema.optional(Schema.Array(ParameterSymbolIdSchema)),
	709	cookieParameterIds: Schema.optional(Schema.Array(ParameterSymbolIdSchema)),
	710	requestBodyId: Schema.optional(RequestBodySymbolIdSchema),
	711	responseSetId: ResponseSetIdSchema,
	712	}),
	713	EntityBaseSchema,
	714	);
	715
	716	export const GraphQLExecutableSchema = Schema.extend(
	717	Schema.Struct({
	718	id: ExecutableIdSchema,
	719	protocol: Schema.Literal("graphql"),
	720	capabilityId: CapabilityIdSchema,
	721	scopeId: ScopeIdSchema,
	722	toolKind: GraphQLToolKindSchema,
	723	operationType: Schema.Literal("query", "mutation", "subscription"),
	724	rootField: Schema.String,
	725	operationName: Schema.optional(Schema.String),
	726	operationDocument: Schema.optional(Schema.String),
	727	argumentShapeId: ShapeSymbolIdSchema,
	728	resultShapeId: ShapeSymbolIdSchema,
	729	selectionShapeId: Schema.optional(ShapeSymbolIdSchema),
	730	selectionMode: SelectionModeSchema,
	731	responseSetId: ResponseSetIdSchema,
	732	}),
	733	EntityBaseSchema,
	734	);
	735
	736	export const McpExecutableSchema = Schema.extend(
	737	Schema.Struct({
	738	id: ExecutableIdSchema,
	739	protocol: Schema.Literal("mcp"),
	740	capabilityId: CapabilityIdSchema,
	741	scopeId: ScopeIdSchema,
	742	serverRef: Schema.String,
	743	toolName: Schema.String,
	744	inputShapeId: Schema.optional(ShapeSymbolIdSchema),
	745	outputShapeId: Schema.optional(ShapeSymbolIdSchema),
	746	responseSetId: ResponseSetIdSchema,
	747	}),
	748	EntityBaseSchema,
	749	);
	750
	751	export const ExecutableSchema = Schema.Union(
	752	HttpExecutableSchema,
	753	GraphQLExecutableSchema,
	754	McpExecutableSchema,
	755	);
	756
	757	export const PaginationHintSchema = Schema.Struct({
	758	kind: PaginationHintKindSchema,
	759	tokenParamName: Schema.optional(Schema.String),
	760	nextFieldPath: Schema.optional(Schema.String),
	761	});
	762
	763	export const StatusMatchSchema = Schema.Union(
	764	Schema.Struct({
	765	kind: Schema.Literal("exact"),
	766	status: Schema.Number,
	767	}),
	768	Schema.Struct({
	769	kind: Schema.Literal("range"),
	770	value: StatusRangeSchema,
	771	}),
	772	Schema.Struct({
	773	kind: Schema.Literal("default"),
	774	}),
	775	);
	776
	777	export const ResponseVariantSchema = Schema.Struct({
	778	match: StatusMatchSchema,
	779	responseId: ResponseSymbolIdSchema,
	780	traits: Schema.optional(Schema.Array(ResponseTraitSchema)),
	781	pagination: Schema.optional(PaginationHintSchema),
	782	});
	783
	784	export const ResponseSetSchema = Schema.extend(
	785	Schema.Struct({
	786	id: ResponseSetIdSchema,
	787	variants: Schema.Array(ResponseVariantSchema),
	788	}),
	789	EntityBaseSchema,
	790	);
	791
	792	export const ImportDiagnosticSchema = Schema.Struct({
	793	id: DiagnosticIdSchema,
	794	level: DiagnosticLevelSchema,
	795	code: DiagnosticCodeSchema,
	796	message: Schema.String,
	797	relatedSymbolIds: Schema.optional(Schema.Array(SymbolIdSchema)),
	798	provenance: Schema.Array(ProvenanceRefSchema),
	799	});
	800
	801	export const CatalogV1Schema = Schema.Struct({
	802	version: Schema.Literal("ir.v1"),
	803	documents: Schema.Record({
	804	key: DocumentIdSchema,
	805	value: SourceDocumentSchema,
	806	}),
	807	resources: Schema.Record({
	808	key: ResourceIdSchema,
	809	value: SchemaResourceSchema,
	810	}),
	811	scopes: Schema.Record({
	812	key: ScopeIdSchema,
	813	value: ScopeSchema,
	814	}),
	815	symbols: Schema.Record({
	816	key: Schema.String,
	817	value: SymbolSchema,
	818	}),
	819	capabilities: Schema.Record({
	820	key: CapabilityIdSchema,
	821	value: CapabilitySchema,
	822	}),
	823	executables: Schema.Record({
	824	key: ExecutableIdSchema,
	825	value: ExecutableSchema,
	826	}),
	827	responseSets: Schema.Record({
	828	key: ResponseSetIdSchema,
	829	value: ResponseSetSchema,
	830	}),
	831	diagnostics: Schema.Record({
	832	key: DiagnosticIdSchema,
	833	value: ImportDiagnosticSchema,
	834	}),
	835	});
	836
	837	export const CatalogFragmentV1Schema = Schema.Struct({
	838	version: Schema.Literal("ir.v1.fragment"),
	839	documents: Schema.optional(
	840	Schema.Record({
	841	key: DocumentIdSchema,
	842	value: SourceDocumentSchema,
	843	}),
	844	),
	845	resources: Schema.optional(
	846	Schema.Record({
	847	key: ResourceIdSchema,
	848	value: SchemaResourceSchema,
	849	}),
	850	),
	851	scopes: Schema.optional(
	852	Schema.Record({
	853	key: ScopeIdSchema,
	854	value: ScopeSchema,
	855	}),
	856	),
	857	symbols: Schema.optional(
	858	Schema.Record({
	859	key: Schema.String,
	860	value: SymbolSchema,
	861	}),
	862	),
	863	capabilities: Schema.optional(
	864	Schema.Record({
	865	key: CapabilityIdSchema,
	866	value: CapabilitySchema,
	867	}),
	868	),
	869	executables: Schema.optional(
	870	Schema.Record({
	871	key: ExecutableIdSchema,
	872	value: ExecutableSchema,
	873	}),
	874	),
	875	responseSets: Schema.optional(
	876	Schema.Record({
	877	key: ResponseSetIdSchema,
	878	value: ResponseSetSchema,
	879	}),
	880	),
	881	diagnostics: Schema.optional(
	882	Schema.Record({
	883	key: DiagnosticIdSchema,
	884	value: ImportDiagnosticSchema,
	885	}),
	886	),
	887	});
	888
	889	export const CatalogSnapshotV1Schema = Schema.Struct({
	890	version: Schema.Literal("ir.v1.snapshot"),
	891	import: ImportMetadataSchema,
	892	catalog: CatalogV1Schema,
	893	});
	894
	895	export type SourceKind = typeof SourceKindSchema.Type;
	896	export type ScopeKind = typeof ScopeKindSchema.Type;
	897	export type EffectKind = typeof EffectKindSchema.Type;
	898	export type ParameterLocation = typeof ParameterLocationSchema.Type;
	899	export type ResponseTrait = typeof ResponseTraitSchema.Type;
	900	export type SecuritySchemeType = typeof SecuritySchemeTypeSchema.Type;
	901	export type SelectionMode = typeof SelectionModeSchema.Type;
	902	export type GraphQLToolKind = typeof GraphQLToolKindSchema.Type;
	903	export type PaginationHintKind = typeof PaginationHintKindSchema.Type;
	904	export type DiagnosticCode = typeof DiagnosticCodeSchema.Type;
	905	export type DiagnosticLevel = typeof DiagnosticLevelSchema.Type;
	906
	907	export type DocumentationBlock = typeof DocumentationBlockSchema.Type;
	908	export type ProvenanceRef = typeof ProvenanceRefSchema.Type;
	909	export type NativeBlob = typeof NativeBlobSchema.Type;
	910	export type EntityBase = typeof EntityBaseSchema.Type;
	911	export type ImportMetadata = typeof ImportMetadataSchema.Type;
	912	export type SourceDocument = typeof SourceDocumentSchema.Type;
	913	export type FieldSpec = typeof FieldSpecSchema.Type;
	914	export type DiscriminatorSpec = typeof DiscriminatorSpecSchema.Type;
	915	export type ScalarShape = typeof ScalarShapeSchema.Type;
	916	export type UnknownShape = typeof UnknownShapeSchema.Type;
	917	export type ConstShape = typeof ConstShapeSchema.Type;
	918	export type EnumShape = typeof EnumShapeSchema.Type;
	919	export type ObjectShape = typeof ObjectShapeSchema.Type;
	920	export type ArrayShape = typeof ArrayShapeSchema.Type;
	921	export type TupleShape = typeof TupleShapeSchema.Type;
	922	export type MapShape = typeof MapShapeSchema.Type;
	923	export type AllOfShape = typeof AllOfShapeSchema.Type;
	924	export type AnyOfShape = typeof AnyOfShapeSchema.Type;
	925	export type OneOfShape = typeof OneOfShapeSchema.Type;
	926	export type NullableShape = typeof NullableShapeSchema.Type;
	927	export type RefShape = typeof RefShapeSchema.Type;
	928	export type NotShape = typeof NotShapeSchema.Type;
	929	export type ConditionalShape = typeof ConditionalShapeSchema.Type;
	930	export type GraphQLInterfaceShape = typeof GraphQLInterfaceShapeSchema.Type;
	931	export type GraphQLUnionShape = typeof GraphQLUnionShapeSchema.Type;
	932	export type ShapeNode = typeof ShapeNodeSchema.Type;
	933	export type AnchorTarget = typeof AnchorTargetSchema.Type;
	934	export type SchemaResource = typeof SchemaResourceSchema.Type;
	935	export type RequestPlacementHint = typeof RequestPlacementHintSchema.Type;
	936	export type OAuthFlow = typeof OAuthFlowSchema.Type;
	937	export type SecurityPlacement = typeof SecurityPlacementSchema.Type;
	938	export type SecuritySchemeSymbol = typeof SecuritySchemeSymbolSchema.Type;
	939	export type EncodingSpec = typeof EncodingSpecSchema.Type;
	940	export type ContentSpec = typeof ContentSpecSchema.Type;
	941	export type ShapeSymbol = typeof ShapeSymbolSchema.Type;
	942	export type ParameterSymbol = typeof ParameterSymbolSchema.Type;
	943	export type HeaderSymbol = typeof HeaderSymbolSchema.Type;
	944	export type RequestBodySymbol = typeof RequestBodySymbolSchema.Type;
	945	export type ResponseSymbol = typeof ResponseSymbolSchema.Type;
	946	export type ExampleSymbol = typeof ExampleSymbolSchema.Type;
	947	export type Symbol =
	948	\| ShapeSymbol
	949	\| ParameterSymbol
	950	\| RequestBodySymbol
	951	\| ResponseSymbol
	952	\| HeaderSymbol
	953	\| ExampleSymbol
	954	\| SecuritySchemeSymbol;
	955	export type ServerSpec = typeof ServerSpecSchema.Type;
	956	export type ScopeDefaults = typeof ScopeDefaultsSchema.Type;
	957	export type Scope = typeof ScopeSchema.Type;
	958	export type InteractionSpec = typeof InteractionSpecSchema.Type;
	959	export type Capability = typeof CapabilitySchema.Type;
	960	export type HttpExecutable = typeof HttpExecutableSchema.Type;
	961	export type GraphQLExecutable = typeof GraphQLExecutableSchema.Type;
	962	export type McpExecutable = typeof McpExecutableSchema.Type;
	963	export type Executable = typeof ExecutableSchema.Type;
	964	export type PaginationHint = typeof PaginationHintSchema.Type;
	965	export type StatusMatch = typeof StatusMatchSchema.Type;
	966	export type ResponseVariant = typeof ResponseVariantSchema.Type;
	967	export type ResponseSet = typeof ResponseSetSchema.Type;
	968	export type ImportDiagnostic = typeof ImportDiagnosticSchema.Type;
	969	export type CatalogV1 = typeof CatalogV1Schema.Type;
	970	export type CatalogFragmentV1 = typeof CatalogFragmentV1Schema.Type;
	971	export type CatalogSnapshotV1 = typeof CatalogSnapshotV1Schema.Type;

packages/kernel/ir/tsconfig.json+15−0

@@ -0,0 +1,15 @@
	1	{
	2	"compilerOptions": {
	3	"target": "ES2022",
	4	"module": "ESNext",
	5	"moduleResolution": "Bundler",
	6	"strict": true,
	7	"skipLibCheck": true,
	8	"noEmit": true,
	9	"lib": ["ES2022"],
	10	"types": ["bun-types", "node"]
	11	},
	12	"include": [
	13	"src/*/.ts"
	14	]
	15	}

move ir into kernel

Keyboard shortcuts

General

Issues and pull requests

Issues, pull requests and Inbox

Repository code