fix: activate against core main — pluginUi nav, optional_requires (0.3.0)

[Weegy]

What

Verification pass of this plugin against omadia core origin/main (9feb3ad3) — the first core carrying the whole C9–C11 contract surface (optional_requires, ctx.services.getOptional, pluginUi nav, core migrations at boot, ctx.sql.seedLedger with the read-only witness fence) at @omadia/plugin-api 1.5.0.

It found two real defects. Both stopped the plugin working against that core, and neither was a degradation — the first prevented activation outright.

The two fixes

1. The nav entry was unregisterable → the plugin did not activate

UiRouteCatalog.registerNav(@omadia/dev-platform/devPlatform): href segment
  '%40omadia%2Fdev-platform' has characters outside [A-Za-z0-9-._~]

This plugin's id is scoped, so the only URL that resolves is the percent-encoded one (raw splits into two path segments and 404s). That is exactly the spelling core's HREF_SEGMENT refuses — and #798 deliberately kept that rule strict rather than widening it the way the 2026-08-20 acceptance run's local patch assumed, because the shell decides "core destinations win" by comparing hrefs for string equality and percent-encoding breaks the comparison.

So the patch this repo was implicitly waiting on was never going to land. C9 closed it from the other side: the plugin declares pluginUi: true and the kernel renders pluginUiHref(id) itself. Byte-identical URL, no plugin ever hand-spells a percent-encoded href.

registerNav threw, the throw propagated out of activateInner, and activation failed. A recording double accepts any nav entry, which is why a green suite never noticed — so the shape is now asserted directly (pluginUi === true, no href).

2. Four survivable capabilities were declared as hard requirements

turnContext@1, githubAppJwt@1, usageTelemetry@1, conductorRoles@1 move from requires: to optional_requires: (C9 / core #795).

Core's capability resolver and install gate read requires: only, so listing a survivable capability there made this plugin uninstallable on stock core for four capabilities activate() is explicitly written to live without — each with a logged, documented degradation. graphPool@1 stays the single hard requirement.

Resolution moves to ctx.services.getOptional behind an optional-method guard, so a core predating plugin-api 1.4.0 still activates through the get() fallback. Both paths are driven by tests.

Checked and found already correct

• The nine C11 seedLedger witnesses. Each is already a single SELECT returning one boolean row, built from to_regclass, information_schema.columns or a pg_constraint join — no casts that throw on a missing relation, no multi-statement strings, no writes. They run clean under core's READ ONLY savepoint over the extended protocol.
• permissions.sql.ledger is plg_omadia_dev_platform_migrations, inside the plg_<sanitized-id>_ namespace.

Test-double fidelity

The activate() double was lenient on two points that mattered here:

• services.get / getOptional now throw for a capability declared in neither manifest list, matching the kernel since C2b.
• The declared set is parsed from manifest.yaml rather than restated in the test, so a forgotten manifest entry fails in this suite instead of against a real core.

test/manifest.test.ts asserts the exact requires: / optional_requires: sets rather than membership — this regression arrives one promoted line at a time.

Acceptance

scripts/acceptance-local.mjs, same artifact, two cores:

Core	PASS	FAIL	BLOCKED
origin/main @ 9feb3ad3	38	33	2
origin/main + C12 (feat/470-c13-residue @ 322afd19)	71	0	2

All 33 failures on main have one cause: the two dev-platform publicPaths exemptions that C12 (byte5ai/omadia#807) deletes, not yet merged. Core activates the plugin fully and then tears it down over the collision, so every downstream row reads 404 — route not mounted. With C12 present: 0 FAIL, no plugin change. Re-run against main once #807 lands; no plugin change is expected.

The two BLOCKED rows are unchanged from 2026-08-20 and honest: core exposes no tool-registry endpoint to probe chat-tool registration, and acceptance.md §3.15 has not decided the uninstall lifecycle for grant rows.

Full record: docs/ACCEPTANCE-RUN-2026-08-21.md.

Core gaps

Four of the six gaps from 2026-08-20 are closed on main (G1 SQL gate, G2 optionality, G3 boot migrations, G5 nav href). G6 is C12, merged on its branch. Two remain:

• G4 — a failed activation still reports status: "active". This run is the proof: §3.9 activation reported PASS above a plugin core had already deactivated.
• G7 (new) — core's pre-activate migration run pre-empts the C11 handoff. toolPluginRuntime.ts:374-394 calls ctx.sql.runMigrations() before activate() whenever the manifest declares permissions.sql.migrations, but seedLedger is documented to run inside activate() before runMigrations() (plugin-api/src/pluginContext.ts:2071-2087). Measured against a database carrying core's donor rows and all nine tables — expected 9 seeded / 0 applied, observed core applying 9 first and the handoff reporting 0 seeded, 9 already seeded. Not data loss (the files are idempotent), but the skippedNoWitness alarm — the one output C11 exists to produce — can never fire. Needs a core issue; a plugin cannot fix it from its side.

Verification

• npm ci && npm run typecheck && npm run build && npm test && npm run package -w packages/plugin — all clean against core main.
• 1,316 tests, 0 fail, 0 skipped (plugin 786 / runner-shim 76 / daemon + ui 454) with the Postgres suites actually running. Remaining skips are the two needing a built dev-runner image.
• Version bumped 0.2.0 → 0.3.0 in package.json and manifest.yaml together; the drift guard passes and the 0.3.0 ZIP is 525,131 bytes.

---

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