@cat-factory/agents 0.94.0 → 0.96.0

package/dist/agents/prompts/bespoke-kinds.js

@@ -0,0 +1,114 @@
+import { baseSystemPromptFor } from '../catalog.js';
+import { INLINE_ENGINE_SYSTEM_PROMPTS } from './inline-engine.js';
+import { FINAL_ANSWER_IN_REPLY } from './shared.js';
+// The two bespoke CONTAINER prompts (`merger`, `on-call`) and the map that collects every kind
+// whose prompt is a bespoke constant rather than a `systemPromptFor` composition.
+//
+// Each is declared as a ROLE half and a DIRECTIVES half rather than one string, because a
+// workspace can replace the role from the pipeline builder (and a registered agent-kind VARIANT
+// can replace it in code — see ../kinds/variants.ts). The directives half is what
+// `applySurfaceDirectives` is for every other kind — the read-only guardrail, the machine-parsed
+// output contract, and the answer-in-your-reply rule — so it must survive a replacement rather
+// than be editable prose inside it. Each `*_DIRECTIVES` string CARRIES ITS OWN LEADING SEPARATOR,
+// exactly as the appended directives do on the `systemPromptFor` path (where they are recovered
+// by slicing the base off), so `role + directives` is the shipped prompt byte for byte.
+// `promptOverrides.spec.ts` pins that.
+//
+// This lives in `@cat-factory/agents` rather than beside the container executor that dispatches
+// the two kinds because the ENGINE needs the same answer: it resolves a variant's prompt against
+// the SHIPPED base once per dispatch, and a bespoke kind's shipped base is its role half, not
+// what `baseSystemPromptFor` would return. With the map in the HTTP layer the engine could only
+// have guessed, and would have folded a variant's addition onto the wrong text for exactly the
+// two kinds whose prompts carry a parsed output contract.
+/**
+ * The EDITABLE half of the `merger` prompt: what the agent is for. Replaced wholesale by a
+ * workspace override, so it must carry no invariant the engine depends on.
+ */
+export const MERGER_ROLE_PROMPT = 'You are a release manager assessing a pull request before merge. Inspect the ' +
+    'change (the diff between the pull-request branch(es) and their base) and judge three axes, ' +
+    'each as a number from 0 (trivial/safe) to 1 (severe): complexity (how intricate the ' +
+    'change is), risk (how likely it is to break something), and impact (blast radius ' +
+    'if it does). When the change spans several repositories, weigh the COMBINED cross-repo ' +
+    'change as one and return a single assessment. Be conservative.';
+/**
+ * The NON-EDITABLE half: the JSON contract `resolveMergerStep` parses, and the rule that keeps a
+ * reasoning model's answer out of its hidden channel. Re-appended on top of an override — an
+ * override that could drop these fails the run in exactly the ways they exist to prevent (an
+ * empty visible reply the harness reads as unusable; a merge decision with nothing to parse).
+ */
+export const MERGER_DIRECTIVES = ' Respond with ONLY a JSON ' +
+    'object of shape {"complexity":0.0,"risk":0.0,"impact":0.0,"rationale":"…"} — no prose, ' +
+    'no code fences. ' +
+    FINAL_ANSWER_IN_REPLY;
+/** Role prompt the `merger` step runs under (scores the PR; returns JSON only). */
+export const MERGER_SYSTEM_PROMPT = MERGER_ROLE_PROMPT + MERGER_DIRECTIVES;
+/**
+ * The EDITABLE half of the `on-call` prompt: what the agent is investigating and how to weigh
+ * it. Replaced wholesale by a workspace override — note that the read-only guardrail is
+ * deliberately NOT here, since an on-call agent that could be told to commit is the specific
+ * accident this split prevents.
+ */
+export const ON_CALL_ROLE_PROMPT = 'You are an on-call engineer investigating a possible post-release regression. A ' +
+    'recently merged pull request shipped, and the evidence below (alerting Datadog ' +
+    'monitors/SLOs and recent error logs) suggests the service regressed afterward. Read ' +
+    'the PR diff on the head branch and weigh whether THIS change is the likely cause — ' +
+    'beware correlation vs causation; a coincident deploy is not proof.';
+/**
+ * The NON-EDITABLE half: the read-only guardrail (this kind investigates, a human decides
+ * whether to revert — see `resolveOnCallStep`), the JSON contract the engine parses, and the
+ * answer-in-your-reply rule. Re-appended on top of an override.
+ */
+export const ON_CALL_DIRECTIVES = ' You may read and ' +
+    'inspect any file, but you MUST NOT modify, commit or revert anything; a human decides ' +
+    'whether to revert. Respond with ONLY a JSON object of shape ' +
+    '{"culpritConfidence":0.0,"recommendation":"revert"|"hold"|"monitor","rationale":"…",' +
+    '"evidence":["…"]} — no prose, no code fences. ' +
+    FINAL_ANSWER_IN_REPLY;
+/** Role prompt the `on-call` step runs under (investigates a regression; returns JSON only). */
+export const ON_CALL_SYSTEM_PROMPT = ON_CALL_ROLE_PROMPT + ON_CALL_DIRECTIVES;
+/**
+ * Every kind whose prompt is a bespoke constant rather than a `systemPromptFor` composition,
+ * keyed by agent kind and SPLIT at the boundary a replacement may cross
+ * ({@link BespokeSystemPrompt}).
+ *
+ * Two families, for the same reason. The container kinds `merger` and `on-call` dispatch a
+ * bespoke constant (both return a strict JSON assessment whose contract is stated in that
+ * prompt); the inline ENGINE steps — the requirements + clarity reviewers, both brainstorm
+ * stages, their rework editors and the Requirement Writer — are driven by
+ * `IterativeReviewService` as bare inline calls. Neither family passes through `systemPromptFor`,
+ * so neither gets its override applied or its invariants re-appended by that seam.
+ *
+ * Collected here so the prompt EDITOR, the RUN and a code-registered VARIANT agree on what "the
+ * built-in prompt for this kind" is. With the constants only inlined, an editor built on
+ * `systemPromptFor` showed the merger's thin one-line role — and the requirements reviewer's
+ * `roles.ts` line — as the baseline while something else entirely ran: "restore the built-in"
+ * restored a prompt that was never running, and a diff against the baseline was noise.
+ *
+ * Adding another such kind means adding it here, SPLIT — a kind added with its directives inside
+ * `role` compiles and runs fine, and fails only later, as a workspace that edited it loses its
+ * guardrail or its JSON contract.
+ *
+ * The two container kind ids are bare literals: their canonical constants live in kernel
+ * (`ON_CALL_AGENT_KIND`) and orchestration (`MERGER_AGENT_KIND`), and this package sits below
+ * both. Pinned by `promptOverrides.spec.ts`, which resolves them through those constants.
+ */
+export const BESPOKE_SYSTEM_PROMPTS = {
+    ...INLINE_ENGINE_SYSTEM_PROMPTS,
+    merger: { role: MERGER_ROLE_PROMPT, directives: MERGER_DIRECTIVES },
+    'on-call': { role: ON_CALL_ROLE_PROMPT, directives: ON_CALL_DIRECTIVES },
+};
+/**
+ * The SHIPPED prompt for a kind — the unit a per-workspace override or a registered variant
+ * REPLACES, and what the prompt editor shows as the baseline to diff against and restore to.
+ *
+ * It excludes the surface directives and trait guidance `systemPromptFor` layers on (and, for a
+ * bespoke kind, its `directives` half), because those are invariants of how the platform runs
+ * the kind (a read-only kind must not edit; a reasoning kind's answer must land in its visible
+ * reply) rather than editorial content. They are re-applied on top of a replacement, so handing
+ * them to an editor would only let someone delete something that comes back anyway — or, worse,
+ * duplicate it on save.
+ */
+export function shippedBasePromptFor(kind, registry) {
+    return BESPOKE_SYSTEM_PROMPTS[kind]?.role ?? baseSystemPromptFor(kind, registry);
+}
+//# sourceMappingURL=bespoke-kinds.js.map

package/dist/agents/prompts/bespoke-kinds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bespoke-kinds.js","sourceRoot":"","sources":["../../../src/agents/prompts/bespoke-kinds.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AAEnD,OAAO,EAAE,4BAA4B,EAAE,MAAM,oBAAoB,CAAA;AACjE,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAEnD,+FAA+F;AAC/F,kFAAkF;AAClF,EAAE;AACF,0FAA0F;AAC1F,gGAAgG;AAChG,kFAAkF;AAClF,iGAAiG;AACjG,+FAA+F;AAC/F,kGAAkG;AAClG,gGAAgG;AAChG,wFAAwF;AACxF,uCAAuC;AACvC,EAAE;AACF,gGAAgG;AAChG,iGAAiG;AACjG,8FAA8F;AAC9F,gGAAgG;AAChG,+FAA+F;AAC/F,0DAA0D;AAE1D;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAC7B,+EAA+E;IAC/E,6FAA6F;IAC7F,sFAAsF;IACtF,mFAAmF;IACnF,yFAAyF;IACzF,gEAAgE,CAAA;AAElE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAC5B,4BAA4B;IAC5B,yFAAyF;IACzF,kBAAkB;IAClB,qBAAqB,CAAA;AAEvB,mFAAmF;AACnF,MAAM,CAAC,MAAM,oBAAoB,GAAG,kBAAkB,GAAG,iBAAiB,CAAA;AAE1E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAC9B,kFAAkF;IAClF,iFAAiF;IACjF,sFAAsF;IACtF,qFAAqF;IACrF,oEAAoE,CAAA;AAEtE;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAC7B,oBAAoB;IACpB,wFAAwF;IACxF,8DAA8D;IAC9D,sFAAsF;IACtF,gDAAgD;IAChD,qBAAqB,CAAA;AAEvB,gGAAgG;AAChG,MAAM,CAAC,MAAM,qBAAqB,GAAG,mBAAmB,GAAG,kBAAkB,CAAA;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAoD;IACrF,GAAG,4BAA4B;IAC/B,MAAM,EAAE,EAAE,IAAI,EAAE,kBAAkB,EAAE,UAAU,EAAE,iBAAiB,EAAE;IACnE,SAAS,EAAE,EAAE,IAAI,EAAE,mBAAmB,EAAE,UAAU,EAAE,kBAAkB,EAAE;CACzE,CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAe,EAAE,QAA2B;IAC/E,OAAO,sBAAsB,CAAC,IAAI,CAAC,EAAE,IAAI,IAAI,mBAAmB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAA;AAClF,CAAC"}

package/dist/foundationalServices/FoundationalServiceCatalogService.d.ts

@@ -0,0 +1,65 @@
+import type { ApiContractDocument, CreateFoundationalServiceInput, FoundationalService, FoundationalServiceOwnerKind, ResolvedFoundationalService, UpdateFoundationalServiceInput } from '@cat-factory/contracts';
+import type { ApiContractRepository, Clock, FoundationalServiceRepository, GroupCacheHandle, WorkspaceRepository } from '@cat-factory/kernel';
+export interface FoundationalServiceCatalogDependencies {
+    foundationalServiceRepository: FoundationalServiceRepository;
+    apiContractRepository: ApiContractRepository;
+    workspaceRepository: WorkspaceRepository;
+    clock: Clock;
+    /** The merged per-workspace catalog cache. Absent (tests) ⇒ every resolve reads through. */
+    catalogCache?: GroupCacheHandle<ResolvedFoundationalService[]>;
+}
+/**
+ * The foundational-services catalog (docs/initiatives/foundational-services.md): per-tier CRUD
+ * plus the merged account ⊕ workspace resolve every design dispatch reads.
+ *
+ * Two properties are load-bearing and are why this is a service rather than a repository call:
+ *
+ * - **The catalog never carries a contract BODY.** `listTier` and `resolve` join the contract
+ *   MANIFEST (id, format, title, byte size, operation names) onto each service in ONE extra
+ *   query for the whole tier. The documents are read only by {@link contractsFor}, and only for
+ *   the ids a caller asks for.
+ * - **A workspace row wins over an account row of the same id, and a workspace TOMBSTONE
+ *   suppresses one.** That is what lets a board opt out of an org-wide service without an
+ *   account admin, and it is why the merge reads the workspace tier `includeDeleted`.
+ */
+export declare class FoundationalServiceCatalogService {
+    private readonly deps;
+    constructor(deps: FoundationalServiceCatalogDependencies);
+    /** One tier's registered services, contract manifests joined on. Raw — not merged. */
+    listTier(ownerKind: FoundationalServiceOwnerKind, ownerId: string): Promise<FoundationalService[]>;
+    /** Register a service at a tier. */
+    create(ownerKind: FoundationalServiceOwnerKind, ownerId: string, input: CreateFoundationalServiceInput): Promise<FoundationalService>;
+    /** Patch a registered service. `contracts`, when present, replaces the whole set. */
+    update(ownerKind: FoundationalServiceOwnerKind, ownerId: string, serviceId: string, input: UpdateFoundationalServiceInput): Promise<FoundationalService>;
+    /**
+     * Remove a service from a tier. A WORKSPACE removal writes a tombstone (which is also how a
+     * board suppresses an inherited account service); an ACCOUNT removal drops the row and its
+     * documents outright, since there is no higher tier for it to shadow.
+     */
+    remove(ownerKind: FoundationalServiceOwnerKind, ownerId: string, serviceId: string): Promise<void>;
+    /**
+     * Suppress an ACCOUNT service for one workspace by writing a workspace-tier tombstone. The
+     * row carries no content of its own — it exists only to lose the merge — so it is written
+     * here rather than through {@link create}, which would demand a name and summary for
+     * something that is never rendered.
+     */
+    suppressForWorkspace(workspaceId: string, serviceId: string): Promise<void>;
+    /** The merged catalog a workspace's agents see, cached per workspace. */
+    resolve(workspaceId: string): Promise<ResolvedFoundationalService[]>;
+    /**
+     * The LAZY contract read: full documents for the named services, resolved against the same
+     * account ⊕ workspace precedence the catalog uses. One batched query per tier — never a
+     * per-service read — and an empty `serviceIds` returns `[]` without touching the store.
+     *
+     * Precedence matters here as much as in the catalog: a workspace that overrode a service
+     * must hand out ITS documents, or the design would be reviewed against the org's spec while
+     * the code is written against the board's.
+     */
+    contractsFor(workspaceId: string, serviceIds: string[]): Promise<Map<string, ApiContractDocument[]>>;
+    /** Drop a tier's cached catalog. An account write invalidates every workspace's. */
+    invalidate(ownerKind: FoundationalServiceOwnerKind, ownerId: string): Promise<void>;
+    private loadCatalog;
+    private require;
+    private buildUploadedContracts;
+}
+//# sourceMappingURL=FoundationalServiceCatalogService.d.ts.map

package/dist/foundationalServices/FoundationalServiceCatalogService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FoundationalServiceCatalogService.d.ts","sourceRoot":"","sources":["../../src/foundationalServices/FoundationalServiceCatalogService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EACnB,8BAA8B,EAC9B,mBAAmB,EACnB,4BAA4B,EAC5B,2BAA2B,EAC3B,8BAA8B,EAC/B,MAAM,wBAAwB,CAAA;AAC/B,OAAO,KAAK,EAGV,qBAAqB,EACrB,KAAK,EAEL,6BAA6B,EAC7B,gBAAgB,EAChB,mBAAmB,EACpB,MAAM,qBAAqB,CAAA;AAU5B,MAAM,WAAW,sCAAsC;IACrD,6BAA6B,EAAE,6BAA6B,CAAA;IAC5D,qBAAqB,EAAE,qBAAqB,CAAA;IAC5C,mBAAmB,EAAE,mBAAmB,CAAA;IACxC,KAAK,EAAE,KAAK,CAAA;IACZ,4FAA4F;IAC5F,YAAY,CAAC,EAAE,gBAAgB,CAAC,2BAA2B,EAAE,CAAC,CAAA;CAC/D;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,iCAAiC;IAChC,OAAO,CAAC,QAAQ,CAAC,IAAI;IAAjC,YAA6B,IAAI,EAAE,sCAAsC,EAAI;IAE7E,sFAAsF;IAChF,QAAQ,CACZ,SAAS,EAAE,4BAA4B,EACvC,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAOhC;IAED,oCAAoC;IAC9B,MAAM,CACV,SAAS,EAAE,4BAA4B,EACvC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,8BAA8B,GACpC,OAAO,CAAC,mBAAmB,CAAC,CAsC9B;IAED,qFAAqF;IAC/E,MAAM,CACV,SAAS,EAAE,4BAA4B,EACvC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,8BAA8B,GACpC,OAAO,CAAC,mBAAmB,CAAC,CAmC9B;IAED;;;;OAIG;IACG,MAAM,CACV,SAAS,EAAE,4BAA4B,EACvC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAKf;IAED;;;;;OAKG;IACG,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBhF;IAED,yEAAyE;IACnE,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,2BAA2B,EAAE,CAAC,CAGzE;IAED;;;;;;;;OAQG;IACG,YAAY,CAChB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAAE,GACnB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,mBAAmB,EAAE,CAAC,CAAC,CA0B7C;IAED,oFAAoF;IAC9E,UAAU,CAAC,SAAS,EAAE,4BAA4B,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQxF;YAEa,WAAW;YAoBX,OAAO;IAUrB,OAAO,CAAC,sBAAsB;CAyC/B"}

package/dist/foundationalServices/FoundationalServiceCatalogService.js

@@ -0,0 +1,284 @@
+import { ConflictError, NotFoundError, ValidationError, summarizeContract, } from '@cat-factory/kernel';
+import { mergeFoundationalTiers, toWire } from './foundational-catalog.js';
+import { validateUploadedContract } from './contract-validation.js';
+/**
+ * The foundational-services catalog (docs/initiatives/foundational-services.md): per-tier CRUD
+ * plus the merged account ⊕ workspace resolve every design dispatch reads.
+ *
+ * Two properties are load-bearing and are why this is a service rather than a repository call:
+ *
+ * - **The catalog never carries a contract BODY.** `listTier` and `resolve` join the contract
+ *   MANIFEST (id, format, title, byte size, operation names) onto each service in ONE extra
+ *   query for the whole tier. The documents are read only by {@link contractsFor}, and only for
+ *   the ids a caller asks for.
+ * - **A workspace row wins over an account row of the same id, and a workspace TOMBSTONE
+ *   suppresses one.** That is what lets a board opt out of an org-wide service without an
+ *   account admin, and it is why the merge reads the workspace tier `includeDeleted`.
+ */
+export class FoundationalServiceCatalogService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** One tier's registered services, contract manifests joined on. Raw — not merged. */
+    async listTier(ownerKind, ownerId) {
+        const [records, manifest] = await Promise.all([
+            this.deps.foundationalServiceRepository.listByOwner(ownerKind, ownerId),
+            this.deps.apiContractRepository.listManifestByOwner(ownerKind, ownerId),
+        ]);
+        const byService = indexManifest(manifest);
+        return records.map((record) => toWire(record, byService.get(record.serviceId) ?? []));
+    }
+    /** Register a service at a tier. */
+    async create(ownerKind, ownerId, input) {
+        const existing = await this.deps.foundationalServiceRepository.get(ownerKind, ownerId, input.id);
+        // A LIVE row is a conflict; a tombstoned one is revived by this write. Refusing the
+        // revival would leave an id permanently unusable after one delete.
+        if (existing && !existing.deletedAt) {
+            throw new ConflictError(`Foundational service '${input.id}' already exists at this scope`, 'foundational_service_exists', { serviceId: input.id });
+        }
+        const now = this.deps.clock.now();
+        const record = {
+            serviceId: input.id,
+            ownerKind,
+            ownerId,
+            name: input.name,
+            summary: input.summary,
+            description: input.description,
+            capabilities: input.capabilities ?? [],
+            sourceId: null,
+            sourcePath: null,
+            pinnedCommit: null,
+            createdAt: existing?.createdAt ?? now,
+            updatedAt: now,
+            deletedAt: null,
+        };
+        await this.deps.foundationalServiceRepository.upsert(record);
+        const contracts = this.buildUploadedContracts(ownerKind, ownerId, input.id, input.contracts, now);
+        await this.deps.apiContractRepository.replaceForService(ownerKind, ownerId, input.id, contracts);
+        await this.invalidate(ownerKind, ownerId);
+        return toWire(record, contracts.map(manifestOf));
+    }
+    /** Patch a registered service. `contracts`, when present, replaces the whole set. */
+    async update(ownerKind, ownerId, serviceId, input) {
+        const existing = await this.require(ownerKind, ownerId, serviceId);
+        const now = this.deps.clock.now();
+        const record = {
+            ...existing,
+            name: input.name ?? existing.name,
+            summary: input.summary ?? existing.summary,
+            description: input.description ?? existing.description,
+            capabilities: input.capabilities ?? existing.capabilities,
+            updatedAt: now,
+        };
+        await this.deps.foundationalServiceRepository.upsert(record);
+        let manifest;
+        if (input.contracts) {
+            const contracts = this.buildUploadedContracts(ownerKind, ownerId, serviceId, input.contracts, now);
+            await this.deps.apiContractRepository.replaceForService(ownerKind, ownerId, serviceId, contracts);
+            manifest = contracts.map(manifestOf);
+        }
+        else {
+            manifest = (await this.deps.apiContractRepository.listManifestByOwner(ownerKind, ownerId)).filter((entry) => entry.serviceId === serviceId);
+        }
+        await this.invalidate(ownerKind, ownerId);
+        return toWire(record, manifest);
+    }
+    /**
+     * Remove a service from a tier. A WORKSPACE removal writes a tombstone (which is also how a
+     * board suppresses an inherited account service); an ACCOUNT removal drops the row and its
+     * documents outright, since there is no higher tier for it to shadow.
+     */
+    async remove(ownerKind, ownerId, serviceId) {
+        const now = this.deps.clock.now();
+        await this.deps.foundationalServiceRepository.softDelete(ownerKind, ownerId, serviceId, now);
+        await this.deps.apiContractRepository.deleteForService(ownerKind, ownerId, serviceId);
+        await this.invalidate(ownerKind, ownerId);
+    }
+    /**
+     * Suppress an ACCOUNT service for one workspace by writing a workspace-tier tombstone. The
+     * row carries no content of its own — it exists only to lose the merge — so it is written
+     * here rather than through {@link create}, which would demand a name and summary for
+     * something that is never rendered.
+     */
+    async suppressForWorkspace(workspaceId, serviceId) {
+        const now = this.deps.clock.now();
+        await this.deps.foundationalServiceRepository.upsert({
+            serviceId,
+            ownerKind: 'workspace',
+            ownerId: workspaceId,
+            name: '',
+            summary: '',
+            description: '',
+            capabilities: [],
+            sourceId: null,
+            sourcePath: null,
+            pinnedCommit: null,
+            createdAt: now,
+            updatedAt: now,
+            deletedAt: now,
+        });
+        await this.invalidate('workspace', workspaceId);
+    }
+    /** The merged catalog a workspace's agents see, cached per workspace. */
+    async resolve(workspaceId) {
+        if (!this.deps.catalogCache)
+            return this.loadCatalog(workspaceId);
+        return this.deps.catalogCache.get(workspaceId, workspaceId, () => this.loadCatalog(workspaceId));
+    }
+    /**
+     * The LAZY contract read: full documents for the named services, resolved against the same
+     * account ⊕ workspace precedence the catalog uses. One batched query per tier — never a
+     * per-service read — and an empty `serviceIds` returns `[]` without touching the store.
+     *
+     * Precedence matters here as much as in the catalog: a workspace that overrode a service
+     * must hand out ITS documents, or the design would be reviewed against the org's spec while
+     * the code is written against the board's.
+     */
+    async contractsFor(workspaceId, serviceIds) {
+        const wanted = [...new Set(serviceIds)].filter(Boolean);
+        if (wanted.length === 0)
+            return new Map();
+        const accountId = await this.deps.workspaceRepository.accountOf(workspaceId);
+        const [workspaceDocs, accountDocs] = await Promise.all([
+            this.deps.apiContractRepository.listByServiceIds('workspace', workspaceId, wanted),
+            accountId
+                ? this.deps.apiContractRepository.listByServiceIds('account', accountId, wanted)
+                : Promise.resolve([]),
+        ]);
+        // Which TIER won for each id is decided by the catalog merge, not by which tier happens to
+        // hold documents: a workspace row that overrides an account one but ships no contract of
+        // its own must NOT silently inherit the account's documents, or the override reads as
+        // partially applied. So resolve the winning tier first, then take that tier's documents.
+        const catalog = await this.resolve(workspaceId);
+        const tierById = new Map(catalog.map((entry) => [entry.id, entry.tier]));
+        const out = new Map();
+        for (const id of wanted) {
+            const tier = tierById.get(id);
+            if (!tier)
+                continue;
+            const docs = (tier === 'workspace' ? workspaceDocs : accountDocs).filter((doc) => doc.serviceId === id);
+            out.set(id, docs.map(documentOf));
+        }
+        return out;
+    }
+    /** Drop a tier's cached catalog. An account write invalidates every workspace's. */
+    async invalidate(ownerKind, ownerId) {
+        if (!this.deps.catalogCache)
+            return;
+        // A workspace write affects exactly one group; an account write affects every workspace in
+        // the account, and enumerating them would be a read per invalidation — over-invalidation is
+        // always safe, so the account path drops everything (the same call `FragmentLibraryService`
+        // makes for the same reason).
+        if (ownerKind === 'workspace')
+            await this.deps.catalogCache.invalidateGroup(ownerId);
+        else
+            await this.deps.catalogCache.invalidateAll();
+    }
+    async loadCatalog(workspaceId) {
+        const accountId = await this.deps.workspaceRepository.accountOf(workspaceId);
+        const [workspaceRows, accountRows, workspaceManifest, accountManifest] = await Promise.all([
+            this.deps.foundationalServiceRepository.listByOwner('workspace', workspaceId, true),
+            accountId
+                ? this.deps.foundationalServiceRepository.listByOwner('account', accountId)
+                : Promise.resolve([]),
+            this.deps.apiContractRepository.listManifestByOwner('workspace', workspaceId),
+            accountId
+                ? this.deps.apiContractRepository.listManifestByOwner('account', accountId)
+                : Promise.resolve([]),
+        ]);
+        return mergeFoundationalTiers({
+            accountRows,
+            workspaceRows,
+            accountManifest: indexManifest(accountManifest),
+            workspaceManifest: indexManifest(workspaceManifest),
+        });
+    }
+    async require(ownerKind, ownerId, serviceId) {
+        const record = await this.deps.foundationalServiceRepository.get(ownerKind, ownerId, serviceId);
+        if (!record || record.deletedAt)
+            throw new NotFoundError('FoundationalService', serviceId);
+        return record;
+    }
+    buildUploadedContracts(ownerKind, ownerId, serviceId, uploads, now) {
+        const seen = new Set();
+        return (uploads ?? []).map((upload) => {
+            if (seen.has(upload.contractId)) {
+                throw new ValidationError(`Duplicate contract id '${upload.contractId}'`, {
+                    reason: 'duplicate_contract_id',
+                    contractId: upload.contractId,
+                });
+            }
+            seen.add(upload.contractId);
+            validateUploadedContract(upload);
+            const summary = summarizeContract({
+                contractId: upload.contractId,
+                format: upload.format,
+                title: upload.title,
+                path: null,
+                body: upload.body,
+            });
+            return {
+                ownerKind,
+                ownerId,
+                serviceId,
+                contractId: upload.contractId,
+                format: upload.format,
+                title: upload.title,
+                body: upload.body,
+                operations: summary.operations,
+                omittedOperations: summary.omittedOperations,
+                sourcePath: null,
+                sourceSha: null,
+                createdAt: now,
+                updatedAt: now,
+            };
+        });
+    }
+}
+function indexManifest(entries) {
+    const map = new Map();
+    for (const entry of entries) {
+        const list = map.get(entry.serviceId);
+        if (list)
+            list.push(entry);
+        else
+            map.set(entry.serviceId, [entry]);
+    }
+    return map;
+}
+/**
+ * A just-written contract record → its manifest entry. The operation index is recomputed from
+ * the body here rather than read back, so a create/update response describes exactly what was
+ * stored without a second round trip.
+ */
+function manifestOf(record) {
+    return {
+        serviceId: record.serviceId,
+        contractId: record.contractId,
+        format: record.format,
+        title: record.title,
+        size: record.body.length,
+        operations: record.operations,
+        omittedOperations: record.omittedOperations,
+        sourcePath: record.sourcePath,
+    };
+}
+/**
+ * A stored record → the wire document. The operation index is read off the ROW rather than
+ * recomputed: it is the same index the catalog showed, so a consumer can never see a document
+ * whose operation list disagrees with the one the design was chosen from.
+ */
+function documentOf(record) {
+    return {
+        contractId: record.contractId,
+        format: record.format,
+        title: record.title,
+        size: record.body.length,
+        path: record.sourcePath,
+        operations: record.operations,
+        omittedOperations: record.omittedOperations,
+        body: record.body,
+    };
+}
+//# sourceMappingURL=FoundationalServiceCatalogService.js.map

package/dist/foundationalServices/FoundationalServiceCatalogService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FoundationalServiceCatalogService.js","sourceRoot":"","sources":["../../src/foundationalServices/FoundationalServiceCatalogService.ts"],"names":[],"mappings":"AAkBA,OAAO,EACL,aAAa,EACb,aAAa,EACb,eAAe,EACf,iBAAiB,GAClB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,sBAAsB,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAA;AAC1E,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAA;AAWnE;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,iCAAiC;IACf,IAAI;IAAjC,YAA6B,IAA4C;oBAA5C,IAAI;IAA2C,CAAC;IAE7E,sFAAsF;IACtF,KAAK,CAAC,QAAQ,CACZ,SAAuC,EACvC,OAAe;QAEf,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YAC5C,IAAI,CAAC,IAAI,CAAC,6BAA6B,CAAC,WAAW,CAAC,SAAS,EAAE,OAAO,CAAC;YACvE,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC,mBAAmB,CAAC,SAAS,EAAE,OAAO,CAAC;SACxE,CAAC,CAAA;QACF,MAAM,SAAS,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAA;QACzC,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,CAAA;IACvF,CAAC;IAED,oCAAoC;IACpC,KAAK,CAAC,MAAM,CACV,SAAuC,EACvC,OAAe,EACf,KAAqC;QAErC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,6BAA6B,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC,CAAA;QAChG,oFAAoF;QACpF,mEAAmE;QACnE,IAAI,QAAQ,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,CAAC;YACpC,MAAM,IAAI,aAAa,CACrB,yBAAyB,KAAK,CAAC,EAAE,gCAAgC,EACjE,6BAA6B,EAC7B,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,EAAE,CACxB,CAAA;QACH,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAA;QACjC,MAAM,MAAM,GAA8B;YACxC,SAAS,EAAE,KAAK,CAAC,EAAE;YACnB,SAAS;YACT,OAAO;YACP,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,EAAE;YACtC,QAAQ,EAAE,IAAI;YACd,UAAU,EAAE,IAAI;YAChB,YAAY,EAAE,IAAI;YAClB,SAAS,EAAE,QAAQ,EAAE,SAAS,IAAI,GAAG;YACrC,SAAS,EAAE,GAAG;YACd,SAAS,EAAE,IAAI;SAChB,CAAA;QACD,MAAM,IAAI,CAAC,IAAI,CAAC,6BAA6B,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QAC5D,MAAM,SAAS,GAAG,IAAI,CAAC,sBAAsB,CAC3C,SAAS,EACT,OAAO,EACP,KAAK,CAAC,EAAE,EACR,KAAK,CAAC,SAAS,EACf,GAAG,CACJ,CAAA;QACD,MAAM,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC,iBAAiB,CAAC,SAAS,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,EAAE,SAAS,CAAC,CAAA;QAChG,MAAM,IAAI,CAAC,UAAU,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;QACzC,OAAO,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAA;IAClD,CAAC;IAED,qFAAqF;IACrF,KAAK,CAAC,MAAM,CACV,SAAuC,EACvC,OAAe,EACf,SAAiB,EACjB,KAAqC;QAErC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,CAAC,CAAA;QAClE,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAA;QACjC,MAAM,MAAM,GAA8B;YACxC,GAAG,QAAQ;YACX,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,QAAQ,CAAC,IAAI;YACjC,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,QAAQ,CAAC,OAAO;YAC1C,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,QAAQ,CAAC,WAAW;YACtD,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,QAAQ,CAAC,YAAY;YACzD,SAAS,EAAE,GAAG;SACf,CAAA;QACD,MAAM,IAAI,CAAC,IAAI,CAAC,6BAA6B,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QAC5D,IAAI,QAAoC,CAAA;QACxC,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;YACpB,MAAM,SAAS,GAAG,IAAI,CAAC,sBAAsB,CAC3C,SAAS,EACT,OAAO,EACP,SAAS,EACT,KAAK,CAAC,SAAS,EACf,GAAG,CACJ,CAAA;YACD,MAAM,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC,iBAAiB,CACrD,SAAS,EACT,OAAO,EACP,SAAS,EACT,SAAS,CACV,CAAA;YACD,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,UAAU,CAAC,CAAA;QACtC,CAAC;aAAM,CAAC;YACN,QAAQ,GAAG,CACT,MAAM,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC,mBAAmB,CAAC,SAAS,EAAE,OAAO,CAAC,CAC9E,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,SAAS,KAAK,SAAS,CAAC,CAAA;QACpD,CAAC;QACD,MAAM,IAAI,CAAC,UAAU,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;QACzC,OAAO,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;IACjC,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,MAAM,CACV,SAAuC,EACvC,OAAe,EACf,SAAiB;QAEjB,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAA;QACjC,MAAM,IAAI,CAAC,IAAI,CAAC,6BAA6B,CAAC,UAAU,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,CAAC,CAAA;QAC5F,MAAM,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC,gBAAgB,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,CAAC,CAAA;QACrF,MAAM,IAAI,CAAC,UAAU,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;IAC3C,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,oBAAoB,CAAC,WAAmB,EAAE,SAAiB;QAC/D,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAA;QACjC,MAAM,IAAI,CAAC,IAAI,CAAC,6BAA6B,CAAC,MAAM,CAAC;YACnD,SAAS;YACT,SAAS,EAAE,WAAW;YACtB,OAAO,EAAE,WAAW;YACpB,IAAI,EAAE,EAAE;YACR,OAAO,EAAE,EAAE;YACX,WAAW,EAAE,EAAE;YACf,YAAY,EAAE,EAAE;YAChB,QAAQ,EAAE,IAAI;YACd,UAAU,EAAE,IAAI;YAChB,YAAY,EAAE,IAAI;YAClB,SAAS,EAAE,GAAG;YACd,SAAS,EAAE,GAAG;YACd,SAAS,EAAE,GAAG;SACf,CAAC,CAAA;QACF,MAAM,IAAI,CAAC,UAAU,CAAC,WAAW,EAAE,WAAW,CAAC,CAAA;IACjD,CAAC;IAED,yEAAyE;IACzE,KAAK,CAAC,OAAO,CAAC,WAAmB;QAC/B,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY;YAAE,OAAO,IAAI,CAAC,WAAW,CAAC,WAAW,CAAC,CAAA;QACjE,OAAO,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,WAAW,EAAE,WAAW,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,CAAA;IAClG,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,YAAY,CAChB,WAAmB,EACnB,UAAoB;QAEpB,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;QACvD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,GAAG,EAAE,CAAA;QACzC,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,mBAAmB,CAAC,SAAS,CAAC,WAAW,CAAC,CAAA;QAC5E,MAAM,CAAC,aAAa,EAAE,WAAW,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YACrD,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC,gBAAgB,CAAC,WAAW,EAAE,WAAW,EAAE,MAAM,CAAC;YAClF,SAAS;gBACP,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC,gBAAgB,CAAC,SAAS,EAAE,SAAS,EAAE,MAAM,CAAC;gBAChF,CAAC,CAAC,OAAO,CAAC,OAAO,CAAsB,EAAE,CAAC;SAC7C,CAAC,CAAA;QACF,2FAA2F;QAC3F,yFAAyF;QACzF,sFAAsF;QACtF,yFAAyF;QACzF,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAA;QAC/C,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QACxE,MAAM,GAAG,GAAG,IAAI,GAAG,EAAiC,CAAA;QACpD,KAAK,MAAM,EAAE,IAAI,MAAM,EAAE,CAAC;YACxB,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;YAC7B,IAAI,CAAC,IAAI;gBAAE,SAAQ;YACnB,MAAM,IAAI,GAAG,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,MAAM,CACtE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,SAAS,KAAK,EAAE,CAC9B,CAAA;YACD,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAA;QACnC,CAAC;QACD,OAAO,GAAG,CAAA;IACZ,CAAC;IAED,oFAAoF;IACpF,KAAK,CAAC,UAAU,CAAC,SAAuC,EAAE,OAAe;QACvE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY;YAAE,OAAM;QACnC,2FAA2F;QAC3F,4FAA4F;QAC5F,4FAA4F;QAC5F,8BAA8B;QAC9B,IAAI,SAAS,KAAK,WAAW;YAAE,MAAM,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,eAAe,CAAC,OAAO,CAAC,CAAA;;YAC/E,MAAM,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,aAAa,EAAE,CAAA;IACnD,CAAC;IAEO,KAAK,CAAC,WAAW,CAAC,WAAmB;QAC3C,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,mBAAmB,CAAC,SAAS,CAAC,WAAW,CAAC,CAAA;QAC5E,MAAM,CAAC,aAAa,EAAE,WAAW,EAAE,iBAAiB,EAAE,eAAe,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YACzF,IAAI,CAAC,IAAI,CAAC,6BAA6B,CAAC,WAAW,CAAC,WAAW,EAAE,WAAW,EAAE,IAAI,CAAC;YACnF,SAAS;gBACP,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,6BAA6B,CAAC,WAAW,CAAC,SAAS,EAAE,SAAS,CAAC;gBAC3E,CAAC,CAAC,OAAO,CAAC,OAAO,CAA8B,EAAE,CAAC;YACpD,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC,mBAAmB,CAAC,WAAW,EAAE,WAAW,CAAC;YAC7E,SAAS;gBACP,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC,mBAAmB,CAAC,SAAS,EAAE,SAAS,CAAC;gBAC3E,CAAC,CAAC,OAAO,CAAC,OAAO,CAA6B,EAAE,CAAC;SACpD,CAAC,CAAA;QACF,OAAO,sBAAsB,CAAC;YAC5B,WAAW;YACX,aAAa;YACb,eAAe,EAAE,aAAa,CAAC,eAAe,CAAC;YAC/C,iBAAiB,EAAE,aAAa,CAAC,iBAAiB,CAAC;SACpD,CAAC,CAAA;IACJ,CAAC;IAEO,KAAK,CAAC,OAAO,CACnB,SAAuC,EACvC,OAAe,EACf,SAAiB;QAEjB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,6BAA6B,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,CAAC,CAAA;QAC/F,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,SAAS;YAAE,MAAM,IAAI,aAAa,CAAC,qBAAqB,EAAE,SAAS,CAAC,CAAA;QAC1F,OAAO,MAAM,CAAA;IACf,CAAC;IAEO,sBAAsB,CAC5B,SAAuC,EACvC,OAAe,EACf,SAAiB,EACjB,OAAoD,EACpD,GAAW;QAEX,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;QAC9B,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE;YACpC,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;gBAChC,MAAM,IAAI,eAAe,CAAC,0BAA0B,MAAM,CAAC,UAAU,GAAG,EAAE;oBACxE,MAAM,EAAE,uBAAuB;oBAC/B,UAAU,EAAE,MAAM,CAAC,UAAU;iBAC9B,CAAC,CAAA;YACJ,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,CAAA;YAC3B,wBAAwB,CAAC,MAAM,CAAC,CAAA;YAChC,MAAM,OAAO,GAAG,iBAAiB,CAAC;gBAChC,UAAU,EAAE,MAAM,CAAC,UAAU;gBAC7B,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,IAAI,EAAE,IAAI;gBACV,IAAI,EAAE,MAAM,CAAC,IAAI;aAClB,CAAC,CAAA;YACF,OAAO;gBACL,SAAS;gBACT,OAAO;gBACP,SAAS;gBACT,UAAU,EAAE,MAAM,CAAC,UAAU;gBAC7B,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,UAAU,EAAE,OAAO,CAAC,UAAU;gBAC9B,iBAAiB,EAAE,OAAO,CAAC,iBAAiB;gBAC5C,UAAU,EAAE,IAAI;gBAChB,SAAS,EAAE,IAAI;gBACf,SAAS,EAAE,GAAG;gBACd,SAAS,EAAE,GAAG;aACf,CAAA;QACH,CAAC,CAAC,CAAA;IACJ,CAAC;CACF;AAED,SAAS,aAAa,CACpB,OAAmC;IAEnC,MAAM,GAAG,GAAG,IAAI,GAAG,EAAsC,CAAA;IACzD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAA;QACrC,IAAI,IAAI;YAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;;YACrB,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC,KAAK,CAAC,CAAC,CAAA;IACxC,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;;GAIG;AACH,SAAS,UAAU,CAAC,MAAyB;IAC3C,OAAO;QACL,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM;QACxB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,iBAAiB,EAAE,MAAM,CAAC,iBAAiB;QAC3C,UAAU,EAAE,MAAM,CAAC,UAAU;KAC9B,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,UAAU,CAAC,MAAyB;IAC3C,OAAO;QACL,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM;QACxB,IAAI,EAAE,MAAM,CAAC,UAAU;QACvB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,iBAAiB,EAAE,MAAM,CAAC,iBAAiB;QAC3C,IAAI,EAAE,MAAM,CAAC,IAAI;KAClB,CAAA;AACH,CAAC"}

package/dist/foundationalServices/FoundationalServiceRunResolver.d.ts

@@ -0,0 +1,37 @@
+import type { FoundationalServiceSelection } from '@cat-factory/contracts';
+import type { FoundationalCatalogView, InjectedContextFile } from '@cat-factory/kernel';
+import type { FoundationalServiceCatalogService } from './FoundationalServiceCatalogService.js';
+/**
+ * The engine-facing seam over the foundational-services catalog
+ * (docs/initiatives/foundational-services.md). Two reads, deliberately separate, because they
+ * serve the two halves of the feature:
+ *
+ * - {@link catalogFor} is the DESIGN-time read: identity, capabilities and operation names for
+ *   every registered service, no document bodies. Folded into the Architect's prompt.
+ * - {@link contextFilesFor} is the CONSUMER-time read: the full contract documents, for exactly
+ *   the ids the design declared, materialised as `.cat-context/foundational-services/*` files.
+ *
+ * Implemented against the catalog SERVICE rather than the repositories so both reads go through
+ * the same tier merge and the same cache — a consumer can never be handed the account's
+ * document for a service the design chose at the workspace tier.
+ */
+export declare class FoundationalServiceRunResolver {
+    private readonly catalog;
+    constructor(catalog: FoundationalServiceCatalogService);
+    /** The catalog the design step is shown. Empty array when nothing is registered. */
+    catalogFor(workspaceId: string): Promise<FoundationalCatalogView[]>;
+    /** Just the ids in the merged catalog — the check a settled design's declaration runs against. */
+    catalogIdsFor(workspaceId: string): Promise<string[]>;
+    /**
+     * The injected context files a consumer kind receives for a design's declared services: one
+     * markdown file per service carrying its contract documents, plus an index.
+     *
+     * The INDEX is always produced, even when nothing was declared and nothing resolved. That is
+     * the "degrade loudly" half: a coder handed no foundational context cannot otherwise tell
+     * "the design decided none apply" from "the design step never ran" from "the design named a
+     * service this deployment does not have", and those need three different reactions.
+     */
+    contextFilesFor(workspaceId: string, selection: FoundationalServiceSelection | undefined): Promise<InjectedContextFile[]>;
+    private hasCatalog;
+}
+//# sourceMappingURL=FoundationalServiceRunResolver.d.ts.map

package/dist/foundationalServices/FoundationalServiceRunResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FoundationalServiceRunResolver.d.ts","sourceRoot":"","sources":["../../src/foundationalServices/FoundationalServiceRunResolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,wBAAwB,CAAA;AAC1E,OAAO,KAAK,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAOvF,OAAO,KAAK,EAAE,iCAAiC,EAAE,MAAM,wCAAwC,CAAA;AAE/F;;;;;;;;;;;;;GAaG;AACH,qBAAa,8BAA8B;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAApC,YAA6B,OAAO,EAAE,iCAAiC,EAAI;IAE3E,oFAAoF;IAC9E,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAUxE;IAED,kGAAkG;IAC5F,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAE1D;IAED;;;;;;;;OAQG;IACG,eAAe,CACnB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,4BAA4B,GAAG,SAAS,GAClD,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAyChC;YAEa,UAAU;CAGzB"}

package/dist/foundationalServices/FoundationalServiceRunResolver.js

@@ -0,0 +1,92 @@
+import { FOUNDATIONAL_INDEX_FILE, contextFileFor, renderContractDocument, renderFoundationalIndex, } from '@cat-factory/kernel';
+/**
+ * The engine-facing seam over the foundational-services catalog
+ * (docs/initiatives/foundational-services.md). Two reads, deliberately separate, because they
+ * serve the two halves of the feature:
+ *
+ * - {@link catalogFor} is the DESIGN-time read: identity, capabilities and operation names for
+ *   every registered service, no document bodies. Folded into the Architect's prompt.
+ * - {@link contextFilesFor} is the CONSUMER-time read: the full contract documents, for exactly
+ *   the ids the design declared, materialised as `.cat-context/foundational-services/*` files.
+ *
+ * Implemented against the catalog SERVICE rather than the repositories so both reads go through
+ * the same tier merge and the same cache — a consumer can never be handed the account's
+ * document for a service the design chose at the workspace tier.
+ */
+export class FoundationalServiceRunResolver {
+    catalog;
+    constructor(catalog) {
+        this.catalog = catalog;
+    }
+    /** The catalog the design step is shown. Empty array when nothing is registered. */
+    async catalogFor(workspaceId) {
+        const resolved = await this.catalog.resolve(workspaceId);
+        return resolved.map((service) => ({
+            id: service.id,
+            name: service.name,
+            summary: service.summary,
+            description: service.description,
+            capabilities: service.capabilities,
+            contracts: service.contracts,
+        }));
+    }
+    /** Just the ids in the merged catalog — the check a settled design's declaration runs against. */
+    async catalogIdsFor(workspaceId) {
+        return (await this.catalog.resolve(workspaceId)).map((service) => service.id);
+    }
+    /**
+     * The injected context files a consumer kind receives for a design's declared services: one
+     * markdown file per service carrying its contract documents, plus an index.
+     *
+     * The INDEX is always produced, even when nothing was declared and nothing resolved. That is
+     * the "degrade loudly" half: a coder handed no foundational context cannot otherwise tell
+     * "the design decided none apply" from "the design step never ran" from "the design named a
+     * service this deployment does not have", and those need three different reactions.
+     */
+    async contextFilesFor(workspaceId, selection) {
+        const declared = selection?.declared ?? [];
+        const unknown = selection?.unknown ?? [];
+        const noDeclaration = selection === undefined;
+        // Nothing to say and nothing to warn about: a run in a deployment that registers no
+        // foundational services at all would otherwise pay for an index file on every dispatch
+        // saying so. A declaration that resolved to nothing is DIFFERENT and does get the file.
+        if (noDeclaration && unknown.length === 0 && !(await this.hasCatalog(workspaceId)))
+            return [];
+        const documents = await this.catalog.contractsFor(workspaceId, declared);
+        const resolved = await this.catalog.resolve(workspaceId);
+        const byId = new Map(resolved.map((service) => [service.id, service]));
+        const bundles = declared
+            .map((id) => {
+            const service = byId.get(id);
+            if (!service)
+                return null;
+            return {
+                id: service.id,
+                name: service.name,
+                summary: service.summary,
+                description: service.description,
+                contracts: (documents.get(id) ?? []).map((doc) => ({
+                    contractId: doc.contractId,
+                    format: doc.format,
+                    title: doc.title,
+                    body: doc.body,
+                })),
+            };
+        })
+            .filter((bundle) => bundle !== null);
+        const files = [
+            {
+                path: FOUNDATIONAL_INDEX_FILE,
+                content: renderFoundationalIndex({ bundles, unknown, noDeclaration }),
+            },
+        ];
+        for (const bundle of bundles) {
+            files.push({ path: contextFileFor(bundle.id), content: renderContractDocument(bundle) });
+        }
+        return files;
+    }
+    async hasCatalog(workspaceId) {
+        return (await this.catalog.resolve(workspaceId)).length > 0;
+    }
+}
+//# sourceMappingURL=FoundationalServiceRunResolver.js.map

package/dist/foundationalServices/FoundationalServiceRunResolver.js.map

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