@zackbart/connecta 0.36.0 → 0.36.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/CHANGELOG.md +55 -0
  2. package/README.md +1 -1
  3. package/bin/version.mjs +1 -1
  4. package/dist/auth/downstream-oauth.js +3 -0
  5. package/dist/auth/oauth-authorization-params.js +52 -0
  6. package/dist/auth/static-oauth.js +1 -4
  7. package/dist/connectors/option-shapes.js +1 -0
  8. package/dist/connectors/remote-mcp.d.ts +4 -1
  9. package/dist/connectors/remote-mcp.js +12 -1
  10. package/dist/google.d.ts +13 -0
  11. package/dist/google.js +42 -0
  12. package/dist/http/hatch-paging.js +2 -2
  13. package/dist/http/paging.js +3 -88
  14. package/dist/http/provider.js +1 -2
  15. package/dist/http/tools.js +1 -23
  16. package/dist/program-writes.js +0 -1
  17. package/dist/providers/_shared/google/service-account.d.ts +1 -1
  18. package/dist/providers/_shared/google/service-account.js +20 -8
  19. package/dist/providers/_shared/sensitive-fields.js +0 -16
  20. package/dist/providers/breeze/api.js +2 -2
  21. package/dist/providers/ccb/api.js +1 -1
  22. package/dist/providers/cloudflare/api.js +8 -8
  23. package/dist/providers/cloudflare/lib/config.d.ts +2 -1
  24. package/dist/providers/docs/api.js +1 -1
  25. package/dist/providers/drive/api.js +1 -1
  26. package/dist/providers/drive/lib/hatch.js +1 -1
  27. package/dist/providers/drive/tools.js +1 -1
  28. package/dist/providers/forms/api.js +1 -1
  29. package/dist/providers/forms/lib/hatch.js +1 -1
  30. package/dist/providers/forms/tools.js +1 -1
  31. package/dist/providers/github/api.js +1 -1
  32. package/dist/providers/github/lib/discovery.js +2 -2
  33. package/dist/providers/gmail/api.js +1 -1
  34. package/dist/providers/granola/api.js +155 -0
  35. package/dist/providers/granola/index.d.ts +10 -0
  36. package/dist/providers/granola/index.js +68 -0
  37. package/dist/providers/granola/openapi.generated.js +30 -0
  38. package/dist/providers/granola/safety.js +37 -0
  39. package/dist/providers/granola/skill.generated.js +5 -0
  40. package/dist/providers/granola/tools.js +2 -0
  41. package/dist/providers/overflow/api.js +26 -26
  42. package/dist/providers/planning-center/api.js +4 -4
  43. package/dist/providers/planning-center/lib/constants.d.ts +1 -1
  44. package/dist/providers/planning-center/lib/json-api.js +2 -2
  45. package/dist/providers/quickbooks/lib/query.js +1 -1
  46. package/dist/providers/quickbooks/safety.js +1 -1
  47. package/dist/providers/sheets/api.js +1 -1
  48. package/dist/providers/sheets/lib/hatch.js +2 -2
  49. package/dist/providers/sheets/lib/requests.js +1 -1
  50. package/dist/providers/slides/api.js +1 -1
  51. package/dist/providers/stripe/api.js +7 -7
  52. package/dist/providers/tithely/api.js +2 -2
  53. package/dist/providers/vercel/api.js +12 -12
  54. package/dist/providers/vercel/lib/pin.js +1 -1
  55. package/dist/request-token.d.ts +7 -0
  56. package/dist/request-token.js +1 -0
  57. package/dist/routes/mcp.js +1 -1
  58. package/dist/runtime/admission.js +0 -12
  59. package/dist/storage/keys.js +2 -3
  60. package/dist/version.d.ts +1 -1
  61. package/dist/version.js +1 -1
  62. package/documentation/README.md +13 -12
  63. package/documentation/architecture.md +148 -76
  64. package/documentation/auth.md +198 -4
  65. package/documentation/code-mode.md +6 -6
  66. package/documentation/meta-tools.md +5 -2
  67. package/documentation/operator-tests.md +11 -2
  68. package/documentation/operator-ui.md +1 -2
  69. package/documentation/providers.md +110 -0
  70. package/package.json +10 -2
  71. package/templates/node/package.json +1 -1
@@ -763,9 +763,9 @@ adoption, OAuth handoff ownership, single-use connect links, every downstream
763
763
  OAuth grant write and consent claim, the result stash, and initialization of the cursor signing key.
764
764
 
765
765
  Every key is built in `src/storage/keys.ts`, which lists each family with its
766
- scope, version, codec, and TTL policy; `test/storage-keys.node.test.ts` fails when
767
- two families overlap, another source file spells a prefix (constant concatenation
768
- folded), or a storage call passes a key holding literal text. Core hands
766
+ scope, version, codec, and TTL policy. Deployed-consumer persistence journeys
767
+ check actual owner isolation in the physical database; key probes retain NUL
768
+ refusal. Core hands
769
769
  subsystems namespaced views: `conn:<id>:` per connector, `principal:<key>:` per
770
770
  personal registry, `results:` and `subject:<key>:` for result paging.
771
771
 
@@ -1199,6 +1199,15 @@ meaning. These facts do not change agent error fields or write outcomes.
1199
1199
 
1200
1200
  ## Configuration
1201
1201
 
1202
+ Downstream OAuth browser extensions use `auth.authorizationParams` on
1203
+ `remoteMcp()` and `oauth.authorizationParams` on `api()`. Both snapshot and
1204
+ validate the string map at construction, reserve protocol/security parameters
1205
+ case-insensitively, and add entries only when publishing the consent URL.
1206
+ Remote MCP includes canonical sorted entries in its existing client configuration
1207
+ binding (omitted and empty maps remain equivalent); static API OAuth retains
1208
+ its existing token-endpoint binding. The [auth contract](./auth.md#browser-authorization-parameters)
1209
+ owns limits, reserved names, and reconnect requirements.
1210
+
1202
1211
  `ConnectaConfig` is one schema (`src/config.ts`, combinators in
1203
1212
  `src/config-schema.ts`). The same value produces the TypeScript type a
1204
1213
  deployment writes, the unknown-key walk createConnecta runs before reading any
@@ -1210,8 +1219,8 @@ is resolved in place of the caller's object, so no getter or Proxy trap runs;
1210
1219
  an accessor on a config object or array is refused by path, as is an object
1211
1220
  that cannot be inspected. A closed object or record slot takes a plain object
1212
1221
  only: an array or a class instance there is refused by path, unread. String
1213
- maps (static `headers`, `api()`'s `authorizationParams` and
1214
- `tokenRequestHeaders`) are copied the same way and each value must be a
1222
+ maps (static `headers`, remote MCP and `api()` OAuth `authorizationParams`,
1223
+ and `api()` OAuth `tokenRequestHeaders`) are copied the same way and each value must be a
1215
1224
  string. A discriminated union (`remoteMcp()`'s `auth.type`,
1216
1225
  a provider's `auth.type`) with a missing or unrecognized discriminant throws
1217
1226
  with the valid values. Only plain data is copied. Connectors, modules,
@@ -1266,20 +1275,16 @@ removed. Legacy hosted selectors fail at construction with the generic migration
1266
1275
  path. GitHub retains its scope-enforced App identity and exposes a bounded repository-read and release-write hatch plus local scope discovery, scoped data search and guarded merge.
1267
1276
 
1268
1277
  [Decision 0011](https://github.com/zackbart/connecta/blob/main/decisions/0011-provider-standard.md)
1269
- records the provider standard now implemented by all 15 maintained providers. It fixes
1278
+ records the provider standard implemented by every maintained provider. It fixes
1270
1279
  one folder layout per kind and fixed evidence names. `drift.json` gets a
1271
1280
  generated block and the guide a generated Conventions section, and every
1272
- `api()` surface gets one agent-facing shape. Providers completed two migration
1273
- steps: onto the kit with unchanged output, then onto the standard surface.
1274
- Both `PENDING.step1` and `PENDING.step2` in `test/provider-standard.ts` are empty;
1275
- every maintained provider now meets the standard without a migration exemption.
1276
- `test/provider-standard.node.test.ts` holds every maintained provider folder to the
1277
- standard, and `test/provider-conventions.test.ts` checks the surface rules on
1278
- Node. `providers:generate` writes the standard's derived parts and
1279
- refuses a provider past step 1 that breaks the `drift.json` rules, or one past
1280
- step 2 that breaks the guide rules: `drift.json` version 2's `generated` block
1281
- (operations from the kit's `ProviderKitFacts` and evidence digests), and a guide's `## Conventions`, rendered
1282
- from the definition's declarations into `skill.generated.ts`.
1281
+ `api()` surface gets one agent-facing shape. Every maintained provider meets the
1282
+ standard without a migration exemption. `test/provider-standard.node.test.ts`
1283
+ holds every provider folder to it, and `test/provider-conventions.test.ts`
1284
+ checks the surface rules on Node. `providers:generate` refuses drift (D) and
1285
+ guide (G) violations before writing. It derives `drift.json` version 2's
1286
+ `generated` block from kit operations and evidence digests, and the guide's
1287
+ `## Conventions` from definition declarations into `skill.generated.ts`.
1283
1288
  The generator requires `fixtures.ts` to export `createAuthored()` with a
1284
1289
  nonempty offline `staticTools` catalog. Its input/output schemas derive one
1285
1290
  paging convention, including `get_*`, hatch search and details, excluding
@@ -1291,8 +1296,9 @@ reports a nonzero explicit refusal count with singular/plural wording and
1291
1296
  points to the actual prefixed details tool with method/path lookup; it never
1292
1297
  embeds the refusal table. Unreviewed operations remain refused.
1293
1298
  `ProviderContext.usageGuide` selects a guide's `<!-- when: <key> -->` blocks
1294
- with the definition's `blocks`. `providers:check` reads both record versions,
1295
- reports a manifest operation no endpoint row records at the provider's level,
1299
+ with the definition's `blocks`. Maintained drift records use version 2;
1300
+ `providers:check` retains version-1 endpoint/manual record parsing for historical
1301
+ reports, while OpenAPI generation and checks use `evidence/openapi.json`. It reports a manifest operation no endpoint row records at the provider's level,
1296
1302
  and lists manual checks last verified more than 180 days ago. Its offline
1297
1303
  record validator, `scripts/drift-validate.mjs`, also gates `providers:generate`
1298
1304
  and the standard suite, so a record they accept is one `providers:check` reads.
@@ -1356,8 +1362,10 @@ acknowledgement, then reconciles vendor state with exactly one physical send.
1356
1362
  `test/provider-privacy-journey.node.test.ts` checks credential echoes over HTTP.
1357
1363
  Focused provider suites retain MIME/draft restrictions, revision conflicts,
1358
1364
  CCB routing, Planning Center product exclusions and deployment pins. Native
1359
- HTTP framing, cursor and request-lifetime fault probes remain in the HTTP suites;
1360
- catalog copies and decoder/adapter parity matrices are retired under #1072.
1365
+ HTTP framing, cursor and request-lifetime fault probes remain in the HTTP suites.
1366
+ The catalog-wide status sweep and its argument roster, catalog/ranking copies
1367
+ and unused paging strategy tests are retired under #1072. Provider workflows
1368
+ belong in the existing shared outcomes; a new tool requires no failure-matrix row.
1361
1369
  No legacy REST tool adapter remains.
1362
1370
  Large documents opt into generator options that drop restated operation ids
1363
1371
  and plain path parameters and cap one operation's details (`opBudget`).
@@ -1376,7 +1384,7 @@ schemaless and non-JSON responses declare no fields. Request shrinking and
1376
1384
  endpoint contract digests do not depend on this metadata.
1377
1385
  Fields remain optional additive metadata, so a previously compiled
1378
1386
  index without the source bytes remains usable without inventing a response
1379
- contract. Vercel's step-2 pin review restores response metadata from the reviewed public
1387
+ contract. Vercel's pin includes response metadata from the reviewed public
1380
1388
  document; operations without declared response properties still refuse fields. Breeze's pin declares no response
1381
1389
  properties. GitHub's immutable official OpenAPI pin supplies its complete index and response fields; a reviewed repository allowlist controls dispatch. Natural queries with reviewed matches scope discovery to those matches and named-only operations; explicit paths and unmatched queries retain full-pin refusal discovery.
1382
1390
  `check:providers-generated` checks each index header against its source record
@@ -1435,14 +1443,12 @@ every vendor ships one reviewed table through one mechanism
1435
1443
  signing, webhooks, drains, transfer, claim, and invite codes). It is the
1436
1444
  union of the detectors Cloudflare and Vercel shipped first, and
1437
1445
  deliberately over-inclusive. `providers:spec` writes
1438
- `evidence/value-safety.json` (`value-safety.candidates.json` until the
1439
- provider's step 1) when the source record sets
1446
+ `evidence/value-safety.json` when the source record sets
1440
1447
  `options.valueSafety` (vendor `operationWords`; Stripe's `expansions: false`
1441
1448
  skips id-or-object expansions, which are their own operations' candidates),
1442
1449
  stamped with the pinned digest, the detector format, and its options. The
1443
1450
  file is test evidence and never ships.
1444
- 2. **One reviewed verdict per candidate**, in the vendor's `safety.ts`
1445
- (`value-safety.ts` until its step 1):
1451
+ 2. **One reviewed verdict per candidate**, in the vendor's `safety.ts`:
1446
1452
  `refuse` (the generic tools refuse it before transport, naming the
1447
1453
  operation and the reason), `redact` (reviewed field paths), or `safe`, each
1448
1454
  with a reason. Paths are dot paths into the data a tool returns: a list on
@@ -1627,14 +1633,13 @@ response schema can return (through `options.valueSafety.dataRoot` for an
1627
1633
  envelope such as Cloudflare's `result`), and every resource rule path
1628
1634
  something the resource's schema can return. It stamps the paths that resolve
1629
1635
  into the candidates file and fails on the rest, unless the table's `absent`
1630
- field (`value-safety.absent.json` until the provider's step 1) acknowledges
1636
+ field acknowledges
1631
1637
  them with a reason (shared verdicts applied to operations whose schema lacks a
1632
1638
  path, or fields a schema leaves undeclared; such paths still apply at
1633
1639
  runtime).
1634
1640
 
1635
1641
  `test/fixtures/value-safety.ts` is the shared harness each vendor's
1636
- `value-safety.node.test.ts` (`provider.safety.node.test.ts` after its step 1)
1637
- runs; `reviewProblems` is pure, and
1642
+ `provider.safety.node.test.ts` runs; `reviewProblems` is pure, and
1638
1643
  `test/value-safety-harness.node.test.ts` proves wrong paths fail it. It fails
1639
1644
  on candidates from another pin, format, or option set; an unreviewed
1640
1645
  candidate; a verdict for an operation the index lacks; a table path the stamp
@@ -1672,21 +1677,74 @@ capture determinism. Production invariants remain unchanged.
1672
1677
  Use the existing stateful fixture vendors and published-edge deployment adapters:
1673
1678
 
1674
1679
  - `pnpm run eval:outcomes` drives representative joins, retained paging, endpoint
1675
- refusal, auth handoff, value safety and refund recovery. Graders inspect
1680
+ refusal, auth handoff, value safety and recovery after committed refunds,
1681
+ cancellations, DNS and environment updates, plus a single GitHub draft release
1682
+ and Google document partial creation and shared-drive permissions. Graders inspect
1676
1683
  independent downstream state and the physical mutation ledger, and reject
1677
1684
  wrong targets, duplicate writes, missing completion and interrupted trials.
1685
+ Every reference also rejects a fabricated correct answer without the work.
1686
+ Promoted read journeys reject erased MCP data even with the vendor ledger intact.
1678
1687
  - `pnpm run eval:smoke` boots the Node template, Node eval deployments and native
1679
- Workers deployments, including the actual QuickBooks provider, then exercises
1688
+ Workers deployments, including the actual QuickBooks and Granola providers, then exercises
1680
1689
  MCP and the operator page.
1690
+ - The shared `granola-workspace-journey` outcome uses actual provider reads,
1691
+ independent fake meeting state and physical cursor/filter requests on both
1692
+ Node/SQLite/QuickJS and native Workers/D1. It covers transcript-too-large
1693
+ recovery, empty intermediate pages, selected fields, withheld photo/credential
1694
+ values and shared-vault reuse after application reconstruction. No-op,
1695
+ fabricated-read and erased-delivery controls must fail.
1696
+ - `test/identity-write-journey.node.test.ts` uses the existing Node deployment
1697
+ adapter, stateful MCP fake, SQLite vault and QuickJS to grade admitted human
1698
+ and machine identities, pool isolation, fail-closed discovery, endpoint and
1699
+ connector policy, physical mutation counts, ambiguous-write reconciliation,
1700
+ credential ownership and payload-free activity. Independent decoding checks
1701
+ returned private values and credential echoes; positive record facts must
1702
+ still arrive. An explicitly writable pool also exercises reopening a
1703
+ read-only deployment without bypassing connector policy.
1704
+ - `test/cancellation-journey.node.test.ts` observes a queued client's departure
1705
+ without another vendor send, and an active client's departure after the
1706
+ vendor commits. The vendor must see its held response socket close before
1707
+ releasing it; a later MCP read recovers the committed intent exactly once.
1708
+ `test/cancellation-faults.test.ts` keeps signal-less token-resolution,
1709
+ warmed-credential digest, stalled body-cleanup and abort/grant races on Node
1710
+ and workerd. These replace the universal Promise-method/seam/owner matrix
1711
+ and its enrollment self-test, plus migration-only runtime wrapper checks.
1712
+ - `test/browser/operator-flows.spec.ts` serves the actual operator shell and
1713
+ routes over TCP with file-backed SQLite. Sign-in, Settings provenance, OAuth
1714
+ connect/disconnect and credential save/test/replace/remove survive closing and
1715
+ reopening the app, database and vault. An independent SQL connection reads
1716
+ trigger counts: one save, one replacement, one removal, and no credential
1717
+ writes from reads or a rejected replacement. A real SQL trigger failure leaves the old
1718
+ credential usable after restart. MCP calls verify that those edits preserve
1719
+ the reader pool's actual read access and write refusal. Activity renders
1720
+ successful calls recorded before restart without either credential value.
1721
+ - The existing Node-template `eval:smoke` target constructs invalid config from
1722
+ published imports before any I/O and reuses a stored token after restarting
1723
+ the consumer process. Its Worker-fakes target saves a personal credential in
1724
+ Chromium, refuses another owner's use, saves that owner's invalid credential,
1725
+ then restarts workerd on the same D1 directory. Actual downstream records
1726
+ remain readable only to the correct owner. Direct SQL inspection finds two
1727
+ distinct durable encrypted rows and exactly one committed save for each.
1728
+ - Keep focused SQL batch/schema/retention rollback, clock-skew and absolute
1729
+ expiry, NUL/UTF-8 and literal-prefix, cross-connection claims, cancellation,
1730
+ corrupt-row and tracing-secrecy probes. Keep operator identity/slot fences,
1731
+ deadlines, CSRF, restricted-view projection and sink secrecy probes. These
1732
+ cover faults that a successful browser journey cannot reproduce. Retired
1733
+ evidence includes the key-prefix source scanner, config expected-object
1734
+ matrices, operator structure snapshots and native-composition sentinels.
1681
1735
  - `test/provider-privacy-journey.node.test.ts` sends credentials through real
1682
1736
  HTTP MCP and a maintained API provider. Unknown vendor fields and keys carry
1683
1737
  raw, escaped, percent-encoded, base64 and Basic echoes through direct calls,
1684
1738
  QuickJS programs, failure and recovery. The independent decoder in
1685
1739
  `test/helpers/secret-echoes.ts` checks the wire responses for secret fragments;
1686
1740
  it does not normalize them to placeholders or compare saved output.
1687
- - `test/provider-failure-sweep.test.ts` checks retained catalog examples for
1688
- dispatched failure, classification, auxiliary and composite write outcomes.
1689
- New providers use the required deployment outcomes above. Existing
1741
+ - `test/provider-hostile-response.node.test.ts` reconciles real HTTP mutations
1742
+ after HTML, malformed JSON and oversized acknowledgements with one physical
1743
+ send. It distinguishes Stripe's reviewed pre-execution 401 refusal, and checks
1744
+ read failure facts, secrecy and recovery through direct and QuickJS calls.
1745
+ `test/provider-failure-sweep.test.ts` retains only concrete auxiliary, composite,
1746
+ in-flight and untracked-call fault probes; no provider/tool argument roster or
1747
+ catalog/finalizer agreement sweep remains. Existing
1690
1748
  `test/sent-secrets.test.ts`, `test/sent-secret-output-boundary.test.ts`,
1691
1749
  `test/request-secret-redaction.test.ts` and `test/catalog-secret-redaction.test.ts`
1692
1750
  cover secrecy before projection, truncation, caching, paging and diagnostics.
@@ -1695,11 +1753,24 @@ Use the existing stateful fixture vendors and published-edge deployment adapters
1695
1753
  Native transport parity, OAuth and write-provenance suites retain their
1696
1754
  workerd coverage. The shared throwaway RSA key in `test/fixtures/rsa.ts` is
1697
1755
  used by write-provenance and unknown-write-advice fixtures.
1698
- - The request, catalog, auxiliary-call, renewal and Promise-boundary lifetime
1756
+ - The request, catalog, auxiliary-call and renewal lifetime
1699
1757
  suites, plus `test/auth-admission-binding.test.ts`, exercise cancellation,
1700
1758
  held native work and garbage collection. These test actual request ownership;
1701
1759
  the retired capture scheduler's source guards were only harness constraints.
1702
1760
 
1761
+ The remaining probes defend distinct reachable failures: auth admission and
1762
+ native scheduler ownership, grant/callback fencing and refresh coordination,
1763
+ SDK replay/redirect/SSE attempts, nested write provenance and refusal evidence,
1764
+ unawaited program drain and failed-program accounting, catalog drift and paging
1765
+ revocation, and hostile serializers, structural echoes, truncation and persisted
1766
+ pages. Broad scripted-executor policy/privacy cross-products and repeated
1767
+ post-401 result/error-shape tables are retired. Protocol claims link executable
1768
+ evidence files in `spec/coverage.json`; the invariant contracts above are defended
1769
+ by the actual behavior assertions in these journeys and focused probes.
1770
+ The required CI gate includes build/declarations, Node and Workers probes,
1771
+ outcomes, browser flows, installed consumers and Docker, audits and real Eve
1772
+ compatibility. Further contributor cleanup is tracked in #1072.
1773
+
1703
1774
  Add a compact fault journey only for a meaningful outcome those suites cannot
1704
1775
  observe. Reuse their fixtures and adapters; do not reintroduce a snapshot
1705
1776
  format, module loader or virtual scheduler. Workerd enrollment is for native
@@ -1708,6 +1779,19 @@ fetch, streams, Web Crypto, lifetime and request-byte behavior, as listed in
1708
1779
 
1709
1780
  ## Optional deployment modules
1710
1781
 
1782
+ `/google` (`src/google.ts`) exports the Promise-based
1783
+ `googleServiceAccountToken` request-token resolver outside the root graph.
1784
+ It reuses `src/providers/_shared/google/service-account.ts` for Web Crypto,
1785
+ in-memory token caching and exact-token invalidation, with an absent subject
1786
+ for service accounts acting as themselves. Workspace providers keep supplying
1787
+ subjects and retain their delegated error guidance. `src/request-token.ts`
1788
+ owns the callable resolver contract and optional HTTP-401 invalidation hook;
1789
+ `remoteMcp()` invokes it without replaying the failed operation.
1790
+ `test/google-service-account-token.test.ts` exercises signing/cache behavior on
1791
+ Node and workerd; `test/google-service-account-remote.node.test.ts` checks
1792
+ real-socket token/MCP requests, invalidation and one physical attempt per write.
1793
+ Operator setup lives in [Google hosted MCP](./auth.md#google-service-account-tokens-and-hosted-mcp).
1794
+
1711
1795
  `createConnecta` takes closed typed `ui`, `vault`, and `activity`
1712
1796
  slots, with factories at `/ui`, `/credentials`, and `/activity`
1713
1797
  and agent tokens at `/auth/access-tokens`. Root exports the contracts, never the implementations, and there
@@ -1822,9 +1906,9 @@ declarations; elsewhere it lives in an unexported function or in
1822
1906
  (`ConnectorCallError`, `ExecutorAdmissionError`, `CallAdmissionError`) because
1823
1907
  callers and tests check `instanceof`, `name`, and `message`.
1824
1908
 
1825
- Effect callers skip the Promise and take the program: `admit` and
1826
- `acquireScoped` for request admission (`src/runtime/admission.ts`), `admitCall`
1827
- and `acquireCallScoped` for call admission, `closeScope` and `closeScopeOnExit`
1909
+ Effect callers skip the Promise and take the program: `admit` for executor
1910
+ admission (`src/runtime/admission.ts`), `admitCall` and `acquireCallScoped` for
1911
+ call admission, `closeScope` and `closeScopeOnExit`
1828
1912
  for a connector scope, `withDeadlineEffect` where Promise code has
1829
1913
  `withDeadline`. The build prunes every declaration no `exports` target reaches,
1830
1914
  and `pnpm run check:declarations` fails if what remains names an Effect type.
@@ -2044,8 +2128,8 @@ published storage interfaces.
2044
2128
  The synchronous state-file parser, validation, file read, and one atomic
2045
2129
  SQLite import remain native synchronous leaves because `importStateFile` is a
2046
2130
  published synchronous API. `openSqlite` retains file modes, WAL, busy timeout,
2047
- and database ownership. `test/sql-effect-contract.ts` runs native-path,
2048
- affected-row, 50-claim, cancellation, and tracing checks on SQLite and native
2131
+ and database ownership. `test/sql-effect-contract.ts` retains affected-row,
2132
+ 50-claim, typed-failure, cancellation, and tracing probes on SQLite and native
2049
2133
  D1. `test/kv-to-d1.test.ts` also reuses stores across separate workerd requests;
2050
2134
  the existing SQL contracts prove rollback, database-clock TTL, encodings,
2051
2135
  activity upgrades, and copy recovery.
@@ -2198,8 +2282,7 @@ ordinary Promise-based Connector factory. The kit stays outside the root
2198
2282
  graph and its Effect types are internal. In each provider, `api.ts` declares
2199
2283
  the vendor and `tools.ts` the tools.
2200
2284
 
2201
- Decision 0011's standard surface (Tithe.ly's step 2) adds four kit pieces.
2202
- A `list` without the legacy `key` returns `{ items, page }`, with
2285
+ The standard `list` builder returns `{ items, page }`, with
2203
2286
  `page.nextCursor` only while `hasMore`, and the kit appends `limit` (the
2204
2287
  declared default and maximum), `cursor` and `fields` to the tool's filters;
2205
2288
  `read` and `get` take `fields: true`. `src/http/fields.ts` narrows after every
@@ -2441,8 +2524,8 @@ after repairing/deleting a corrupt key, restart every process/isolate to clear
2441
2524
  cached keys. Pre-upgrade cursors require a new first page.
2442
2525
 
2443
2526
  The helper derives connection metadata and probe messages from
2444
- validated options and still accepts complete legacy usage guides for compatibility.
2445
- All maintained providers have completed the standard-surface migration.
2527
+ validated options and renders every maintained guide through
2528
+ `ProviderContext.usageGuide`.
2446
2529
  Candidate checks can refuse before authentication while
2447
2530
  preserving the provider's exact diagnostic. Its optional `authScope(options)`
2448
2531
  selector fixes OAuth grant ownership from deployment mode at construction;
@@ -2544,7 +2627,7 @@ dispatch.
2544
2627
 
2545
2628
  The generator's `allSuccessResponses: true` option unions JSON response fields
2546
2629
  from every 2xx. Existing providers keep the first JSON success contract until
2547
- their own reviewed regeneration; no committed provider index changes here.
2630
+ their own reviewed regeneration.
2548
2631
 
2549
2632
  `src/providers/_shared/google/hatch.ts` supplies JSON framing over the existing
2550
2633
  confined `Connection.sendPath`. It retains the hatch's origin/media guards,
@@ -2571,8 +2654,7 @@ For example, a direct value-mode result has outer `result.data`, the hatch's
2571
2654
  `result.data.page.nextCursor`, and vendor JSON at `result.data.data`:
2572
2655
  `call_tool({ address: "crm.forms_api_read", args: { path:
2573
2656
  "/forms/form_1/responses", cursor: previous.data.page.nextCursor },
2574
- resultMode: "value" })`. This is an envelope illustration for an opted-in
2575
- provider, not a claim that the Forms migration has shipped.
2657
+ resultMode: "value" })`. Google Forms uses this continuation envelope.
2576
2658
 
2577
2659
  `googleErrors(product, { standard: true })` declares the product's 404 meaning
2578
2660
  and uses common status fallbacks; revision-conflict meanings require a
@@ -2602,7 +2684,7 @@ Sheets declares its seven API methods in `src/providers/sheets/api.ts`; its
2602
2684
  kit tools retain the private digest-bound cell cursor, legacy A1 path encoding,
2603
2685
  and create/append recovery advice. Its projections and the Google failure
2604
2686
  classifier read fields by the names Google gave them, which the kit's parse pass
2605
- keeps. Its catalog and guide stay unchanged in step 1.
2687
+ keeps.
2606
2688
 
2607
2689
  Google's request adapter also offers a reviewed binary send. It marks the
2608
2690
  operation `googleBytes` for the product's `binaryBodies` selector and forwards
@@ -2814,8 +2896,8 @@ result handling, reviewed value safety and the deployment privacy projection
2814
2896
  before paging or provider projections can read it. Read methods beyond GET
2815
2897
  and HEAD require a review. Construction fixes each write step's capacity;
2816
2898
  the guarded transport reserves it before preparation and the shared core
2817
- decides the whole call's write outcome. Dedicated upload builders wait for
2818
- the Google Drive migration in C.7.
2899
+ decides the whole call's write outcome. Drive uploads use write builders over
2900
+ reviewed raw-body sends.
2819
2901
 
2820
2902
  Reviewed path calls resolve their actual method and path through an indexed
2821
2903
  safety adapter; a provider-supplied template cannot bypass the policy.
@@ -3026,7 +3108,8 @@ compiling and configuring the real thing.
3026
3108
  rejections are observed; dispatch and lease guards still contain detached
3027
3109
  work. Per-await I/O cancellation remains useful for releasing resources,
3028
3110
  while prompt refusal is enforced at the boundary
3029
- (`test/promise-boundary-lifetime.test.ts`). Invocation owns
3111
+ (`test/cancellation-faults.test.ts`, `test/operation-cancellation.test.ts`
3112
+ and `test/cancellation-journey.node.test.ts`). Invocation owns
3030
3113
  the recovery and logical-call records it reads after teardown. Closing an
3031
3114
  outer call also revokes nested calls paused in preparation. Request-owned
3032
3115
  MCP sessions and token flights outlive individual calls and close with the
@@ -3119,8 +3202,9 @@ compiling and configuring the real thing.
3119
3202
  at construction) and the predicate matched, which the ledger records on the
3120
3203
  request. Only Stripe declares it (`src/providers/stripe/api.ts`, reviewed
3121
3204
  as a `manual` check in its `drift.json`): an API v1 answer carrying Stripe's
3122
- `Request-Id`. `test/provider-failure-sweep.test.ts` holds that list to the
3123
- sources. Q8 is decided in one place, `settleWrite` in
3205
+ `Request-Id`. The real HTTP hostile-response journey checks this refusal
3206
+ against an ambiguous committed write; there is no copied declaration list.
3207
+ Q8 is decided in one place, `settleWrite` in
3124
3208
  `src/write-outcome.ts`, once per logical call and over every request it
3125
3209
  recorded. The invocation calls it for every failure of a served write: a
3126
3210
  thrown or mapped error, a custom connector's, a program's call, and its
@@ -3369,29 +3453,17 @@ compiling and configuring the real thing.
3369
3453
  `write_outcome_unknown`. The caller's own abort reason still passes by
3370
3454
  identity for a read and for a served call, whose timeout passes through
3371
3455
  unchanged for the invocation to report.
3372
- The catalog-driven `test/provider-failure-sweep.test.ts` checks every API
3373
- provider/tool on Node, fails on missing provider/tool examples or a
3374
- dispatched failure bypassing the helper, and covers served write/read
3375
- overrides with HTTP 503 for every tool and a connection reset after send
3376
- for each provider/verdict representative. HTTP 401 recovery uses those
3377
- representatives plus the distinct composite, auxiliary, owner-lookup and
3378
- POST-as-read paths.
3379
- Shared sender and real-socket evidence below own status/reset permutations.
3380
- Local metadata
3381
- tools prove zero sends; composite calls prove each distinct request leaves
3382
- once. The round-5 cases additionally cover Docs creation with initial text,
3383
- composite success followed by refusal, GitHub preflight failures, typed
3384
- handler errors after successful sends, Forms cursor conflicts after 200,
3385
- generic-code vendor refusals, auxiliary failures after resource dispatch,
3386
- redaction of refusal errors, and concurrent direct-call ledger isolation.
3387
- The round-6 cases cover a composite write's early refusal while siblings
3388
- await credentials or are in flight, requests started after the call ended,
3389
- connect-phase errnos with each body kind (all unknown for a write, and a
3390
- direct read stays retryable), a request aborted with a refusal-shaped
3391
- reason, an errno outside fetch's network error, and
3392
- undeclared handlers whose untracked send precedes a typed failure. Each
3393
- catalog case also checks that the ledger recorded every resource request
3394
- the network saw, and the inventory that every API connector declares it.
3456
+ Shared provider outcomes and the real HTTP hostile-response journey check
3457
+ returned data, failure/recovery, privacy and physical writes without a
3458
+ catalog-wide status matrix. `test/provider-failure-sweep.test.ts` retains
3459
+ fault probes for Docs creation with initial text, composite success followed
3460
+ by refusal, GitHub preflight failures, typed handler errors after successful
3461
+ sends, Forms cursor conflicts after 200, generic-code vendor refusals,
3462
+ auxiliary failures after resource dispatch and concurrent direct-call isolation.
3463
+ It also holds siblings awaiting credentials or already in flight when another
3464
+ write fails, refuses requests after call closure, and probes network errors,
3465
+ refusal-shaped abort reasons and untracked sends. Native transport and
3466
+ request-lifetime suites retain their platform-specific evidence.
3395
3467
  `test/write-evidence.test.ts` uses real refused, reset, and held sockets on
3396
3468
  both runtimes: a refused write is unknown and a refused read retryable,
3397
3469
  including a write aborted with another fetch's real refusal as its reason