Factory docs, home
Page navigation

Independent adoption draft: Discovery and Service adoption exposes the existing Access, discovery and catalogue contracts as one Service-access family. Caller-owned trees, names-only captures and optional catalogue injection work without Portfolio or a Git checkout. Count/CoverageStatus now come from shared reporting types; runtime, authority exclusions and recorded protocols are unchanged. Current acceptance and review evidence: build review.

A names-only map of the third-party Services a Product uses and where their credentials live, and the answer to "can this need be met now, by which route?". It holds a frozen catalogue of Service kinds, scans a Product's tracked tree and captured listings for names, folds them into a Service map inside one journal command per discovery, keeps exclusive store bindings, owner declarations, confirmations and route pins, and answers readiness. It is built never to read, return or record a secret value; the canary, adversarial and regression suites establish that for the positions and forms they plant, which is not proof for every construct a repository could hold (Trust scope).

Cloudflare increment C1 (integrated after independent review; no acceptance receipt): cloudflare/1 joins the catalogue with the tracked-path signature source, Wrangler's deny rules, vault-only and unwanted slots, token scopes as data, one 1Password item per token and the unscoped-credential finding. Names only: no reader, runbook or live call. It changes behaviour, so the receipts below are stale for it until a new acceptance receipt records it; the eleven earlier kinds' digests are unchanged, but the detection digest changed, so every map recorded before it reads as catalogue-drift until rediscovery.

Cloudflare increment C2 (integrated 2 October 2026 after independent review; no acceptance receipt): wrangler.toml, wrangler.json and wrangler.jsonc join the allow list (role wrangler-config, never under node_modules; cloudflare.config.ts stays unopened). A bounded parser of the module's own (TOML 1.0 as a Wrangler file needs it; JSON with comments and trailing commas; no dependency) keeps only [env.<name>] instances, each instance's Worker name, route and custom-domain hostnames (screened lower-case LDH names of at most 253 bytes, scheme, leading wildcard and path dropped), binding names by section (a closed list, vars keys among them; it also covers secrets_store_secrets, pipelines, ratelimits, unsafe.bindings and a service-worker Worker's wasm_modules, text_blobs and data_blobs keys; a section outside it is ignored, not read) and whether account_id and pages_build_output_dir are written. Values, ids, resource names, comments and account_id are dropped. It changes behaviour, so the receipts below are stale for it too; the catalogue and its digests are unchanged.

Vault presence, increment 4 (integrated 2 October 2026 after independent review; no acceptance receipt): src/service-vault-reader.ts runs exactly op item list --vault <id> --format json and refuses every other argument list, each value-printing form included, before a process starts. It keeps each item's id, version and last edit, the vault id and only a conventional title, counting the others. recordVaultListing keeps the latest listing of each bound vault, and a declared vault item is then present (its field unverified), absent from a complete non-empty listing only, or unknown. It was tested against a fake op only: no real op has run, nothing composes the reader, and it is not packaged. It changes behaviour, so the receipts below are stale for it until a new acceptance receipt records it.

Operational-signal read credentials, packet SA5-OPS (2 October 2026; implemented, independent review owed; no acceptance receipt): sentry/2 and posthog/2 supersede sentry/1 and posthog/1, and datadog/1 joins, so the O37.2 adapters' read credentials have catalogue slots before any adapter reads. Each read credential is a vault-only slot (no name, no CI destination) in a 1Password item of its own, with its token permissions as data: Sentry's event-read-token (an internal integration's organisation-owned token: event:read and project:read required, org:read optional), PostHog's query-read-key (a user's personal API key: query:read required, project:read and error_tracking:read optional) and Datadog's read-api-key (no scopes exist, so none is stated) with read-app-key (a service account's application key: metrics_read and timeseries_query required, logs_read_data and events_read optional), each at most 90 days. Each kind gains read-signals (brokered, then owner; consumers operations and signal-intake only) and one brokered verify-<slot> purpose per read slot. A recipe is refused for a purpose naming more than one slot, so Datadog's read-signals stays the owner's until a reviewed revision acquires both keys. Runbook templates may now be written for one slot, and their steps name the system (vendor, onepassword, github), interface and one reason per skipped rung in spec r8's interface order; a kind lists its vendor's rungs, and its digest covers every system's rungs its steps use. The three vendors list the official API, the classic CLI and the console, with no agentic CLI, since none is established to make read credentials. Sentry's Next.js configuration files are tracked paths. .sentryclirc, sentry.properties, datadog.yaml (outside .github/workflows/) and datadog-ci.json are denied. The ten untouched kinds and cloudflare/1 keep their digests; the detection digest changed, so maps recorded before read as catalogue-drift, and a need naming posthog/1 or sentry/1 is refused KIND. SUPERSEDED_KIND_SPECS keeps the first revisions so a recorded map can be read under the catalogue that recorded it. No credential exists: the owner's steps are in Register signal read credentials. It changes behaviour, so the receipts below are stale for it.

Status: Accepted local implementation: scanner and organisation-presence repairs passed independent Astra review and combined checks. Required CI remains pending. No live repository, listing, sign-in or vault is read. Scanner evidence, organisation evidence, current build review. Human page: guide.

  • Source: src/service-kinds.ts (catalogue, grammars, shape checks), src/service-discovery.ts (path rules, scanners, listing and sign-in parsers, the fold), src/service-access.ts (aggregates, commands, views, readiness, the vault fold), src/service-vault-reader.ts (the one op item list, increment 4)
  • Tests: test/service-kinds.test.ts (4), test/service-cloudflare.test.ts (15: cloudflare/1, the C1 rules and the C2 allow list, including the pre-packaging journal fixture under both catalogues and a discovery recorded before the Wrangler scanner, which replays unchanged), test/service-ops-kinds.test.ts (7: sentry/2, posthog/2 and datadog/1, their step interfaces and load refusals, the new deny rules, presence through a fake op, and the pre-packaging journal under the current catalogue), test/service-wrangler.test.ts (15: the C2 Wrangler reader, names only, with canaries in every value), test/service-discovery.test.ts (23), test/service-access.test.ts (23, one with six, six and four claimant processes racing), test/service-access-canaries.test.ts (2, with a negative control), test/service-access-boundaries.test.ts (4, import and identifier boundaries read from the compiler's syntax tree, the vault reader's included), test/service-vault-reader.test.ts (18, increment 4 against a fake op, with canary scans and negative controls), test/service-access-adversarial.test.ts (14, written by the increment's adversary; never weakened), test/service-access-regressions.test.ts (23, one per class the adversarial tests and the implementation reviews opened; the seven for Astra round 2 each fail on 2101d4d)
  • Helpers: test/helpers/service-access.ts (a TreeSource that logs every read, gh-shaped captures, a synthetic Tally-shaped checkout), test/helpers/service-access-child.ts (one binding claimant per process), test/helpers/fake-op.mjs (answers only op item list from a recording and prints a canary secret for every value-printing form, so a bypass would leak where the tests scan)

Intelligence: none — Discovery, references, readiness and runbooks are exact rules over names and dates; a model would add an injection path near secrets, not accuracy.

What it hides

  • The catalogue. A ServiceKind is frozen data for one pure interpreter: id (vercel/1), family (ci-provider, saas, store-console, signing), pinned console origins, signatures (decisive or weak, by source: workflow file, tracked path (a listed file's base name, matched exactly and never opened), action, command words, npm, SwiftPM, Gradle dependency, plugin or block, consumed name, any name), name prefixes, slots (class, exact names after a public prefix is stripped, destinations, desired scope, and for a token its scope as data: owner, the permissions an owner may grant on a zone, account, organisation or project, named as the vendor names them (Zone Read, event:read, metrics_read), with those every token holds, and the longest expiry), a 1Password item template (one item for the kind, or with items: "per-token" one API Credential per secret slot, <kind> <instance> <slot>, beside a Secure Note for the rest), purposes (slots, routes, consumers, mutating, signatures), desired settings, runbook templates (the four general ones, then any written for one slot, whose steps may name their system, interface and one reason per skipped rung in spec r8's interface order, with the vendor's rungs listed on the kind) and brokered recipes (none yet; refused for a purpose naming more than one slot). defineKind(family, spec) merges the family's defaults (item category, the five default settings, the four runbook templates), checks every rule, deep-freezes the kind and digests it (sha256: of the canonical kind without its digest). The catalogue's detection digest covers every kind's signatures, name prefixes, slot ids, classes and names, the public prefixes and the class rules. A slot's scope vault (vault-only: no destination outside the Product's vault, declared at a vault item) or unwanted (an unscoped credential no store should hold: no destination, no purpose, no item field) is exactly a slot with no destination, and only a secret may have either; a delegated-CI purpose names no vault-only slot. The first eleven kinds: github-actions/1, vercel/1, convex/1, clerk/1, posthog/1 (now posthog/2), sentry/1 (now sentry/2), honeycomb/1, app-store-connect/1, apple-signing/1, google-play/1, android-signing/1; then cloudflare/1 (increment C1 of the archived Cloudflare adapter design): Wrangler and cloudflare.config.ts files, Cloudflare npm packages, actions, Wrangler deploy commands and a consumed CLOUDFLARE_API_TOKEN are decisive, while _routes.json, cf (also Cloud Foundry's CLI) and the CF_PAGES prefix are weak; its only name prefix is CLOUDFLARE_. Its slots are deploy-token (the one token a CI store may hold), the vault-only dns-token and read-token, the identifiers account-id, zone-id and pages-project (GitHub variables), and the unwanted global-key (the Global API Key); every token is account-owned with Zone Read on the Product's zone and at most 90 days. Every brokered purpose takes one token slot, and no recipe exists. Then (packet SA5-OPS) sentry/2, posthog/2 and datadog/1, each with vault-only read slots for the operational-signal adapters, read-signals and verify-<slot> purposes and slot runbooks; the superseded first revisions are kept in SUPERSEDED_KIND_SPECS, never in CATALOGUE.
  • Path rules, deny first. isDeniedPath refuses .env* except *.example and *.sample, *.p8 *.p12 *.pfx *.pem *.key *.keystore *.jks *.mobileprovision *.gpg *.asc *.tfvars, id_rsa id_dsa id_ecdsa id_ed25519 .htpasswd GoogleService-Info.plist google-services.json .npmrc .netrc, *-firebase-adminsdk-*.json, Wrangler's local secrets (.dev.vars and .dev.vars.* except *.example) and anything under a .wrangler/ directory, the Sentry and Datadog files that hold keys (.sentryclirc, sentry.properties, datadog-ci.json, and datadog.yaml outside .github/workflows/), and data files (JSON, YAML, text, plist, XML, properties, INI, TOML, config, CSV, .env or no extension) named with secret, credential or service-account: each is a secret-bearing-file finding, never opened. allowedRole opens only .github/workflows/*.yml|yaml, env templates, package.json (never under node_modules), *.gradle.kts, gradle/libs.versions.toml, Package.resolved and (C2) wrangler.toml, wrangler.json and wrangler.jsonc (never under node_modules).
  • The credential screen. credentialShaped(text) is true for a run of 20 or more letters and digits holding both (a random token, key or digest) and for a few vendor shapes whose random part is shorter or split (AWS key ids, Google API keys and OAuth tokens, GitLab and Slack tokens, Stripe webhook secrets), in either case. Every path, name and identifier from outside the Factory passes it before it may be recorded: RelPath refuses a path shaped like a credential, and the grammars for names, job ids, runner labels, instances, slugs, logins, attribution, held items and npm, SwiftPM, Gradle and action identities are screened (fits, matching; the rule text ends "not shaped like a credential"). Commit ids, digests, reference ids and 1Password ids are Factory-derived or vendor ids and are not screened. It is a screen, never a secret scanner: a name-shaped secret cannot be told from a name, and a long identifier with digits and no separator (LegacyApiV2IntegrationTests) is screened out too, a safe failure that leaves its source partial.
  • Tree scanning. scanTree(source, {capturedAt, catalogue?}) lists the TreeSource, applies the rules and reads only allow-listed blobs within maxFileBytes. A path outside RelPath (printable ASCII, relative, at most 200 bytes, no empty, . or .. segment, not shaped like a credential) is never opened or recorded; it is counted, and it makes the scan partial (credential-shaped-text when only the screen refused it, else path-outside-grammar), so a denied path shaped like a credential is not a secret-bearing-file finding either; the parser refuses a tree that counts one without either reason. Links, submodules, files over a per-file bound (the listed size before reading; lines, jobs, steps or sites once read: file-over-limit, the file dropped whole, never a prefix), size mismatches, unreadable and non-UTF-8 files, and denied paths the allow list would have opened also make it partial. A listed blob or link outside node_modules and the deny list whose base name is a tracked-path signature is recorded in tracked (path and signature), never opened; more than maxTracked such matches refuse with LIMIT. A Wrangler configuration (C2) is read to its end or to the first thing its parser cannot follow: a line holding a control character, an unterminated string or comment, a multi-line string holding an escape TOML 1.0 does not define, a Unicode escape that names no scalar value or a lone carriage return (its text is checked and never kept), a key set twice (neither value kept), a table defined twice, an inline table extended or spread over lines, a bare TOML value that is none of TOML 1.0's scalars (a bare word, or a malformed number, date or time; its text is checked and dropped), text after a value or after JSON's root, or a root that is no object (malformed-file). What came before the stop is kept where it belongs and nothing after it is read. A name outside its grammar, or an environment called default, is dropped (credential-shaped-text when only the screen refuses it, else malformed-file). A line over maxLineLength, nesting deeper than maxConfigDepth (32; TOML table headers, arrays of tables, dotted keys and nested values counted together, as JSON's levels are) or more than maxSitesPerFile names refuses with LIMIT, which drops the file whole (file-over-limit), never keeping a prefix; the totals (maxOpenedFiles, maxTotalBytes) refuse the scan with LIMIT as for every allow-listed file.
  • Scanners. A bounded line grammar for workflow YAML reads block mappings and sequences, one-line flow sequences of scalars, block scalars (literal | keeps its lines, folded > joins them), comments, and a plain scalar continued on deeper lines or written on the line after its key (folded into one value, as YAML folds it). It never reads a line as structure while inside a scalar or collection another line opened: a quoted scalar runs to its closing quote and a flow collection to its closing bracket, whatever the indentation between (as libyaml reads them), and both are folded into one value. Every scalar is decoded as YAML reads it before any name is read from it: a single-quoted scalar's doubled quotes, a double-quoted scalar's escapes (YAML 1.2's set; any other escape leaves the node unread and the file partial) and a quoted scalar's line folding, from its lines as written; a double-quoted key's escapes; each item of a one-line flow sequence; and a block scalar's lines read together, as YAML joins them, so an expression or literal that runs across them is read whole. A plain scalar's comment starts at its first #, whatever quotes stand before it (YAML reads no quote inside a plain scalar), and ends the scalar. Anchors and tags are stripped and their node read; aliases, merge keys, complex keys, keys the walker cannot decode, flow mappings, nested flow collections, a quoted or flow value continued on later lines, text after a closing quote or bracket, a deeper line under a node the walker closed, and an expression opened on one line of a block scalar and closed on another are unsupported-yaml, and no name is read from a node the walker hides, cannot decode or cannot place. A line over the length bound (line-over-limit), a tab in the indentation, a second document or content on a document marker stops the walker: nothing after that line is read. It keeps jobs with their lines, runner labels and kind (hosted by label pattern, else self-hosted; a dynamic label, or one outside the label grammar or screened, leaves the runner unknown, never hosted), the environment as an instance (lower-cased; dynamic, outside [a-z0-9._-]{1,64} or screened is unknown, and so is one not read whole: an environment key seen without its name, a job that is an alias or holds a merge key, or a job the walker stopped inside before its environment's name), every secrets.NAME and vars.NAME use with its line, job and exposure (env, with, run, secrets, if, other), forwards (--env, --build-env, -e, -b on a catalogue command such as vercel), secrets passed as command arguments through an environment variable, checkout tokens persisted (a secret token without persist-credentials: false) and matched signatures. A job whose id cannot be recorded is dropped with every line under it, never attributed to another job. An expression ${{ … }} ends at the first }} outside its string literals, which are single-quoted as GitHub's expression syntax has them, and its references are read only outside them (secrets['NAME'] reads its index literal's text): a literal's text is a value, never a reference; an expression that never closes, or holds a double quote outside a literal (which that syntax refuses), is not read and makes the file partial. Scripts are read as bash reads them: ;, &, |, (, ), a newline and a command substitution ($( ) or backticks, inside double quotes too) start a command only outside quotes; single-quoted text, an ANSI-C quote ($'…', where a backslash escapes), double-quoted text outside a substitution, a parameter expansion (${…}, its quotes and substitutions followed, a single quote being a character inside double quotes), an arithmetic expansion or command ($[…], $((…)), ((…)), its quotes and substitutions followed), a comment and a here-document body start none; bash reads (( as two parentheses when the ) matching its second is not followed by another, and so does the reader, by reading that text again, stopping (unsupported-yaml) rather than read past one extra pass over the script; a backslash-newline joins two lines; a forward is read from the provider command's own argument words (--env NAME=… or --env=NAME=…), so a flag inside another argument's quotes is that argument's text, and a forward's source is read from the script's own expression as GitHub evaluates it before the shell runs, never from the word the shell unquotes. GITHUB_TOKEN is the automatic token, never a stored secret. toJSON(secrets), a computed index, secrets: inherit and a name over 128 characters make the file partial (dynamic-reference); a workflow_call trigger in any form (a key, a list item, a flow collection, an escaped or folded scalar) makes it a reusable workflow (reusable-workflow), whose secrets are its caller's, and so do triggers the walker could not read whole (a node under on it hid or could not decode, such as an alias or a flow mapping, or a stop inside on or before it was read); so does any job id, label, environment, call, name or identity the screen drops (credential-shaped-text), or a forwarded name outside the name grammar. Env templates keep key names with lines, reading values as dotenv does: a quoted value (double, single or backtick) runs to its closing quote across lines, and none of its lines is ever a key; where dotenv and a shell would read where a pair or line ends differently (a quote, parameter or arithmetic expansion, command substitution, subshell or ANSI-C quote left open, or a here-document, in an unquoted value, a quoted one or a line that is no pair; text after a value's closing quote; an escaped quote in single quotes or backticks; a backtick inside a quote inside a backtick substitution; a trailing backslash), where a shell runs any command on the line other than an assignment, an export of names written literally or one of dotenv's inert forms (a dotted or dashed key, or KEY: value, holding no parenthesis), since it may open case patterns, [[ operands or a group over later lines, define a function or an alias, or source a file, or where any word names bash's alias table or command paths (BASH_ALIASES, BASH_CMDS; an assignment, or an expansion such as ${…:=…} that assigns), where a value never ends, and at a line past the length bound, the key on that line stands and the scan ends there, partial. Manifests keep dependency identities (never URLs or versions) and signature hits: package.json and Package.resolved are parsed as JSON; a Gradle Kotlin script and a version catalogue (TOML) are lexed first, so a dependency, plugin or block is read only from code (a declaring call, or a catalogue key, whose value is a one-line string without a template), never from inside another string (a raw or multi-line one included) or a comment, and a source that ends inside a string or comment is partial. A catalogue's table headers are read as TOML reads them (bare, quoted and dotted keys, with a basic string's escapes, so ["libraries"] is the libraries table and ["versions"] ends it), and a line of an array another line opened is never a header or a key; a header written any other way, an inline table left open, an array closed more than it was opened, or a line past the length bound ends the catalogue's scan there, partial, so no line is ever read under a table it does not belong to. A literal where a credential belongs (any non-placeholder under a secret or signing-material name; a credential-like one under an unclassified name) is a literal-in-template finding by line; the value is dropped as it is read.
  • Listings and the sign-in. readListing(capture) takes what gh secret list or gh variable list --json name,updatedAt printed, the exit code, stderr already reduced by classifyStderr to a byte count and 401, 403 or null, and the endpoint's total_count. A failed command is unauthenticated (401) or unavailable (forbidden or failed); output that does not parse, an entry with any field but name and updatedAt, a name outside the grammar (a credential-shaped one included) or repeated in any case, or a bad date makes the listing corrupt and keeps none of it; complete needs the count to equal total_count, else partial. readSignIn(capture) keeps the active github.com account's login, state, scopes and token source from gh auth status --json hosts; a key named like a token (any key containing token but tokenSource) at any depth, any key besides the seven that gh 2.89.0 prints, or any of the seven holding another type than gh prints refuses the whole sign-in (a gh release that adds a key is refused until a reviewed revision lists it: a safe failure). No OAuth scopes, as a fine-grained or App token shows, keeps the sign-in with the reason scopes-unknown: whether it can write is unknown, never assumed read-only (writeCapable returns null).
  • The input. parseDiscoveryInput re-validates what the scanners and readers wrote, never trusting a status: a file scan must be of a path the deny list does not refuse and carry the scanner the allow list gives it (the deny rules as they stood before Wrangler's were added, so a discovery recorded before them still replays; the fold refuses a scan that opened a path the current rules deny, so no new map is derived from it); a Wrangler scan's names must fit their grammars, its records name only default or an instance it lists, sorted and distinct as the scanner writes them, with no hit and no field beyond the scanner's; a denied path's allowListed flag must say whether the allow list the scan was taken under would have opened it, one list for the whole scan: before C2 (no Wrangler scanner, so a denied .wrangler/tmp/wrangler.toml recorded false) or the current one (always the current one once a file was scanned as a Wrangler configuration), so a discovery recorded before C2 still replays, while the fold refuses with INVALID inside the decision, recording nothing, any denied flag the current allow list disagrees with (the current list would leave that scan partial); a tree's reasons must include every file's, and denied-allow-listed where a denied path would have been opened; tracked paths must be sorted, distinct and outside the deny list and node_modules, and a scan recorded before they existed keeps its shape without them, so its discovery still replays (the fold refuses such a scan under a catalogue that has tracked-path signatures, and, since the parser checks only a signature's shape, refuses with INVALID inside the decision, recording nothing, any tracked path whose signature is not one of the catalogue's tracked-path signatures or whose base name is not that signature's, and (C2) any tracked path the allow list now opens that has no file scan while the tree gives no reason for leaving it unopened, as a scan recorded before C2 does; an exact repeat of such a discovery still replays); a listing's status must agree with its total, entry count and reasons, and a sign-in's with its reasons and account, exactly as readListing and readSignIn write them. The fold re-checks the same where it matters, since it is exported: a listing is conclusive only when complete, non-empty, its total its entry count and without a reason, and a sign-in gives a reference only for an account the reader kept.
  • The fold. discoverServices(productId, input, catalogue?) is pure. Names resolve to a location per job: a job in an environment reads that environment's secret before the repository's, so only a conclusive listing of the environment settles which applies (the environment's when it lists the name, else the repository's); without one, the use is located at the environment, whose presence stays unknown, and also at the repository when its listing holds the name, so neither is taken for the one that applies and a stored repository name is never called unreferenced. A name is present when a listing holds it; absent only when every relevant listing is conclusive and every use of it shows where it resolves, observed as of the oldest of those listings; and unknown otherwise, with the listings' reasons and the uses': a use in a job whose environment is unknown (instance-unknown), in a reusable workflow (reusable-workflow) or in a file not scanned whole (tree-partial) never makes a name absent. Kinds are detected by one decisive or two distinct weak signatures; a tracked path is evidence by path, without a line. Only a decisive command claims its command's forwarded variables, so a weak one (cf) never makes a provider variable of its kind. Names classify by slot after stripping a public prefix, else by one kind's name prefix (no slot) and the longest class rule (a public prefix makes an unmatched name public configuration, unless the rule says secret or signing material: such a name is a secret exposed to a client bundle, never one to move into a plain variable); two kinds claiming a name leave it unclassified with an ambiguous-kind finding. Each CI job records whether it names an environment (environment) and whether its workflow is reusable (called). Forwards become provider-variable references (presence provider-unreadable), template keys env-template-key references (local-not-a-source), and the ambient sign-in a tool-sign-in reference, with write-capable-reader only when a scope can write. A discovered reference whose slot is unwanted raises unscoped-credential, at its first consumer when it has one; the view adds the same finding, without a path, for every merged reference a declaration or confirmation puts in such a slot, so a declared or confirmed key is flagged too, and never twice. A Service's evidence is capped for presentation at maxEvidencePerService sites, and evidenceTotal reports every distinct site found.
  • Vault presence (increment 4). opCliReader({executable, env, timeoutMs?, clock?}) runs one argument list, which checkOpArgv refuses (INVALID) before any process starts unless it is exactly item list --vault <26-character id> --format json. The reader copies the caller's list before anything else runs, the clock included, and checks and spawns only that copy, so a list changed after the call changes nothing that reaches op. The copy owes nothing to the caller's prototypes: its length and each own element are read once as data, through intrinsics captured when the module loads, and an accessor, a hole or a non-text element refuses the list (INVALID). The copy is a frozen array with no prototype, so no species subclass, replaced slice or iterator of the caller's changes it. This is not a sandbox against other code in the same process: Node's launch copies the arguments into fresh arrays and publishes them on the public child_process.spawn diagnostics channel, so a clock callback that installs a prototype setter, or a channel subscriber, can still change what op receives. The clock, channel subscribers and the rest of the process are trusted code. The environment is copied the same way into a frozen object with no prototype, so a name inherited from Object.prototype never reaches op, and an accessor or a symbol in it is refused (TypeError) at construction. A realm whose intrinsics were replaced before the module loaded, or that replaces Node's own launch, is beyond any in-process check. The process receives exactly that list after its executable: any other option, an argument prefix included, is refused (TypeError) at construction, and a test substitutes the executable only. The refusal covers op read, op item get (whose JSON holds values), op inject, op run, op document get, --reveal, --otp, --fields, signin --raw, --debug and every other form. The child gets only PATH, HOME, OP_CONFIG_DIR and OP_ACCOUNT from opEnvironment, plus fixed NO_COLOR and LC_ALL. A service-account, Connect or session token, or a debug switch, is refused at construction. Standard input is closed, standard output is bounded at maxCapturedBytes (over it, LIMIT) and a timer bounds the run (30 s by default). The process leads its own process group; at the time or byte bound the whole group is killed only while op is unreaped, since until then its id cannot name another process's group. Once op has exited and been reaped nothing is signalled, so a descendant left in its group is not killed (the Claude producer's stated limit). The pipes are closed from the reader's side after closeGraceMs (1 s) at most, so a descendant holding them, one left in the group after op exited, or one that left the group, never keeps the run from ending. Standard error becomes a byte count and a fixed class (signed-out, locked, no-vault or none). readVaultListing(capture, catalogue?) refuses output over maxOutputBytes UTF-8 bytes (LIMIT) before any parsing, whichever reader took the capture, and keeps each item's id, version and updated_at (as an ISO instant, its calendar components checked first, so 30 February or hour 24 is never rolled over into another instant). It keeps the title only when it is conventional under the catalogue (vaultTitleOf: <kind> <instance>, or <kind> <instance> <slot> for one token's item, the instance screened) and counts the others. Every other key (additional_information, urls, tags, the vault's name, last_edited_by and so on) is dropped unrecorded. A non-zero exit keeps no item: signed out or locked is unauthenticated, no such vault is listing-forbidden, and anything else, a timeout included, is listing-failed. Output that is not UTF-8 JSON (empty or blank output included), an item outside the shape, an updated_at that is no calendar instant or a repeated id is corrupt (listing-malformed), and the whole listing then keeps no item. An item holding a value-bearing key (fields, sections, files, value, password, notesPlain, details) is corrupt (listing-unexpected-field). An item of another vault refuses the listing whole (OUT_OF_BINDING), as more than maxListingEntries items do (LIMIT). Only [] is complete with listing-empty. listBoundVault(reader, bindings, vaultId) refuses a vault outside the Product's bindings (OUT_OF_BINDING) before op starts, and refuses a capture whose vault is not the one asked for (OUT_OF_BINDING), whichever reader took it. Both read each field of a capture once, into a copy, so the vault checked is the vault read. In the fold, a declared onepassword-ref reads its vault's latest listing (vaultPresence). With no listing it is unknown (vault-not-listed). Under an inconclusive or empty listing it is unknown with that listing's reason. A listed item is present with its version, last edit and field unverified, since fields are never listed. An item a complete, non-empty listing lacks is absent as of that listing. An absent item is no brokered destination: an unpinned need falls through, and a pin to it is pin-target-gone, but only while the listing it rests on is within staleAfterMs.vault at asOf. An absence from an older listing is unknown: stale-listing, never a fall-through or a gone pin, and the map shows such a pin's route unknown (as it does for an absence captured after asOf), never target-gone. A brokered route stays unknown: field-unverified for a present item (with stale-listing beside it from an older listing), or the item's own reason, until an acquisition (increment 7) observes the field.
  • Records. Aggregates service-access:product:<productId> (sf-service-access/1: discoveries, route commands, the latest map, declared references, confirmations, route pins, and from the first vault listing an optional vaults key holding each bound vault's latest listing, absent from every state recorded before it so that state reads exactly as written) and service-access:bindings (sf-service-access-bindings/1). The Product aggregate holds one Service map, so a Product binds at most one repository (maxRepositoriesPerProduct, 1) until maps are kept per repository; a second is refused (LIMIT) rather than silently replacing the first's map. Command IDs service-access:<productId>: followed by bind:github-<repositoryId> or bind:vault-<vaultId>, discover:<n>, declare:<referenceId>, confirm:<referenceId>, route:<n> or vault:<vaultId>-<capturedAt in epoch ms>; discover and route must be the next number (STALE otherwise), and a vault listing must be captured after the one recorded for that vault (STALE otherwise), so presence never moves back in time. Events service-access.bound, .discovered, .declared, .confirmed, .route-pinned, .vault-listed, one per command. Payloads are names only: the validated discovery input or vault scan, never file text, raw output or a map.

Public interface

src/service-kinds.ts imports createHash from node:crypto and canonicalJson from ./canonical-json.ts. src/service-discovery.ts adds ./service-kinds.ts and shared Count and CoverageStatus types from ./reporting-contract.ts. src/service-access.ts imports the other two, the journal class and its conflict, decision and input errors from ./journal.ts, and canonicalJson. src/service-vault-reader.ts imports the three, spawn from node:child_process, Buffer from node:buffer and kill alone from node:process (to kill its process's group); nothing in src/ imports it.

  • Constants: CATALOGUE_PROTOCOL = "sf-service-catalogue/1", TREE_SCAN_FORMAT = "sf-tree-scan/1", SERVICE_MAP_FORMAT = "sf-service-map/1", ACCESS_PROTOCOL = "sf-service-access/1", BINDINGS_PROTOCOL = "sf-service-access-bindings/1", BINDINGS_AGGREGATE. ACCESS_LIMITS (frozen): maxTreeEntries 100 000, maxOpenedFiles 400, maxFileBytes 262 144, maxTotalBytes 8 388 608, maxLineLength 4 096, maxLinesPerFile 20 000, maxJobsPerWorkflow 100, maxStepsPerJob 200, maxSitesPerFile 2 000, maxDenied 1 000, maxTracked 1 000, maxListings 64, maxListingEntries 1 000, maxCapturedBytes 1 048 576, maxReferences 2 000, maxConsumersPerReference 256, maxFindings 2 000, maxEvidencePerService 16, maxStateBytes 786 432, maxDeclared 256, maxConfirmed 512, maxPins 64, maxPinCommands 1 000, maxDiscoveries 100 000, maxBindings 1 000, maxBindingsPerProduct 16, maxRepositoriesPerProduct 1, defaultStaleAfterMs 86 400 000. KIND_LIMITS bounds a kind (24 signatures, 12 slots, 8 permissions per token). Vocabularies: FAMILIES, CLASSES, SLOT_SCOPES and VAULT_SCOPES (with isVaultScope), CONSUMERS (producer and delivery are REFUSED_CONSUMERS), ROUTE_ORDER (ci, gh, brokered, owner), DESIRED_SETTINGS, RUNBOOK_PURPOSES, PUBLIC_PREFIXES, CLASS_RULES, PARTIAL_REASONS (with credential-shaped-text), LISTING_REASONS, SIGN_IN_REASONS (with scopes-unknown), UNKNOWN_REASONS (with reusable-workflow), FINDINGS (the spec's fourteen and unscoped-credential), LOCATION_STORES.
  • Catalogue: KIND_SPECS, SUPERSEDED_KIND_SPECS (first revisions kept for reading recorded maps, each with supersededBy), defineKind(family, spec), defineCatalogue(kinds) (one revision per kind), KINDS, CATALOGUE, detectionRules, kindBase; the interface order INTERFACE_ORDER, LAST_RUNGS, SKIP_REASONS, STEP_SYSTEMS, ONEPASSWORD_RUNGS, GITHUB_RUNGS; the screen credentialShaped(text) and fits(value, grammar).
  • Discovery: isDeniedPath, allowedRole, scanTree, scanFile, isPlaceholder, classifyName, classifyStderr, readListing, readSignIn, writeCapable, parseDiscoveryInput, discoverServices, referenceIdOf (ref- and the first 24 hex of SHA-256 over canonical {productId, location}), locationName, parseLocation, parseServiceMap.
  • class ServiceAccess(journal, {catalogue?}):
    • bindLocation({commandId, productId, expectedVersion, binding, commissionedBy}), recordDiscovery({…, input}), declareReference({…, location, kind, instance, slot, declaredBy}), confirmReference({…, referenceId, kind, slot, confirmedBy}) and declareRoute({…, kind, instance, purpose, target, declaredBy}) return AccessResult {productId, aggregateId, commandId, version, replayed, event} or throw AccessError. expectedVersion is the bindings aggregate's version for bindLocation and the Product's otherwise; next(productId) gives both (NextCommands {version, bindingsVersion, discoverCommandId, routeCommandId}), with the next numbered ids, so a caller need not derive them from read. A concurrent command can still take a number first: the loser is STALE and reads again.
    • bindings(productId), read(productId), next(productId), map(productId, {asOf, staleAfterMs?}) (a ServiceMapView: the map with declarations, confirmations and pins merged, per-source staleness at asOf against the same Fresh bounds as readiness, drift against the catalogue in force, the map's findings in their order with an ambiguous-kind finding dropped once its reference is classified and an unscoped-credential finding added for any merged reference in an unwanted slot that lacks one (the stored map is never rewritten), vault coverage from the bound vaults' latest listings (unavailable: vault-not-listed until one is recorded; one vault shows its listing; several show complete only when each is listed completely, else partial), fixed unavailable coverage for provider stores and local files, and the Product's own bindings; the view's shape is unchanged) vaultListings(productId, {asOf, staleAfterMs?}) (each bound vault's latest listing: status, reasons, capture, staleness against staleAfterMs.vault, item and unconventional-title counts) and readiness(productId, need, {asOf, staleAfterMs?}). recordVaultListing({commandId, productId, expectedVersion, scan}) records a vault listing (OUT_OF_BINDING for an unbound vault; the scan re-validated by parseVaultScan, its status agreeing with its items and reasons and no kept title shaped like a credential in any part; INVALID for a kept title that is not conventional under the catalogue in force, since free text comes only from the catalogue). All reads work on a read-only journal, and every read re-validates the stored state (about 1 ms per call at the Tally-shaped fixture's scale, measured on this host; nothing is cached).
    • Helpers: productAggregateId, pinKeyOf, bindCommandId, discoverCommandId, declareCommandId, confirmCommandId, routeCommandId, vaultCommandId, parseAccessState, parseVaultScan, vaultTitleOf, VAULT_STATUSES.
  • Vault reader (src/service-vault-reader.ts, not packaged): opListArgv(vaultId), checkOpArgv(argv), opEnvironment(source), OP_ENVIRONMENT_NAMES, opCliReader(options) (an OpReader with run(argv)), classifyOpStderr(bytes, total?), readVaultListing(capture, catalogue?), listBoundVault(reader, bindings, vaultId, catalogue?), VAULT_READER_LIMITS; types VaultCapture, OpReader, OpCliOptions, OpStderrClass.
  • AccessError {code, productId, currentVersion}, codes INVALID CORRUPT STALE CONFLICT LIMIT TAKEN EXISTS OUT_OF_BINDING NOT_FOUND CLASS ROUTE KIND; ShapeError (a TypeError) from the shape checks, <path> must <rule>.
  • Types: ServiceKind (tokenItems only for a per-token kind, interfaces only for a kind whose steps name one), Slot, TokenScope, TokenPermission, RunbookTemplate (slot for a slot's own), RunbookStep (system, interface, reasons together or not at all), Rung, Interface, SkipReason, StepSystem, Catalogue, TreeSource, TreeScan, TrackedPath, FileScan, ListingCapture, ListingScan, SignInCapture, SignInScan, DiscoveryInput, Location, Presence, CredentialReference, ServiceEntry (with evidenceTotal), ServiceMap, CiJob, Finding, CountSet, StoreBinding, Need, Fresh, Route, Readiness (ready carries actionable), RoutePin, ServiceMapView, NextCommands, VaultScan, VaultItem, VaultStatus, VaultListingView.

Invariants and guarantees

  1. No value, by construction and on the tested forms. No interface is built to return a secret value and no record to hold one: deny-listed paths are never opened, only allow-listed blobs within the size limit are read, scanners keep names, lines, labels, identities and signature ids, no line inside a workflow or env-template value (a quoted or flow value continued on later lines, a plain scalar's continuation, a block scalar, an env template's quoted value) is ever read as a key, job id or name, no text inside a quoted string, an expression's literal or a comment of a Gradle script or catalogue is read as a dependency, reference or forward, a listing or sign-in with any unexpected field is kept as a status only, every string that enters a record matches a grammar, and every path, name and identifier from outside the Factory passes the credential screen. Test-made canaries, token-like and name-shaped, in every value position reach no byte of the database, WAL or shared-memory file, no event, view, answer or error, in raw, base64, base64url, hex, percent or JSON form or either case; the token-like canary is also planted where paths and names are recorded (an allow-listed and a denied path segment, a workflow file name, a job id, a runner label, an environment, a secret reference, a forwarded name, a template key, npm, Gradle and SwiftPM identities and a listed name) and is recorded nowhere; name-shaped canaries in multi-line quoted values, Kotlin raw strings, templates and block comments, TOML multi-line and literal strings, expression literals, a quoted provider flag and a template line a shell carries on are recorded nowhere either, nor (Astra round 2) expression literals behind YAML quote doubling, double-quote escapes (\u0027, \x27, \U00000027), multi-line quoted scalars, flow-sequence items, block scalars, a forward's value or a double quote in an expression, text in a plain scalar's comment, nodes the walker cannot decode or place, template lines inside a parameter or arithmetic expansion, command substitution, subshell, ANSI-C quote, here-document, case pattern or [[ operand, or after a line that defines a function or an alias or names bash's alias table, catalogue lines under a quoted, dotted, escaped, array or over-long header, and script lines bash reads inside an expansion (arithmetic included), ANSI-C quote or here-document; a negative control shows the scan finds a canary a journal does hold, upper-cased as a name would be included (acceptance 2). For C2, canaries in Wrangler values, comments, account_id, ids, route paths, multi-line strings and malformed, over-long, oversized or over-deep Wrangler files reach no byte of the database, WAL or shared-memory file, no event, view or error, and a forged Wrangler scan carrying one is refused without echoing it (test/service-wrangler.test.ts). This is evidence for those positions, not a proof that no other construct could carry a value into a name.
  2. Absence only from a conclusive listing and a use that shows where it resolves. A listing that is unauthenticated, forbidden, failed, incomplete, without total_count, malformed or empty leaves presence unknown; only a complete, authenticated, non-empty listing, whose total is its entry count, gives absent, referenced-not-stored and missing, and a listing whose status contradicts its own total or reasons is refused (INVALID) before any command. A use in a job whose environment is unknown, in a reusable workflow or in a file not scanned whole never makes a name absent. A partial tree keeps tree-dependent Counts from being exact and suppresses stored-not-referenced (acceptance 3). A consequence, by design: a Product with no secrets yet stays unknown: listing-empty and never reaches missing or an exact Count until an owner statement (increment 3) can say the store is empty.
  3. Counts use the shared reporting contract. Only an exact Count shows 0: stored over the repository scope and every environment a job names, one named default included (Dependabot secrets serve Dependabot runs and are listed but not counted), referenced, storedUnreferenced (never a partial: it is an upper bound), referencedNotStored, and stored names by class, unclassified counted as secret. No Count is exact while a job's environment is unknown (instance-unknown) or a partial tree may hide jobs, and so environments (tree-partial: any tree reason but dynamic-reference, reusable-workflow or malformed-file, which leave every job read). On the Tally-shaped fixture: 44 stored, 31 referenced, 13 stored-unreferenced and 0 referenced-not-stored, all exact (acceptance 1).
  4. Exclusive bindings. One aggregate decides every claim: a slug (compared lower-cased), repository id or vault id another Product holds is TAKEN, the Product itself cannot bind its slug or vault again in another form (EXISTS), and a second repository for one Product is LIMIT (a stored one is CORRUPT). Six, six and four claimant processes racing on one slug in six cases, one repository id under six slugs and one vault id give exactly one winner each; losers re-read after STALE and are TAKEN. recordDiscovery needs its repository bound to the Product by slug and id; a declaration of a GitHub location or vault item outside the Product's bindings is OUT_OF_BINDING, whatever its reference id (acceptance 4).
  5. Isolation. Reference ids hash the Product with the location, so identical names in two Products never share an id; views and bindings return only the Product's own.
  6. Commands behave as the Product gate's. Input defects are INVALID before any journal work, except the checks that depend on the catalogue in force (a discovery's tree scanned under it, and each title a vault listing keeps being conventional under it), which run inside the decision (INVALID, recording nothing) so that an exact repeat still replays after the catalogue changes, a kind or token slot removed included; an exact repeat of any command replays (replayed: true: bind, discover, declare, confirm and route are each tested); the same id with other content is CONFLICT; a wrong version or sequence number is STALE; stored state is re-validated on every read and command (CORRUPT, never repaired, including a forged reference id, a finding naming no reference, a miscounted evidence total, listing or sign-in coverage that contradicts itself, or a second repository binding); the next state is bounded (LIMIT above 768 KiB or the journal's document limit), a discovery input over the journal's 1 MiB document limit is LIMIT before any journal work, the declaration, confirmation and pin bounds are LIMIT, and a scan or fold beyond ACCESS_LIMITS's totals refuses with LIMIT, never truncating, while a single file over a per-file bound leaves the scan partial. A supplied map is INVALID (acceptance 5).
  7. Errors quote nothing. Every message names a field by path and the rule it breaks (or a fixed reason), never an input's content; the product id in an error is present only when it passed its grammar.
  8. Drift is per kind. A map records its detection digest and the digest of every kind it uses. Readiness is unknown: catalogue-drift when the detection rules or the need's own kind changed; a change to another kind's runbook changes nothing for this need (acceptance 5).
  9. Readiness (acceptance 6), in order: need grammar (INVALID); an unknown kind or purpose is refused KIND or PURPOSE; producer, delivery or a consumer the purpose does not list is CONSUMER; no map is unknown: not-discovered; a map any of whose sources (tree, listings, sign-in, vault listings) was captured after asOf is unknown: captured-after-as-of, and drift and a tree older than its bound are unknown. Then routes in preference order (delegated CI, ambient sign-in, brokered, owner-executed): a delegated-CI destination is a job at exactly the need's instance that shows one of the purpose's signatures (preferred over a job that only consumes a slot) or consumes one of its slots; several are AMBIGUOUS unless a pin names one; a pin whose job is no longer a candidate is unknown: pin-target-gone; no candidate at the instance while a job's environment is unknown is unknown: instance-unknown. A job of a reusable workflow is unknown: reusable-workflow, since it reads its caller's secrets under names the caller maps. At the job, every slot must be consumed from the job's own CI stores (slot-not-consumed otherwise; a provider variable the job writes is a destination, not a source) by present references observed within the listings bound (stale-listing); any consumed reference of the slot whose presence is unknown, such as an environment that may override the repository, makes the answer unknown even beside a present one; for a job in an environment that environment's listing must be within the bound too; absent slots give missing only with a complete tree, and absence is as old as the oldest listing it rests on. The ambient sign-in route needs a present sign-in (sign-in-unavailable) observed within the listings bound (stale-sign-in). A brokered route counts only with a recipe (none exists in the catalogue; tests add one), and its destinations are vault item references (onepassword-ref) of the kind, instance and a purpose slot, since only a vault item is ever a brokered source: none falls through to the next route, several are AMBIGUOUS unless pinned, a pin whose item no longer fits is unknown: pin-target-gone, an absence resting on a vault listing older than staleAfterMs.vault is unknown: stale-listing (pinned or not), and one is unknown (field-unverified, or its presence's reasons such as vault-not-listed) until acquisition exists. The owner-executed route needs the kind among the map's Services and names its first console. No destination is unknown: no-route. Ready is presence, never validity, and carries actionable: false exactly for the owner-executed route, which only the owner can use; an actionable route still needs the grant its use requires (an Action grant for a CI run, a service grant for a brokered use).
  10. Classification is never lowered. confirmReference applies only to a reference whose kind is unclassified and refuses a slot whose class ranks below the reference's catalogue class (public configuration below identifier below secret and signing material); declareReference refuses (CLASS) a slot whose class ranks below the one a catalogue slot or name rule gives the location's name, and a vault-only slot at any location but a vault item; and the view never applies a declaration or confirmation that would lower a class, whenever it was recorded (before discovery, or before a catalogue revision): a later catalogue classification wins, and a declared location the map does not hold shows the higher of its slot's class and its name's. There is no per-Product override of a catalogue classification: declareReference refuses a location the map holds (EXISTS) and confirmReference a classified one (CLASS), so a wrong name rule or slot name (OTEL_EXPORTER_OTLP_ENDPOINT claimed by honeycomb/1, the generic KEY_ALIAS) is fixed only by a reviewed catalogue revision.
  11. Route pins match their need. declareRoute accepts only a job that is a current delegated-CI candidate for the kind, instance and purpose, or for a brokered route a vault item reference of that kind, instance and one of the purpose's slots (a GitHub secret of the right slot is refused); the pin survives rediscovery, and the view shows it current, target-gone, or unknown when a brokered target's only absence rests on a vault listing older than staleAfterMs.vault or captured after asOf (as readiness answers stale-listing or captured-after-as-of).
  12. Boundaries (acceptance 7). The three files import only each other in one direction (access → discovery → kinds), ./canonical-json.ts, ./journal.ts, node:crypto and the shared reporting types; they name no process, fetch, globalThis, loader, timer or performance, call no import(), use no import.meta, and read no Date.now or Math.random; nothing else in src/ imports them but the module's own vault reader (increment 4). The reader imports exactly the three, spawn from node:child_process, Buffer from node:buffer and the single binding kill from node:process (to signal its own process group), names no process, fetch, globalThis or loader, and uses two timers: the run's time bound and the pipe-close grace. Its default capture clock is new Date(), and nothing in src/ imports it. Probes in the compiler's view show each breach caught and comments and strings ignored.

Failure semantics

  • AccessError: INVALID for malformed input (a ShapeError becomes INVALID with its path and rule), before any journal work; rule failures throw their code and record nothing; VersionConflictError becomes STALE with the current version; CommandConflictError becomes CONFLICT ("re-read"); stored defects are CORRUPT; storage errors pass through.
  • scanTree and readListing refuse with AccessError LIMIT beyond their totals, and throw ShapeError for a malformed source listing or capture. scanFile alone refuses with LIMIT beyond a per-file bound, which scanTree turns into file-over-limit. Everything else about a file, listing or sign-in is its status and reasons.
  • readiness returns its four states and throws only INVALID, CORRUPT or a journal storage error.
  • The vault reader refuses a forbidden argument list with INVALID before any process starts, an unbound vault with OUT_OF_BINDING before op runs, output over its byte bound or more items than maxListingEntries with LIMIT, and an item of another vault with OUT_OF_BINDING; it refuses a token, session or debug variable, an option outside executable, env, timeoutMs and clock (an argument prefix included), a relative executable or an out-of-range timeout with TypeError at construction. Everything else about a run is its status and reasons. recordVaultListing refuses a kept title the catalogue does not hold with INVALID (inside the decision, so an exact repeat of a recorded listing still replays after the catalogue drops that kind or slot), an older capture of the same vault with STALE, records nothing on any refusal, and a stored listing that disagrees with itself is CORRUPT.

Trust scope

  • Established locally (macOS arm64, Node 26.8.1, real SQLite journals in temporary directories, test-made fixtures): the path rules and read log, the scanners and parsers, the fold and its Counts on the Tally-shaped fixture, exclusive bindings under racing processes, replay, CONFLICT, STALE, CORRUPT, the byte and count bounds, drift, readiness, the canary scan, and the adversary's fourteen attacks (multi-line values, hostile YAML, forged scans, unknown environments, reusable workflows, classification, quoted commands, nested token keys) with the regression suite that closes each class, and Astra round 2's three findings with the members of their classes found while closing them (quoting, escapes, folding, comments and block scalars in workflow YAML; forwards read as GitHub evaluates them; shell expansions, arithmetic and here-documents in templates and scripts; the commands a template runs; TOML headers; triggers the walker could not read), each fix shown necessary by a source mutation that reverses it (thirty-one, astra-sweep/r2-mutations/summary-pass2.txt).
  • Import and identifier boundaries: read from the pinned TypeScript 7.0.2's unstable JS API, as for the delivery core; loaders obtained at run time are not visible to it, so it guards against accidental coupling, not deliberately hostile source.
  • Not established: any live source. For sentry/2, posthog/2 and datadog/1: no read credential exists, no adapter or recipe reads with one, and nothing renders their runbooks (increment 3). Their vendor rungs and console paths (Sentry's internal integrations, PostHog's personal API key scopes, Datadog's service accounts and application key scopes) follow the vendors' public documentation as understood on 2 October 2026 and were not observed against a live account. No agentic CLI rung is listed for any of them, and each step skips the classic CLI as shows-secret (it would print a new credential where an agent could read it) or unproven; whether any vendor CLI could do a step safely is not established, and a reviewed revision with a drill would be needed to list one. For cloudflare/1, anything beyond names: no presence declaration or runbook (C3; the C2 scanner's instances, Workers, route hosts and bindings are recorded in the discovery input and feed nothing else yet, apart from secret-as-variable for a secret's name among vars), public-presence reader (C4) or recipe (C5–C7) exists, and a vault-only slot's name found in a GitHub store is classified but raises no finding of its own. No reader runs git or gh (increment 2). Vault presence (increment 4) is read only from a fake op. No real op has run on this host, so the shape of 1Password CLI 2's op item list output, as the reader expects it, is not observed here. That shape covers the keys, the timestamp form, whether an empty vault prints [] or nothing, versions starting at 1, and the wording of its signed-out, locked and missing-vault errors. Its classification of standard error is a pattern match, and an unmatched message reads as listing-failed, which is unknown either way. Nothing composes the reader. That it is launched only by the owner, so that an agent session never triggers 1Password's unlock prompt, is a convention, not something the code enforces. The reader is not packaged. Runbooks and blockers do not exist (increment 3), and no value-touching code exists (increments 5–9). The credential screen is a heuristic over shapes, not proof that no recorded name is a secret. The workflow grammar and the shell reading approximate libyaml and bash (the scalar decoder follows YAML 1.2's escapes and flow folding and refuses any other escape; the script reading follows bash, whose reading of a quote inside a backtick substitution POSIX leaves undefined; the template reading assumes a shell that brings no aliases or functions of its own, as a non-interactive one does; a script's array elements are read as the command line such an array commonly holds, so a forward written in an array is recorded as one): what they cannot follow is partial or ends the reading, never guessed, but a construct neither anticipates may still be misread; a hostile repository can always write a name-shaped secret as a name. Every discovery's command stores its whole names-only input in the journal (about 22 KB for the Tally-shaped fixture), and nothing compacts that history; a tree scan kept once per commit is proposed for increment 2. Any catalogue revision changes the detection digest, so every Product's readiness is catalogue-drift until its next discovery. The Tally fixture is synthetic: it follows the re-checked facts in judging.md but is not Tally, and the live map (increment 2) may differ, for example where Tally's own syntax falls outside the line grammar. Detection is a catalogue of named signatures, not a secret scanner: history, other branches, provider-held variables, the Keychain and local files stay unknown. Organisation-level secrets and variables are not listed (spec decision 6), yet GitHub resolves a name from the environment, then the repository, then the organisation: in a repository an organisation owns, a name absent from the repository's and environment's listings may still be an organisation secret, and this increment's absence, referenced-not-stored and missing do not account for that level (an open question for the implementation review). Findings are proposals, never verdicts. Bindings, declarations, confirmations and pins are attribution that any process able to write the journal can forge (the combined model's trust scope); nothing here authenticates an owner. Organisation-aware presence now preserves unknown owner type and requires sufficient organisation listing before proving absence.

Composition

  • Depends on: Command journal and canonical JSON; src/reporting-contract.ts for Count and CoverageStatus. Portfolio reexports the same types.
  • Used by: nothing yet. Vault presence (increment 4) is built locally, tested against a fake op, independently reviewed and integrated 2 October 2026, and not accepted.
  • Planned (spec §12, not built): read-only readers under an owner commission (increment 2), runbooks with per-step checks and Portfolio blockers (3), a Product gate revision for service grants (5), a confined executor profile with a loopback egress proxy (6), the separate credential-broker module (7), a first owner-granted live brokered read (8) and grant anchoring (9).

Changing it safely

  • Run node --test test/service-kinds.test.ts test/service-cloudflare.test.ts test/service-ops-kinds.test.ts test/service-discovery.test.ts test/service-access.test.ts test/service-access-canaries.test.ts test/service-access-boundaries.test.ts test/service-access-adversarial.test.ts test/service-access-regressions.test.ts test/service-vault-reader.test.ts, then npm run check.
  • The vault reader runs one argument list: widening checkOpArgv (another subcommand, flag or output format) is a security change for independent review, and no form that can print a value is ever admitted. A real op run belongs to the owner-run drill, never a test.
  • A kind change is a new revision (vercel/2) through defineKind, never an edit in place: its digest changes, stored maps show drift, and readiness for its needs is unknown until rediscovery. Move the superseded spec to SUPERSEDED_KIND_SPECS unchanged (posthog/1 and sentry/1 are there), so a recorded map can still be read under the catalogue that recorded it; a need naming the superseded id is refused KIND. A step interface or reason is a claim about the vendor's tools: name a rung unproven unless a reviewed template and drill establish it. A change to any signature, slot name or class, name prefix or name rule changes the detection digest and so every Product's readiness until rediscovery.
  • A change to the credential screen changes what is recorded: rerun the canary suite, and treat a narrower screen as a security change for independent review.
  • Any change to a stored shape, a command ID, a key formula or the reference id changes recorded history: stored states must still parse or gain a versioned reader.
  • Reviewers check: nothing reads a value, no scanner keeps text from a value position or reads a line inside another line's value as structure, every YAML scalar is decoded before a name is read from it and a TOML line is read only under its own table, a scanner stops rather than guesses where parsers would disagree, every recorded path, name and identifier passes the screen, every scanner output parses as input (and nothing a scanner or reader would not write does), no decision does I/O or reads a clock, refusals record nothing, and every new bound refuses rather than truncates (a per-file bound drops the whole file).

Shared value implementation: common contracts. Owning errors, limits, stored identities and authority remain as specified above.

Source: docs/agents/service-access.md