feat(#470): grant-gate ctx.services.get and cut plugin-api 1.0.0 (C2b)

[Weegy]

Closes the second half of C2 in epic #470 Phase A: the G8 contract break and bug B1. Moves zero dev-platform code.

What and why

G8 — the contract break, taken once and deliberately

C2a (#555) already deleted ctx.devJobs and moved the DevJob* view types out of @omadia/plugin-api into middleware/src/devplatform/devJobTypes.ts, where they travel with the extraction and the plugin repo will own them as @omadia/dev-platform-plugin-api. I re-verified that: the package exports zero DevJob* types today, and admin-v1 carries no dev_jobs / DevJob DTO fields (grepping for dev_job|DevJob|devJob in middleware/src/api/admin-v1.ts returns nothing).

What was missing was the record and the version. This PR cuts @omadia/plugin-api 1.0.0 and adds a CHANGELOG.md documenting the break in English. implementation.md §1 row 4 is the rationale: there is no installed base, nothing is published to npm, and every consumer is a repository we control — the break is cheap now and expensive later.

One landmine found: harness-channel-api/package.json pinned "@omadia/plugin-api": "^0.1.0", the only package that did. It would have failed to resolve against the bump. Repinned to "*" like its 22 siblings.

B1 — ctx.services.get was a bare pass-through

pluginContext.ts handed the service registry straight through. Any installed plugin could resolve any registered service — graphPool, the same Postgres pool core uses, included — with no manifest declaration, no operator consent, and nothing in the install dialog. serviceRegistry.ts's own header conceded the design: "This registry is a naked service-locator; enforcement lives at the consumer seam."

The seam now exists: middleware/src/platform/pluginServiceGrants.ts.

get(name) resolves only capability names the plugin declares in requires: — or provides:, so a provider can read back its own registration, which is not an escalation since it holds the implementation anyway. Anything else throws the new typed ServiceNotDeclaredError, naming both the capability and the manifest field that would grant it. No new manifest field is invented: pluginContext.ts's own capability docblock already states that capability names are the service-registry keys.

has stays ungated. It answers a yes/no existence question and hands over no capability; gating it would only turn feature-probing into exception-handling.

A plugin with no catalog entry is granted nothing, mirroring the existing scratchEnabled precedent one function below: an id the kernel cannot find a manifest for is an id whose permissions cannot be checked, and unknown permissions are denied permissions.

The trap this closes (§2.2)

Removing ctx.devJobs without this would have converted a permission-gated, kernel-attributed accessor into an ungated, self-attributed one — the only remaining path being B1's naked locator, with the plugin passing its own pluginId into listGrantedRepoIds.

So provide() now also accepts perCallerService(factory). The kernel invokes the factory with a ServiceCaller built from the id it activated the consumer under, never from an argument the consumer supplies. The consumer's only input is the service name; there is no second parameter through which it could name itself something else, and there is a test asserting services.get.length === 1 so a future refactor cannot quietly add one.

The factory is a symbol-branded object, not a bare function. Detecting it with typeof impl === 'function' would have broken every service that is a function — there is a test registering exactly that and asserting it comes back untouched. Value providers are otherwise entirely unaffected.

ServiceRegistry.get(name, caller?) defaults to KERNEL_SERVICE_CALLER, so core's direct .get() call sites keep working unchanged and are attributed to the kernel rather than to whichever plugin happens to be on the stack.

⚠️ Breaking change — @omadia/plugin-api 0.1.0 → 1.0.0

#	Break	Migration
1	DevJobKind, DevJobStatus, DevJobDescriptor, DevJobCreateRequest, DevJobEventRecord, DevJobsAccessor, PluginContext.devJobs no longer exported	None possible or needed. Nothing ever registered the backing host service, so every call threw. A stale manifest declaring permissions.devJobs still installs and activates unchanged — regression-pinned in manifestDevJobsLegacyKey.test.ts
2	ctx.services.get(name) throws ServiceNotDeclaredError for undeclared names	Add "<name>@<major>" to the manifest's requires:. The dated allowlist below grandfathers everything currently shipped
3	ServicesAccessor.provide / .replace widened to T | PerCallerFactory<T>	Source-compatible for every existing call. Only code that implements ServicesAccessor (the kernel, and test doubles typed against it) sees it

Full detail in middleware/packages/plugin-api/CHANGELOG.md.

Call-site audit — every ctx.services.get in core and all ten plugin repos

Read at main across middleware/packages/* and the standalone repos under ~/sources/omadia-*. Service-name constants were resolved to their literal values. A fail-closed gate in one step would have broken 14 of the 20 plugins that call services.get — hence the ramp.

Plugin	Declared requires:	Resolves	⚠️ Undeclared → allowlisted
@omadia/orchestrator	knowledgeGraph, memoryStore, entityRefBus, embeddingClient, contextRetriever, factExtractor, verifier	17 services	attachmentBindings, audienceGrants, graphPool, nudgeProviders, privacyRedact, responseGuard, sessionBriefing, tigrisStore, turnHookRegistry, turnReceiptStore
@omadia/channel-teams 📦	chatAgent	9	anthropicClient, embeddingClient, graphPool, graphTenantId, microsoft365.graph, tigrisStore, topicDetector, turnContext
@omadia/plugin-plan-runner	—	3	knowledgeGraph, processMemory, turnHookRegistry
@omadia/verifier	knowledgeGraph	3	graphPool, odoo.client
@omadia/orchestrator-extras	knowledgeGraph, embeddingClient	4	agentPriorities, graphPool
@omadia/channel-telegram 📦	chatAgent	3	memoryStore, turnContext
@omadia/agent-odoo-hr 📦	knowledgeGraph	2	odoo.agentToolkit.hr, odoo.client
@omadia/agent-confluence 📦	—	2	confluence.client, confluence.toolkit
@omadia/agent-odoo-accounting 📦	knowledgeGraph	1	odoo.agentToolkit.accounting
@omadia/plugin-office	—	1	privacyRedact
@omadia/diagrams	—	1	memoryStore
@omadia/ui-channel	—	1	graphTenantId
@omadia/knowledge-graph-inmemory	—	1	turnContext
@omadia/knowledge-graph-neon	embeddingClient	2	turnContext
@omadia/memory-postgres	graphPool	1	✅ none
@omadia/ui-orchestrator	chatAgent	1	✅ none
@omadia/integration-odoo 📦	knowledgeGraph	1	✅ none
@omadia/integration-confluence 📦	knowledgeGraph, entityRefBus	2	✅ none
@omadia/plugin-web-search	—	0	✅ none — the apparent hit is a template literal inside a log message, not a call
harness-channel-sdk	(library, no manifest)	chatAgent	✅ none — runs under the calling channel's context; both teams and telegram declare chatAgent@^1

📦 = shipped through hub.omadia.ai from a standalone repo, i.e. cannot be fixed in this PR.

27 (plugin, capability) pairs are grandfathered in LEGACY_UNDECLARED_SERVICE_GRANTS_2026_08_20 — frozen, dated, and keyed per plugin id, not per name. It is closed in both directions:

• a different plugin asking for graphPool still throws;
• an allowlisted plugin asking for a new name still throws.

Both are tested. The object and its inner arrays are Object.freezed, and the test asserts a push onto an inner array throws — freezing only the outer object would have left [...].push('anthropicClient') wide open.

Follow-ups this audit surfaced

1. A real naming defect, not laziness. harness-plugin-privacy-guard declares the capability privacy.redact@1 but registers the service under the key privacyRedact. Capability name and service key disagree, so no requires: entry could grant it — the two privacyRedact allowlist rows cannot be retired until one side is renamed. This contradicts the documented invariant that capability names are service keys.
2. There is no way to declare an optional dependency. requires: doubles as the activation dependency — resolveEligiblePlugins holds back a consumer whose requires are unmet. So a plugin that consumes a service optionally (harness-diagrams → memoryStore, verifier → graphPool) cannot declare it without risking non-activation when no provider is installed. This is the real reason most rows exist, and it wants an optional_requires manifest field. A manifest-schema change is a bigger contract move that belongs in C4/C7, not here.
3. middleware/src/index.ts notes plugins should get the tenant id via ctx.services.get('graphTenantId') — two plugins do, neither declares it.

Counter-proof

Reverting the gate in pluginContext.ts to the original one-liner:

get<T>(name: string): T | undefined {
  return serviceRegistry.get<T>(name);
}

→ 9 of the 25 new tests fail, including throws ServiceNotDeclaredError for a capability the manifest never mentions, invokes the factory with the kernel-known id, and all three allowlist-closure tests. Restoring the gate → 25/25 pass. The tests observe the gate, they do not merely coexist with it.

Decoupling ratchet: 3296 → 3300 (hand-raised, middleware/packages 84 → 89)

First measurement was +31. The avoidable 26 were reworded away, not excused:

• the new gate tests used devJobs as their example capability → renamed to repoGrants (−16);
• a perCallerService docblock example used devJobs/makeDevJobsFor → neutral names (−2);
• the CHANGELOG's type list was spread across four lines → collapsed onto one (−7);
• the edited legacy test's new comment restated the permission key → reworded (−1).

middleware/test is back at its 1,030 baseline, unchanged.

The residual +5 is the new packages/plugin-api/CHANGELOG.md, all of it prose about code that left. A changelog recording that DevJobDescriptor was deleted has to name it, or a consumer grepping its own source finds nothing and the record is worthless. Three of the five lines are literal strings that cannot be reworded at all: a spec path (specs/470-dev-platform-plugin/dormant-capabilities.md), a test filename (manifestDevJobsLegacyKey.test.ts), and the future package name (@omadia/dev-platform-plugin-api) — the same class of justification as #557's path string. The other two are the removal heading and the six type names.

Nothing in core references the dev platform as a result of this PR. Justification recorded consistently in all three places the README demands: decoupling-baseline.json, README.md, and acceptance.md.

Also

plan.md §4.2 still claimed the DevJob* types stay in @omadia/plugin-api as "a published, versioned contract that third-party plugins consume via ctx.devJobs". implementation.md §2.5 had already flagged that this contradicts §4.1 and that two implementers would build incompatible package boundaries. Shipped code now settles it — struck through with a pointer to the resolution rather than silently deleted.

Commands run

Node v22.22.3 via nvm, after merging origin/main (5d2b5608).

cd middleware && npm install && npm run build   # exit 0
npm run typecheck                               # exit 0
npm run typecheck:test                          # exit 0 — 406 known, no regressions
npm run lint                                    # exit 0
DATABASE_URL=postgres://test:test@127.0.0.1:55438/test npm test
                                                # 6771 pass / 4 fail
node scripts/check-core-decoupling.mjs          # exit 0 — held at 3300

The 4 failures are environmental, and I proved it rather than asserting it. They are in palaiaHybridRetrievalNeon.test.ts and neonDatasetFilterEscaping.test.ts, all failing with relation "graph_nodes" / "datasets" does not exist — I stood up a throwaway Postgres on :55438 with no migrated schema. I then stashed this branch's changes entirely and re-ran those two files against the unmodified tree: the same 4 failed. Not a regression from this PR. Zero gate-related failures anywhere in the suite.

web-ui untouched, so its typecheck was not run. package-lock.json moves by exactly 2 lines, both intentional (the version bump and the harness-channel-api repin) — no noise.

Note for the C1 golden snapshot (#470 C1)

C1 has not landed on main yet — middleware/packages/plugin-api/ still has no .d.ts snapshot, so there was nothing to update here. Its branch feat/470-c1-plugin-api-golden-snapshot is in flight. This PR adds five exports to the plugin-api surface (perCallerService, isPerCallerService, resolvePerCallerService, ServiceNotDeclaredError, plus the ServiceCaller / PerCallerFactory types) and widens two ServicesAccessor members, so whichever of the two merges second must regenerate the snapshot with its --update mode — deliberately, since the surface change is intended.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

---

Cross-family review (Forge)

Adversarial review against the code by GPT-5.4 (codex exec, reasoning_effort=high) — a deliberately non-Anthropic lineage, so the blind spots are not the ones the author and the Claude-family reviewers share. Every claim below was checked against source, not against the PR description. Three real defects were found and fixed in a6b259f2; the rest of the audit came back clean.

Findings

#	Severity	Finding	Status
1	P0 — boot-breaking	The legacy allowlist was incomplete by 26 pairs, 9 on @omadia/orchestrator itself. harness-orchestrator/src/plugin.ts:452 resolves llmProviderCatalog unconditionally near the top of activate(). As merged, the gate would throw ServiceNotDeclaredError there and the chat orchestrator would not activate. Also missing: nativeToolRegistry, processMemory, palaiaExcerpt, microsoft365.graph, nudgeStateStore, pluginCapabilities, installedPluginConfigReader, installedPluginToolsReadyReader; plus @omadia/orchestrator-extras → processMemory, @omadia/channel-teams ×5, @omadia/channel-telegram → channelResolver, and new rows for @omadia/integration-odoo, @omadia/channel-discord, @omadia/channel-slack, @omadia/channel-whatsapp.	Fixed
2	P0 — missing guard	Nothing derived the allowlist from the repo, so #1 was invisible to CI. Added test/pluginServiceGrantCoverage.test.ts.	Fixed
3	High	Only ctx.services.get passed the caller. ctx.memory, ctx.entities, ctx.mcp, ctx.subAgents, ctx.llm and ctx.events all called serviceRegistry.get(name) with no caller and therefore silently got KERNEL_SERVICE_CALLER — a perCallerService provider would have handed the plugin the kernel-scoped implementation. That is precisely the self-attribution failure §2.2 exists to prevent.	Fixed
4	Medium	perCallerService documented "one implementation per consuming plugin" but invoked the factory on every .get(). orchestrator.ts:544 documents a per-turn services.get, so a per-caller provider would have allocated per turn.	Fixed
5	Medium	The gate test fixture stored manifest: {}, but memoryDeclared reads permissions off the catalog entry's unparsed manifest field — ctx.memory was undefined no matter what the fixture declared, so the new attribution test asserted on nothing.	Fixed
6	High — open, not fixed here	provides: self-declaration is a grant. classifyServiceGrant returns self-provided purely from the manifest; a plugin declaring provides: ["graphPool@1"] is granted get('graphPool') without ever calling provide(), and unlike requires: it pays no activation cost (resolveEligiblePlugins never holds it back). The docblock's justification — "it holds the implementation anyway" — only holds if it actually registered it.	Reported
7	Medium — open, not fixed here	PluginCatalog.load() documents "on ID collision with the built-in catalog the uploaded version wins". An uploaded plugin declaring identity.id: "@omadia/orchestrator" therefore inherits that id's 19-name legacy allowlist (graphPool, tigrisStore, privacyRedact, turnReceiptStore, audienceGrants, …). Pre-existing collision behaviour, but the allowlist is what turns it into a service-grant escalation.	Reported
8	Low	The docblock claimed the audit found 27 undeclared pairs, but the array it introduced already contained 37 — it undercounted its own contents by 10. Now stated as the verified 63 across 19 plugin ids.	Fixed
9	Low	The gate is version-blind: parseCapabilityRef(raw).name discards the range, so requires: ["graphPool@^99"] grants graphPool whatever major is registered. Version is enforced at resolve time, not at get time. Worth one sentence in the docblock.	Reported

Clean — checked and found correct

• requires version-range tricks: no bypass. You still have to declare the name, and requires carries a real activation cost.
• Allowlist keying: keyed by the kernel-known agentId that createPluginContext receives, never a caller-supplied string. Closed per plugin and per name — verified by the existing tests, and the Object.freeze test pins it.
• Other ctx surfaces: no surface hands a plugin the raw ServiceRegistry. The kernel-mediated accessors have their own permission gates (finding chore(deps,ci): Bump docker/login-action from 3 to 4 #3 was about attribution, not about an ungated escalation).
• has() left ungated: correct — it hands over no capability.
• Core-internal serviceRegistry.get(): unaffected, correctly attributed to KERNEL_SERVICE_CALLER. No non-plugin caller can throw, because only ctx.services.get is gated.
• Boot ordering: the CapabilityResolver provider-before-consumer graph is untouched; the gate is a read-time check inside an already-activated context, not a new resolution edge.
• Ratchet +5: verified line by line. All five are in the new plugin-api/CHANGELOG.md, all prose or unrewordable literals (a spec path, a test filename, a future package name, the removal heading, the type list). git diff origin/main...HEAD -- middleware/packages shows zero new matches under any */src/. Nothing re-acquires a dep. middleware/packages 84 → 89 is honest.
• plugin-api 1.0.0 pins: harness-channel-api was the only stale ^0.1.0. Swept all 23 in-repo package.json files and all sibling repos under ~/sources/omadia-* — every other consumer already pins "*". No follow-up needed.

The coverage test earned its place immediately

It is not a rubber stamp: run against the allowlist as merged it fails, and on the first green run it surfaced three gaps that neither the original audit nor the reviewer's own manual sweep had found — @omadia/ui-orchestrator → agentToolInvoker, canvasOutputRegistry, deterministicActionRegistry. It resolves each services.get argument through the TypeScript checker rather than by grep, so const identifiers resolve and doc-comment mentions do not produce phantom call sites (that false-positive class is exactly what made the first audit's picture look complete).

Mutation-proved: dropping the llmProviderCatalog row makes it fail with

@omadia/orchestrator resolves 'llmProviderCatalog' at packages/harness-orchestrator/src/plugin.ts:453
without declaring it. Either add 'llmProviderCatalog@<major>' to manifest.yaml or add a dated row to
LEGACY_UNDECLARED_SERVICE_GRANTS_2026_08_20 for this legacy pair.

Counts, since the PR text and the code disagreed: the allowlist as merged held 37 pairs while its docblock said 27. This review added 26 more (9 on @omadia/orchestrator, 3 on @omadia/ui-orchestrator, 5 on @omadia/channel-teams, 1 each on @omadia/orchestrator-extras and @omadia/channel-telegram, and new rows for @omadia/integration-odoo, @omadia/channel-discord, @omadia/channel-slack, @omadia/channel-whatsapp), for a verified 63 across 19 plugin ids — which is what the docblock now says. Erratum: commit a6b259f2's message says "21 pairs"; the correct figure is 26, as recorded here and in the code.

C1 golden snapshot (#780) — landed mid-review, snapshot regenerated

#780 merged to main while this review was running (6f6956b9). origin/main was merged into this branch (clean, no conflicts — plugin-api/package.json took C1's new scripts alongside this PR's 1.0.0), and the snapshot was regenerated deliberately, per packages/plugin-api/README.md § What to do when the check fails: read the diff first, decide what it means, then accept it.

npm run api:check -w packages/plugin-api was red before the update, and the diff is exactly this PR's intended surface change and nothing else:

+export interface ServiceCaller { readonly agentId: string; readonly pluginId: string; }
+declare const PER_CALLER_FACTORY: unique symbol;
+export interface PerCallerFactory<T> { readonly [PER_CALLER_FACTORY]: (caller: ServiceCaller) => T; }
+export declare function perCallerService<T>(...): PerCallerFactory<T>;
+export declare function isPerCallerService<T = unknown>(...): value is PerCallerFactory<T>;
+export declare function resolvePerCallerService<T>(...): T;
+export declare class ServiceNotDeclaredError extends Error { ... }
-provide<T>(name: string, impl: T): () => void;
-replace<T>(name: string, impl: T): () => void;
+provide<T>(name: string, impl: T | PerCallerFactory<T>): () => void;
+replace<T>(name: string, impl: T | PerCallerFactory<T>): () => void;

Worth recording, because it changes how the version bump reads: there are no removals in this diff. The DevJob* types were already gone from plugin-api/src/ on main before either branch — all that survives is a tombstone comment, which the snapshot strips. By the README's own table this PR's surface change is therefore additive (MINOR-shaped). The 0.1.0 → 1.0.0 bump is still right, but it is the deliberate departure from 0.x — where breaking changes were always permitted — not a break contained in this diff. The PR's "contract break, taken once" framing is about the package leaving 0.x, and reading it as "this diff removes symbols" would be wrong.

npm run api:update -w packages/plugin-api   Wrote api-snapshot/plugin-api.d.ts.snap (2349 lines)
npm run api:check  -w packages/plugin-api   ✓ API snapshot up to date
npm test           -w packages/plugin-api   # tests 1  # pass 1  # fail 0

Verification

npm run build                    exit 0
npm run typecheck                exit 0
npm run typecheck:test           ✓ ratchet 406 known errors, no regressions (baseline 406)
npm run lint                     exit 0
node scripts/check-core-decoupling.mjs   Dev Platform references held at 3300.
npm run api:check -w packages/plugin-api ✓ API snapshot up to date
npm test          -w packages/plugin-api # tests 1    # pass 1    # fail 0

# gate + coverage + legacy-key
node --test test/pluginServiceGrantGate.test.ts \
            test/pluginServiceGrantCoverage.test.ts \
            test/manifestDevJobsLegacyKey.test.ts
  # tests 32   # pass 32   # fail 0

# blast radius — 27 files touching pluginContext / mcp / memory / subAgents / llm /
# serviceRegistry / capabilityResolver / manifest*
  # tests 233  # pass 233  # fail 0

(All gates re-run after merging origin/main at 6f6956b9; every number above is post-merge.)

Verdict: MERGE once findings #6 and #7 are carried into #470 as follow-up issues. They are pre-existing design questions this PR surfaces rather than regressions it introduces, and neither is a reason to hold the boot-breaking fix.