[FEATURE] VNext Phase 8 — general Resource/Capability adapter ecosystem

[Joncallim]

Parent: #333
Execution mode: implementation
Depends on: #341
Absorbs generic connector portions of: #42 and future external-service integration work
Spec references: SPEC-0003 (Grants, Principal types — adapter is a distinct Principal), SPEC-0004 (Operation Catalog, effect classes, retry classes, side-effect lifecycle), SPEC-0005 (credential brokering, egress), SPEC-0008 (conformance)

Problem Statement

By Phase 7, Forge will have generic Missions, Workforces, execution and Triggers, but most real Resources/Capabilities will still be implemented through coding-specific helpers or one-off connectors. If each Workforce owns SDK code, credentials, retry rules and evidence format, package installation becomes an authority bypass and external side effects become impossible to reason about consistently.

Forge needs a reviewed adapter plane beneath Workforces.

Desired Outcome

Forge has one versioned Resource/Capability adapter contract for reads and consequential actions. Workforces request Capabilities; Forge binds Resources, brokers credentials, enforces Grants/budgets/egress, executes trusted adapter code and records idempotency/reconciliation/evidence. Multiple Workforces can reuse one adapter without owning its credentials or implementation.

User Story

As the Forge operator,
I want external services and data sources exposed through one governed adapter layer,
So that installing a Workforce never implicitly installs trusted credentialed code or invents a new side-effect model.

Requirements

A. Adapter definition

Each adapter/capability version declares protected metadata for at least:

• stable adapter id/version;
• Resource types it can bind;
• Capability/Operation ids and read/write/action risk class;
• input/output schemas and hard limits;
• supported mutation/concurrency semantics;
• credential mechanism/required scopes;
• network/egress destinations;
• rate/quota/readiness signals;
• timeout/cancellation behavior;
• idempotency-key support;
• read-after-write/reconciliation strategy;
• evidence/redaction/retention rules;
• supported host/runtime prerequisites.

Security-critical semantics live in reviewed adapter/Core definitions, not normal Workforce package data.

B. Resource binding

A Resource binding identifies a particular account/service/repository/mailbox/database/document corpus/etc. with classification, version/snapshot semantics and operator policy. A Capability Grant applies to explicit Resource scope/object selectors and expiry; connector availability alone grants nothing.

C. Credential broker

• Workforce packages store no credentials.
• Models/prompts receive no raw broad credential by default.
• Forge resolves an operator-configured credential to the narrow trusted adapter boundary only after Principal/Grant/Resource admission.
• Credential identity/scope/version metadata is auditable without copying secret values into ordinary evidence.
• Revocation/rotation is visible to readiness and blocks new Operations immediately.

D. Adapter execution boundary

Adapter executable code is distinct from declarative Workforce packages. In-process adapters are allowed only where reviewed risk/architecture permits; higher-risk adapters should use the #336 confined/process/RPC boundary. Package content cannot dynamically import arbitrary adapter code.

E. Generic side-effect semantics

All write/action adapters consume #336's Operation identity + idempotency/reconciliation lifecycle. An adapter that cannot prove safe retry after uncertain submission must return/hold an uncertain outcome and require reconciliation/operator policy.

F. Readiness/rate/quota

Normalize actionable adapter health without model calls:

• configured/credential missing;
• auth failure/permission denied;
• quota/rate limited;
• unreachable/degraded;
• Resource not found/revoked;
• ready;
• unknown/stale.

Retry/backoff honors adapter/provider policy and Mission budgets.

G. Network/data egress

Adapter network access is restricted to its reviewed destination policy. Model worker network access is not widened merely because an adapter needs a destination. Resource classification/provider egress from #335 remains a separate pre-context decision.

H. Evidence and observability

Every adapter Operation records safe structured identity, input fingerprint where appropriate, Resource scope, adapter version, credential identity metadata, outcome, external reference/idempotency/reconciliation state, timing and redaction/retention status. Raw response bodies/secrets are not default audit logs.

I. Initial migration/proof families

Do not build every connector. Migrate/prove a representative set:

1. repository/filesystem/Git/GitHub Operations from Software Engineering;
2. web/document read adapters from Deep Research;
3. one existing MCP/ACP integration represented through the generic boundary where semantically applicable;
4. one authenticated external service fixture/adapter with an idempotent write (mock/test service acceptable for conformance).

After the contract is proven, add connectors only in response to a Workforce requirement. Email/calendar/Notion/database/infrastructure families are candidates, not mandatory ceremony.

J. GitHub issue/backlog compatibility

If Forge exposes GitHub Issue create/update/read for Software Engineering/backlog workflows, implement it as typed GitHub adapter Operations with idempotency/conflict evidence. Do not recreate #42's separate work_items orchestration truth; Mission/Execution remains Forge runtime truth and GitHub remains implementation/backlog record where configured.

Implementation Sequence

1. Adapter/capability schema + registry — protected definitions and versioning.
2. Resource binding service — scope/classification/version + Grant selectors.
3. Credential broker abstraction — secret injection, rotation/revocation and metadata evidence.
4. Adapter conformance harness — read/write fixtures, timeout/cancel, secret sentinel, egress, idempotency, uncertain submission.
5. Migrate repository/Git/GitHub adapters — prove no behavior/security regression from Phase 3.
6. Migrate web/document adapters — prove read-only Research flow remains intact.
7. MCP/ACP representation pass — reuse existing trust boundaries; do not force a semantic mismatch just for uniform naming.
8. Authenticated write fixture adapter — idempotent submit + reconciliation under injected network faults.
9. Operator configuration/readiness APIs — Resource, credential identity, grants, health, recovery.
10. Documentation/conformance contract — exact checklist for every future adapter.

Primary Code Seams To Inspect First

• [FEATURE][ARCH] VNext Phase 0 — generic runtime contracts and compatibility seam #334 Resource/Capability/Grant contracts
• [FEATURE] VNext Phase 2 — secure generic execution envelope and side-effect recovery #336 Operation/confinement/side-effect journal
• [FEATURE] VNext Phase 1 — deterministic budget, routing, and context economics #335 egress/readiness/budget broker
• [FEATURE] VNext Phase 3 — complete Software Engineering as the first generic Workforce #337 Git/GitHub Operations
• [FEATURE] VNext Phase 5 — Deep Research Workforce and non-repository resource proof #339 web/document Resources
• current provider/MCP/ACP credential and readiness patterns as references
• app settings/crypto only through safe credential abstractions

Orthogonal Checkpoints

1. Capability authority: package declaration, missing Grant, Resource substitution, scope widening, read-vs-write confusion.
2. Secrets: sentinel credentials in prompts/logs/artifacts/errors/crash output, rotation/revocation races.
3. Network: unauthorized host/LAN/redirect destination, DNS/URL normalization where relevant.
4. Side effects: duplicate/replay, ambiguous transport, idempotency-key collision, reconciliation failure.
5. Rate/quota/recovery: 401/403/404/409/429/5xx/timeouts, bounded backoff and Mission budget.
6. Migration: Software Engineering/Research behavior and evidence remain green behind the adapter interface.
7. Package isolation: hostile Workforce content cannot load code/credentials or redefine adapter risk.

Acceptance Criteria

• Two Workforces can use the same adapter without owning its credentials or implementation.
• Capability Grants scope Operations to explicit Resources/object sets/expiry and distinguish reads from writes.
• Package installation cannot obtain a credential or execute adapter code merely by declaring a capability.
• Protected adapter/Operation security semantics cannot be weakened by editable package/config metadata.
• Readiness exposes actionable auth/quota/rate/resource/transport states without LLM probing.
• Duplicate/replayed supported writes are idempotent or enter reconciliation rather than silently duplicating.
• Adapter logs/evidence redact credentials/sensitive payload according to policy.
• Adapter egress is narrower than model-worker network authority and cannot widen it implicitly.
• Revoking a Grant/credential prevents new Operations without uninstalling the Workforce.
• Repository/Git/GitHub and web/document Phase-3/5 release gates remain green after migration.
• One authenticated write fixture passes fault-injection/idempotency/reconciliation conformance.
• GitHub issue integration, if included, does not create a second Forge orchestration database.

Out of Scope

• Public app/plugin marketplace.
• Arbitrary executable connector code bundled inside Workforce packages.
• Implementing every candidate connector family in this phase.
• Broad automatic credential acquisition.
• Model ensembles.

Implementation Scope

Very Large - generic adapter/credential/conformance layer plus representative migrations, expected as 7-10 small PRs.

Technical Notes

Do not force all existing MCP/ACP concepts into one abstraction if doing so would weaken their proven security model. The adapter plane should provide common admission/evidence semantics while allowing specialized protected implementations behind it.

[github-actions]

FORGE issue validation

This Feature issue now matches the required FORGE template structure.
The validator applied ready-for-agent and removed needs-clarification if it was present.

[Joncallim]

Hostile adapter-plane addendum — no hidden SDK authority, audience-bound credentials, and Core-owned retry/effect semantics

A fresh adapter/security pass found several places where an apparently clean Resource/Capability abstraction can still be bypassed by SDK defaults, mutable endpoint configuration, credential confusion or adapter-internal retry behavior. Treat these as mandatory Phase-8 constraints.

1. Split trusted adapter definition from Resource/operator configuration

Security-critical adapter semantics are protected reviewed Core/adapter definition state:

• adapter id/version/content digest/provenance;
• Operation IDs/versions;
• maximum supported Resource types/selectors;
• maximum Capability/effect/risk/retry classes;
• allowed network destination classes/origins;
• credential types/audiences and maximum scopes;
• timeout/cancellation/reconciliation rules;
• input/output/evidence schemas and bounds.

Resource/operator configuration may select/narrow within those ceilings (account id, exact approved endpoint, object scopes, narrower timeout, specific credential binding), but cannot widen them.

Examples that must fail:

• changing a read adapter config to declare write Capability;
• custom base URL outside definition's allowed destination policy;
• config turning reconcile_before_retry into replay_safe;
• package/operator JSON raising risk/concurrency/credential scope beyond adapter definition;
• model output adding an Operation or network destination.

Use a protected registry/writer path. Ordinary Workforce/package data cannot register or mutate trusted adapter definitions.

2. Pin adapter behavior while retaining current-security revocation

Every Operation records exact adapter definition version/digest/runtime identity. Running behavior may be pinned for reproducibility, but current security policy can disable/revoke a vulnerable adapter version immediately for new consequential actions.

• pinned Mission/Execution does not grant a right to keep using a globally revoked adapter binary/version;
• revocation makes outstanding admission tokens invalid at the next consequential boundary;
• upgrading adapter implementation does not rewrite old evidence;
• re-routing an Operation to a new adapter version is new admission/Operation attempt as permitted by the Operation contract, not transparent substitution under the old receipt.

3. Credential binding is (secret reference, adapter, audience, Resource/tenant scope, generation)

A secret's existence is not generic authority.

Before injection, bind/verify:

• exact credential reference/generation;
• exact adapter/version allowed to receive it;
• exact external service/audience/endpoint identity;
• tenant/account/Resource binding;
• declared/known scope ceiling;
• expiry/revocation state;
• acting adapter Principal/Operation admission.

A custom OpenAI-compatible/GitHub-like endpoint cannot receive another service's credential just because the protocol shape matches. One Resource's token cannot be reused for another tenant/account without a separately approved binding.

Credentials are injected after destination + Operation admission into the trusted adapter boundary only. Models/packages receive opaque Resource/credential-state metadata at most.

If provider/service-side scopes change without a local credential-generation change, treat locally stored scope metadata as declared evidence, not proof. Permission-denied/introspection evidence may narrow current readiness/authority; never infer broader scope from successful unrelated calls.

4. Hidden SDK retries must not bypass Operation retry/idempotency semantics

Many client SDKs automatically retry 429/5xx/network errors. For consequential writes this can violate SPEC-0004 by submitting twice behind Forge's back.

Adapter contract therefore controls SDK retry behavior explicitly:

• disable internal automatic retry for external mutation Operations unless each retry is provably covered by the same external idempotency key and the Operation's declared retry class permits it;
• Core/Operation engine owns retry/reconciliation decisions and records each external submission attempt/evidence;
• at_most_once / reconcile_before_retry must never be silently replayed by an SDK;
• reads may use bounded internal transport retries only if declared in adapter semantics and observable enough for timeout/rate budgets; they still cannot bypass destination/credential scopes;
• fallback between endpoints/accounts is a new authorization/resource decision, not an SDK convenience.

Conformance should include a fake SDK whose default policy retries twice and prove Forge disables/contains it.

5. Core generates idempotency identity; model/package/adapter response cannot choose it

For Operations requiring idempotency:

• stable business Operation identity/domain comes from Core;
• trusted adapter deterministically maps it into the external service's accepted key format;
• package/model/user payload cannot supply/override a key that collides with another logical effect;
• adapter records external idempotency key/reference only as evidence;
• key truncation/normalization must preserve collision resistance/domain separation and be tested against service limits.

If the service does not support sufficient idempotency semantics, the adapter remains reconcile_before_retry/at_most_once/human as appropriate rather than claiming safety.

6. Adapter output is untrusted external evidence, even when adapter code is trusted

The trusted adapter mediates bytes from an untrusted/possibly compromised external service.

Core validates:

• output schema/version/size;
• Resource/account identity in responses where relevant;
• external reference formats;
• confirmation policy;
• absence of authority-bearing fields that could widen Grants/policy/budget;
• typed failure classification.

An adapter response saying success, admin=true, retryable=true, or a different Resource id is data; it only has the semantics the reviewed Operation/adapter schema grants it.

Malicious response text/JSON cannot influence routing/Grant/tool policy outside typed fields.

7. Confirmation/reconciliation belongs to the Operation contract, not generic HTTP status

A 2xx is not universally confirmed business success; a 4xx is not universally safe failure.

Each Operation version pins its confirmation strategy from SPEC-0004. Adapter implements that exact strategy:

• synchronous schema-valid response;
• read-after-write;
• idempotency lookup;
• polling async job;
• external audit/event identity.

For eventual-consistency services, reconciliation policy declares bounded propagation/backoff semantics. A temporary 404 after accepted creation must not automatically become reconciled_failure if the service contract says visibility is delayed.

Likewise, “object exists” is only success if it matches the exact intended Operation identity/content; an unrelated pre-existing object is not reconciliation success.

8. Resource identity is external stable identity + tenant/account scope, not display name

For every adapter family define canonical Resource/object identity rules.

• renames/display-name changes do not silently create/adopt another Resource;
• object selectors are normalized/validated against the Grant scope;
• server-returned object IDs are checked against expected tenant/account/parent Resource;
• pagination cursors/continuation tokens are untrusted opaque data and cannot change Resource scope/destination;
• a model cannot substitute a friendly name/path for a different object with broader access.

Where an external service lacks stable IDs, document identity uncertainty/version semantics and use conservative reconciliation rather than pretending names are stable keys.

9. Pagination/bulk APIs need hard aggregate bounds

Read-only adapters can still cause unbounded cost/data/context/storage.

Declare and enforce:

• max pages/requests;
• max items;
• max bytes before/after decoding;
• max wall time;
• per-request + aggregate rate/budget;
• stable ordering/snapshot semantics where available;
• behavior when collection mutates mid-pagination.

No while nextCursor loop without a hard cap. Duplicate/cyclic cursor responses terminate safely. Partial retrieval is marked partial; it cannot be presented as a complete Resource snapshot.

10. Shared rate/quota state is scoped to the actual service limit domain

Two Workforces sharing the same adapter/credential/account may consume one provider quota. An in-memory per-Mission limiter is insufficient.

Normalize a versioned rate/quota key such as adapter/service + tenant/account + credential/resource limit domain according to the external contract. Central admission/backoff coordinates concurrent Operations across Missions where needed.

• Retry-After/reset metadata is untrusted provider evidence validated/bounded before affecting timers;
• absurd future reset values do not create integer/timer overflow or infinite hidden hold;
• current quota state may be unknown/stale, never forged to available;
• rate limiter cannot widen Mission budget/authority; it only narrows timing/admission.

Use DB/durable state where restart correctness or shared quota enforcement requires it; purely advisory latency telemetry may remain in memory.

11. Adapter readiness, Resource readiness and last Operation result are distinct

Avoid another “health means everything” trap.

Examples:

• adapter process/library available but Resource credential missing -> Resource/auth state not ready;
• credential valid but target object not found -> Resource state, not adapter outage;
• one Operation input rejected -> does not make adapter globally unhealthy;
• service 429 may affect shared service/account readiness;
• model/business verification failure after successful adapter call does not poison adapter readiness.

Expose one normalized effective admission projection, but retain typed causal dimensions so policy can distinguish configuration/auth/resource/rate/transport failure.

12. In-process adapter use is an explicit trust decision, not the default convenience path

For each adapter version declare execution class:

• pure/in-process reviewed library path where compromise impact is demonstrably bounded;
• confined adapter process/RPC for credentialed/networked or higher-risk integrations as appropriate.

In-process adapter dependencies become part of Forge's trusted computing/supply-chain base and require the same dependency review/pinning policy. Do not let arbitrary connector packages become in-process because they are easier to call.

For confined RPC:

• closed versioned protocol;
• bounded messages/time;
• authenticated local endpoint/process identity where needed;
• Core supplies only admitted credentials/Resource info;
• adapter cannot open arbitrary host files/sockets beyond confinement;
• crash/partial response maps to typed adapter/Operation state.

13. Inbound event/webhook capability remains #341 Trigger territory

An adapter may expose source-specific authentication/parsing helpers, but it must not create a separate webhook scheduler/event truth.

Inbound events route through #341 Trigger occurrence/auth/dedupe/causality. #342 provides the trusted external-service protocol/credential/resource implementation behind that seam where needed.

Do not let each adapter own an independent background listener/retry database that can wake Missions directly.

14. Migration must compare semantics without doubling consequential effects

When moving Phase-3/5 readers/writers behind the generic adapter interface:

• reads can shadow-compare from one captured source response/evidence where possible rather than issuing unnecessary duplicate external fetches that alter rate/cost/state;
• writes must never execute old + new adapters against the real external system just to compare outputs;
• use fixture/replay/fake service, dry-run normalization, or single canonical external submission with old/new projection comparison;
• declare one authoritative writer during every migration step;
• compare exact input normalization, Resource identity, Operation/idempotency, output/failure reason, evidence/redaction and retry semantics—not only happy-path returned data;
• migrated Phase-3/5 release fixtures must pass with the adapter plane while old independent writer paths are fenced.

15. Credential/readiness evidence failures cannot mask business Operation state

If secret-broker/readiness/audit helper fails:

• before external submission -> Operation blocks/denies with typed cause, no credential leak;
• after submission may have happened -> preserve submission_uncertain/reconciliation semantics; do not downgrade to “adapter error, safe to retry”;
• original external causal result is preserved over secondary diagnostic failures;
• credential broker never logs the resolved secret on error.

16. Future adapter conformance manifest is mandatory, not optional documentation

Create a versioned adapter conformance contract every future adapter must satisfy, mapping at least C1/C3/C4/C5/C6/C8 plus SPEC-0004 failure injection for mutation families.

Hostile generic fixtures include:

• package tries to redefine adapter risk/endpoint/Capability -> ignored/denied;
• wrong-tenant credential/resource substitution;
• custom endpoint requests another service's credential;
• SDK hidden auto-retry on write -> one external submission/idempotent evidence only;
• model-supplied idempotency key collision -> impossible;
• malicious external response tries to widen scope;
• pagination repeats cursor/never ends -> bounded partial result;
• shared rate limit hit by two Missions -> centralized bounded admission;
• credential rotates/revokes between admission and submission -> exact admission token invalid;
• eventual-consistency reconcile sees temporary absence -> follows Operation policy, no blind duplicate;
• old+new writer migration test proves one real external write only;
• adapter process crashes after possible submission -> submission uncertainty preserved;
• Resource rename/object-id confusion -> no accidental adoption;
• inbound webhook helper cannot bypass [FEATURE] VNext Phase 7 — Trigger/Event runtime with dedupe, causality, and zero-token idle #341 occurrence substrate.

The strengthened invariant is:

Adapters are trusted protocol executors with narrower authority than Core. SDK defaults, endpoint config, credentials, external responses and packages cannot invent retry, identity, network or side-effect semantics outside the reviewed Operation contract.

[Joncallim]

Architecture reconciliation — governed messaging adapters and protocol edge cases

Reviewed 1 October 2026 against this issue and the existing adapter security addendum. The user's current product direction explicitly includes Telegram/WhatsApp interaction alongside a browser workbench. This is a design hand-off, not account setup, connector installation or a claim that either channel is connected.

Preserve the common plane

Keep protected adapter definitions, audience-bound credentials, Core-owned retry/idempotency, bounded pagination, current revocation and #341-owned inbound events. Package installation grants no channel access. Messaging is a concrete consumer of this plane; it must not create another Mission/approval database or let a chat transcript become authority.

Messaging contract

• Distinguish talking to Forge through a channel from giving Forge access to wider conversations/accounts. The first does not authorize the second.
• Pair an authenticated Forge Principal with exact provider account/bot + sender identity + conversation/thread scope through an explicit trusted setup flow. Display names, forwarded messages, quoted text and phone-like strings are not identity proof.
• Inbound authenticated event → [FEATURE] VNext Phase 7 — Trigger/Event runtime with dedupe, causality, and zero-token idle #341 occurrence/dedupe → bounded command/intent → normal Mission/Gate admission. Provider webhook authentication establishes event provenance, not permission for every sender.
• Outbound messages are typed [FEATURE] VNext Phase 8 — general Resource/Capability adapter ecosystem #342 Operations with approved destination/audience, disclosure projection, logical message intent, provider receipt and delivery state. Accepted, delivered, read and action-approved are different facts.
• Any actionable button/reply binds an opaque, expiring, single-use decision reference to exact Principal, conversation, subject/action and revision. A stale button, replay, group participant or forwarded prompt cannot approve a new action. Higher-risk decisions may require the browser's authenticated confirmation path.
• Text/attachments remain untrusted inputs. Apply byte/item/content limits, safe media retrieval and the existing credential/egress boundaries. No automatic attachment execution or prompt-authority inheritance.

Telegram first slice

A narrow bot-based, explicitly paired conversation is a suitable first messaging fixture/pilot. Telegram documents mutually exclusive webhook and getUpdates delivery, update identities, webhook secret headers and retries. Route accepted updates through a durable inbox before acknowledging them; dedupe by bot identity plus update ID, not sender display name. Do not assume update IDs are eternally contiguous or monotonically increasing across long idle periods. Also avoid webhook-response shortcut sends for consequential notifications: Telegram states that route does not expose the send result. Use the explicit outbound Operation path instead. Official Bot API

Bot API URLs contain the bot token, so HTTP/access/error telemetry must redact that URL segment, including redirect/error traces. Never place a bot token in model context or ordinary evidence.

WhatsApp supported route and setup gate

Use an official supported Business Platform adapter, not an assumed personal WhatsApp session bridge. Meta's official collection identifies the Cloud API as business messaging and lists a business portfolio, WhatsApp Business Account and business phone number as prerequisites. Meta Cloud API collection

Before enabling real sends, explicitly validate account eligibility, current messaging/template rules, consent, permitted destinations and applicable charges for the chosen setup. Do not hard-code an old pricing model or promise unrestricted free-form personal messaging. Template availability/approval is a typed readiness condition; Meta's template endpoint has its own approved-template contract. Official template example

The legacy Meta developer overview/webhook pages did not load in this research pass; current request-signature and message-policy details must be checked against the supported current docs during implementation. This limitation does not justify an unofficial transport or bypass.

Conformance additions

• Correct webhook authentication, wrong/unpaired sender: no command authority.
• Duplicate/reordered update: one logical intent; edits and deleted messages follow explicit semantics.
• Old approval button after subject/policy change: rejected rather than applied to current work.
• Group/forwarded message copies an approval reference: cannot impersonate the bound approver.
• Send times out after possible acceptance: follow that provider's actual reconciliation/retry contract; do not claim a universal idempotent send.
• Delivery/read webhook arrives before local acknowledgement: correlate immutable provider/Operation IDs without inventing user approval.
• Token-bearing request URL or malicious media redirect enters diagnostics: no secret leakage or destination widening.
• Channel disconnect/revoke blocks new inbound authority and outbound sends while retaining appropriately redacted history.

Delivery sequence

First prove the generic authenticated read/write fixture and existing migrations, then add Telegram's narrow paired command/status/decision flow and a WhatsApp capability/readiness skeleton against the same contracts. Real account provisioning, credential grants, charges and publication remain separate operator actions. Browser and channel views share canonical Core state; neither is a second runtime. No implementation, permissions, accounts or issue state changed in this review.