Service endpoint callers

Caller policyCopy Anchor Link

caller-grant takes an owner granter with an interactive row who holds the approved instance, and a grantee is a current exact owner, actor and lifecycle UID. A managed grantee also needs its actual same-owner parent chain, with each current ancestor holding active covering grants for the same service approval. The operation records those immutable grant ids and lifecycle UIDs in parentRefs and rechecks them before append. An admin scope never substitutes for endpoint caller rights. Every capability must name that instance with instanceOnly: true, carry no journal access and no any or ledger target, and sit within the approval's caller ceiling. The answer is granted with the grant as stored. Ordinary user-auth agent connects now derive their endpoint rows from this policy through core's native grant builder, including reserved Describe for each authorized exact instance. An unpinned invokeService or invokeCommand whose class publish the broker refuses is re-sent once on the rail of the instance that answered its describe, so a granted caller reaches the service without naming the instance. The callout rechecks grantee lifecycle, named ancestor grants, current name, assignment, root, activation, approval and ceiling, then checks the policy evidence again after signing and native-key recording. The original connection expiry is at most 60 seconds from issuance, and capped by root and approval expiry. These are fresh leader reads, not a linearized revoke fence. Existing issued connections keep their original expiry, and caller revocation remains deny-new, not terminal absence proof. One instance indexes at most 256 grants over its life, including attempts refused after indexing, and a full index answers resource-exhausted; a new instance is the remedy. caller-revoke admits the grant's source owner, its grantee owner and an operator. It answers pending with denyNew: "landed" and notBefore, in epoch seconds, 71 s after the broker time of the grant's cutoff marker. It never answers revoked, and the result parser refuses that arm. caller-policy-read gives an owner its own grantees, and another owner's grantee only filtered to a service it holds; caller-policy-list needs a service selector.

Broker payload limitsCopy Anchor Link

Caller grants need max_payload >= 2098176 (SERVICE_CALLER_PAYLOAD_FLOOR: 2 MiB plus 1 KiB), max_control_line >= 4096, and an auth stream with max_msg_size: -1. Broker generation accepts an explicit serverConfig(broker, accounts, { ...options, maxPayload: SERVICE_CALLER_PAYLOAD_FLOOR }); omission leaves the native 1 MiB default unchanged. No startup path raises limits automatically. The stock root sets it with cotal up --max-payload <bytes>, which records the value in .cotal/broker-policy.json; a renderer outside up reads it back with readBrokerPolicy(root)?.maxPayload so every render of that broker carries the same limit.

Payload observationCopy Anchor Link

For a standalone broker only, pass serviceEndpoints.callerPayload.observerCreds to startAuthService (or the corresponding authority-plane option). The callback returns fresh host-private credentials from the broker owner's mintServiceCallerPayloadObserverCreds({ pub: broker.sys.pub, signingSeed: broker.sys.signingSeed }). Keep that registered SYS signer with the broker owner, never in the data account, a sandbox or a participant client. The helper returns an in-memory, at-most-60-second VARZ-only credential. The stock root does this itself: cotal up retains the system-account signing seed in the root's secret store at space creation and at --rotate-sys, and the auth service started with --service-endpoints composes callerPayload from it when the record names the trust record's system account and the seed derives it; a root with no retained seed opens the engine and door without caller issuance and logs why. The callback only supplies credentials, owns no authority resource, and may finish after its 10-second observation deadline has refused the operation. It is not a cancellation callback.

Startup authenticates native VARZ, matches the observer and data connection's broker incarnation, checks config/system-account evidence and live stream limits, then writes an exact-key assertion bound to that broker, configuration and genuine plane claim. Configured clusters, gateways and leaf links refuse, regardless of connected peer count. This is not multi-broker proof. A default 1 MiB broker fails startup with the required byte limit and creates no assertion.

Process restartCopy Anchor Link

Positive caller issuance repeats the observation and checks the exact assertion revision, complete plane hold and effective authority again before native JWT release. Withdrawal or claim loss refuse new issuance. A broker RELOAD, which keeps the same incarnation serving and moves its config_digest, does not: when the fresh observation proves the same incarnation, the same auth store, and every limit above again, the record is re-asserted under the held claim by CAS on the exact prior row and issuance continues. A reload that breaks any of those, a max_payload below the floor included, still refuses, and a withdrawn record is never overwritten. A RESTART is a new incarnation and refuses. Reopening needs an explicit bootstrap to reassert for the new claim; a prior-plane broker-bound assertion cannot authorize another append. Legacy assertion syntax still parses for existing trusted storage fixtures but alone never enables production caller issuance. Shutdown drains in-flight observations and closes their owned connections before releasing the claim. Reads and revokes do not need a positive assertion. A revoke whose policy row would not fit holds payload-precondition without writing it, and a failed live-limit check withdraws the assertion.

Unknown outcomesCopy Anchor Link

Give each caller operation a fresh random requestId, record it with the exact body before you send it, and replay that body after a lost reply, a 503 or a held answer. Never switch to a new requestId while an earlier answer is unknown. A settled refused or expired ends the attempt, and a grant replayed after its 10-minute window adopts a grant that landed and otherwise answers expired.

Caller issuance is generic, not tied to Linear: the same provider-independent contract discovery and invoke path works for ordinary and managed user-auth callers. Controlled policy append currently requires the application's approved service-host instance. Native control endpoints retain their existing ledger/scope and typed authority contracts, not fabricated application approvals. Scoped Describe is not available, and complete terminal retirement and restore remain unsupported. A host revoke refuses new activation, renewal, readiness and connections, but a connection already open keeps its original expiry of at most 60 s. Approval runs service bootstrap and revoke runs cancellation, while complete observer evidence and writer exclusion remain unavailable. Do not seed service reservations in an existing space, adopt old service-shaped rows, or use ordinary retirement to make them terminal. A signing-key or raw-store holder can bypass helper guards, so schema rejection alone does not make mixed-version writers safe. Restore must quarantine service work until a separately supported reconciliation protocol is available.