Factory docs, home
Page navigation

Pre-release documentation. Proposed designs are labelled in the page; acceptance evidence is maintained in the build review. Local paths appear as placeholders. Current state: Build review.

software-factory/provider-events-rpc adapts the existing private subscription host's three methods to decoded JSON-RPC requests. It starts no server, opens no endpoint, and sends no application event. Use the separately commissioned subscription host, with its actual caller-owned private store, authority, connector, clock, nonce and quiet maintenance.

The public declarations need ES2024 only. Construction captures the host's list/subscribe/unsubscribe methods and performs no host operation. A binding requires the actual public ProviderSubscriptionHost, paired with its commissioned Product. The adapter exposes only dispatch(authenticated, request). Its profile is inert data: protocol version 2026-07-28, capability fragment {events:{}}, webhook delivery, one Branch health event and no replay. A working service still needs independently qualified authenticated MCP transport and application delivery. Do not publish that capability on the strength of this packet.

Supply the real caller boundary

Before dispatch, the caller must reject malformed JSON, invalid UTF-8, duplicate object members, batches and raw requests above 20,480 bytes. Plain JSON.parse loses duplicate-member evidence and cannot establish this qualification. The adapter receives a decoded value, copies bounded plain JSON using descriptors, and never reads accessor values or invokes generic thenables. Proxies and dishonest trusted host implementations are outside qualification. Forbidden native Promises and their fulfilled data are observed within the same bounded descriptor traversal, including symbol data, without awaiting permission or accepting the data. Observation faults leave the original refusal and possible host effect unchanged.

Create AuthenticatedEventsContext from the actual authenticated route, outside params: exactly principal, session and productId, each a 1–63 character lowercase ASCII slug. The host receives principal/session with fixed role mcp-principal; request fields cannot grant authority. Null/malformed context or a mismatched bound Product yields Forbidden before a host call. EV2 rechecks current authority under its own real lock; constructor binding is not an authority snapshot.

Requests contain only jsonrpc '2.0', method, id and optional params. IDs are well-formed strings up to 128 UTF-8 bytes, including empty string, or safe integers excluding negative zero. Numeric 1 and string '1' stay distinct. Notifications return local not-handled/notification; other methods return not-handled/other-method; invalid envelopes return invalid-request. These local outcomes are for the caller's router, never wire payloads. The caller owns base protocol errors and response writing.

For one valid known request, dispatch invokes exactly one host method. Omitted list params remain omitted, null stays null, array order and omitted filter defaults stay unchanged. Unknown params, including _meta, progressToken, role and attempt, reach the existing exact host parser and refuse. Generic metadata/progress compatibility remains an explicit real-client gate; silently stripping fields is unsupported.

Project one response

List returns only {events:[...]}; subscribe returns only {id,refreshBefore,cursor:null,truncated:false}; unsubscribe returns {}. The frame is {jsonrpc:'2.0',id,result}. Subscription AttemptToken and private host state are never included. A list result must describe at most the existing webhook event, with both object schemas bound to the commissioned Product.

Host refusals use the existing wireError unchanged and are framed with error. Unexpected exceptions/rejections become fixed InternalError/unknown; malformed or oversized host results become fixed InternalError/corrupt. A post-effect error proves neither rollback nor permission to retry. Raw errors, keys and callback addresses never enter diagnostics or output. The caller must suppress generic body/ID logging; an ID itself may contain a secret and is echoed only to its original request.

Canonical request limit is 18,432 bytes, 20,480 nodes and 18 object/array levels. Params are at most 16,384 canonical bytes with EV2's fewer-than-16 nested-object depth rule. Raw host and projected results are each at most 8,192 canonical bytes; final serialised responses are at most 9,216 UTF-8 bytes. A maximally escaped 128-byte ID occupies 770 quoted JSON bytes. Limits refuse whole values; nothing is truncated. Binding errors are fixed ProviderEventsRpcError, code INVALID_BINDING.

Preserve correlation and uncertainty

Each subscribe call is a new bounded host renewal, even with the same RPC ID and params. The adapter has no response cache, retries, idempotency ledger, implicit renewal or recovery lookup. Private host owners may reconcile an already retained actual AttemptToken under current read authority outside MCP; dispatch intentionally drops that token. Without it, exact lost-reply recovery is not provided.

The caller may suppress dispatch before it starts. Afterwards, closing a response channel does not cancel the host, release an unknown slot or prove no contact. Continue observing the one started promise and deliver at most one reply to its original request object and session. Never forward a late reply to a later use of the same ID. There is no adapter timeout race: the qualified actual host owns bounded port waits. Arbitrary hanging replacement hosts are unqualified.

Expiry, original grant deadlines, key overlap and unknown reservations remain solely in EV2. Recreating this adapter resets none of them. Schedule current-authorised quiet maintenance outside these three methods. Application delivery, replay controls, model/tool jobs, live MCP/ChatGPT qualification, CI and final publication review remain open; Current verification is recorded in build review.

Bind an already commissioned host

import { createProviderEventsRpcAdapter, PROVIDER_EVENTS_RPC_PROFILE, PROVIDER_EVENTS_RPC_LIMITS } from 'software-factory/provider-events-rpc';

// Authentication and raw-byte parsing already happened in the caller's server.
export function bindEvents(host, productId) {
  const adapter = createProviderEventsRpcAdapter({ host, productId });
  return (authenticated, decodedRequest) => adapter.dispatch(authenticated, decodedRequest);
}

if (PROVIDER_EVENTS_RPC_PROFILE.replay !== false) throw Error('Unexpected replay profile');
if (PROVIDER_EVENTS_RPC_LIMITS.responseWireBytes !== 9216) throw Error('Unexpected response bound');
console.log(PROVIDER_EVENTS_RPC_PROFILE.methods.join(', '));

The exported helper remains passive until its returned dispatch function is called. Supply the real transport context and decoded request separately, inspect the local outcome, and let the original channel write its response at most once. The package supplies no default host or production parser, network listener, authentication service, scheduler or connector. The local two-store caller fixture proves only its bounded offline scope.

Source: docs/how-to/adopt-provider-events-rpc.md