@zackbart/connecta 0.16.0 → 0.16.1

package/documentation/meta-tools.md

@@ -229,7 +229,13 @@ results explain that no single tool covered every term and recommend splitting
 distinct intents. A true negative says that no matching capability is
 configured and recommends refining, connector-scoping, or browsing; when a
 connector catalog was unavailable, the response includes
-`unavailableConnectorCount` instead of making that stronger claim. A search
+`unavailableConnectorCount` instead of making that stronger claim. A no-match
+query whose terms name a configured connector's `id` or `title` never makes it
+either: connector identity is not in the lexical index — indexing it would move
+ranking for every query that already matches tools — so instead the guidance on
+an unscoped miss names up to three such connectors by ID and sends the caller
+to a scoped browse. Identity affects that one sentence and nothing else: no
+ranking, no result, and no new field. A search
 explicitly scoped to that unavailable connector also receives `catalogError` —
 the bounded classified failure (`code`, `message`, `retryable`, and any
 `retryAfterMs`) so the caller can tell a transient outage from one a deployment

package/documentation/notion.md

@@ -166,7 +166,7 @@ should do next, and two of Notion's are easy to mistranslate.
 | 400 (`validation_error`, `invalid_json`, `invalid_request`, `missing_version`, …) | `invalid_args` | every documented 400 is a malformed request |
 | 401 `unauthorized` | `auth_required` | the token is missing or invalid |
 | 403 `restricted_resource` | `connector_call_failed`, non-retryable | **not** `auth_required` |
-| 404 `object_not_found` | `connector_call_failed`, non-retryable | overloaded; see below |
+| 404 `object_not_found` | `connector_call_failed`, non-retryable | overloaded — deliberately **not** `not_found`; see below |
 | 409 `conflict_error` | `unavailable`, retryable | Notion says to retry |
 | 429 `rate_limited` | `rate_limited` + `retryAfterMs` | `Retry-After` seconds → ms |
 | 529 `service_overload` | `unavailable` + `retryAfterMs` | back off like a 429 |
@@ -184,7 +184,12 @@ whose message says an operator must change it in Notion.
 object that does not exist and for one that exists but has not been shared with
 the integration, and it will not say which. The message says both, because
 treating it as deletion is exactly how an agent concludes a page is gone when
-it was simply never shared.
+it was simply never shared. This is why the row above does not use `not_found`,
+which exists precisely to say "it is not there": the qualifier on that code
+([H11](./provider-conventions.md#h11--errors-are-mapped-to-what-the-caller-does-next))
+is that the provider must tell absence apart from a permission gap, and Notion
+does not. A program that skipped this id as missing would be right about half
+the time, which is the half that matters.
 
 ## Rate limiting
 

package/documentation/operations.md

@@ -18,6 +18,15 @@ rather than serving a smaller surface
 `new DynamicWorkerExecutor({ loader: env.LOADER })` from
 `@cloudflare/codemode`.
 
+Both executor packages are optional peers: they never install with connecta,
+and a deployment installs the one its runtime needs. The manifest publishes the
+range each release supports — `^0.32.0` for `quickjs-emscripten`,
+`^0.4.4 || ^0.5.0` for `@cloudflare/codemode` — so npm answers the version
+question at install time rather than leaving a deployment to discover the skew
+when a program runs ([#376](https://github.com/zackbart/connecta/issues/376)).
+The version this repository tests against is one the published range admits,
+and `test/package-surface.test.ts` fails if the two ever drift apart.
+
 There are exactly two deployment shapes.
 [`templates/node/`](../templates/node/) is what `connecta init` copies — the
 one standalone Node project, Docker-ready rather than Docker-only — and
@@ -108,9 +117,13 @@ deployment repository
 ```
 
 An upgrade is an intentional dependency change followed by a normal build.
-Instances must not share KV namespaces, D1 databases, secrets, or encryption
-keys. Keeping deployment configuration private is sensible even though this
-package is public.
+Doing it to a deployment somebody else generated — reading its pin, diffing it
+against the template generation it came from, and crossing the version
+boundaries that break construction — is [upgrading](./upgrading.md), which is
+written for the agent sitting inside that deployment rather than inside this
+repository. Instances must not share KV namespaces, D1 databases, secrets, or
+encryption keys. Keeping deployment configuration private is sensible even
+though this package is public.
 
 ## Verification
 
@@ -118,7 +131,7 @@ package is public.
 
 | Script | What it gates |
 | --- | --- |
-| `check:docs` | local Markdown targets and fragments, guide and ethos size caps, duplicate heading anchors, a resurrected `docs/`, stale manual references |
+| `check:docs` | local Markdown targets and fragments — including the `github.com` and `raw.githubusercontent.com` URLs that point back into this repository — guide and ethos size caps, duplicate heading anchors, a resurrected `docs/`, stale manual references |
 | `check:operator-ui` | the committed browser bundle matches its source, byte for byte |
 | `check:lint` | Oxlint's correctness category only — style is authored, not enforced |
 | `check:unused` | Knip's unused-export and dependency gate |
@@ -130,11 +143,38 @@ package is public.
 `npm run release:check` adds `check:security` (`npm audit --omit=dev
 --audit-level=moderate`) and `check:package`, and is what CI runs on every push
 and pull request. `check:package` packs the tarball, asserts the required files
-are in it and that no platform-specific implementation or unshippable path
-leaked in, derives the shipped guide list from which guides still carry a stub
-marker, checks that every packed doc's `documentation/` link resolves to
-something the tarball carries, and then runs `connecta init` and builds and
-runs the generated deployment's own container.
+are in it and that no unshippable path leaked in — including any
+Cloudflare-named connector or storage path (`connectors/cloudflare`,
+`storage/cloudflare`) anywhere in the artifact, `dist/` and `examples/` alike —
+derives the shipped guide list from which guides still carry a stub marker,
+hands the packed path list to `scripts/check-packed-links.mjs`, and then runs
+`connecta init` and builds and runs the generated deployment's own container.
+
+That last step enforces the packed-link policy, which is one sentence: **every
+relative link in shipped Markdown must resolve to a path the tarball carries,
+and a target that is repository-only is cited as an absolute
+`https://github.com/zackbart/connecta/blob/main/...` URL** (the
+`raw.githubusercontent.com` form for an image, which is how the README hero
+still renders on npmjs.com). The tarball is built output, not a checkout: it
+carries no `eval/`, `test/`, `scripts/`, or `assets/`, so a relative pointer
+into any of them is a dead end for the reader who installed the package, and
+the fix is never to ship those directories — that would undo the trim of
+[#346](https://github.com/zackbart/connecta/issues/346). A repository URL keeps
+the citation verifiable in both directions: an outside reader can follow it, and
+`check:docs` resolves it back to the checkout and fails when the cited file
+moves ([#378](https://github.com/zackbart/connecta/issues/378)). `CHANGELOG.md`
+is exempt from both gates, because release notes quote the paths that existed
+when they shipped.
+
+The Worker example ships in the tarball, its Cloudflare KV and D1 adapters
+included: it is the Workers starting template a consumer copies. That is not a
+hole in the published surface, because nothing under `examples/` appears in the
+`exports` map — every export target resolves into `dist/`, so those adapters
+are reference source rather than an importable subpath. They also clear the
+platform-specific gate above on their names (`cloudflare-kv.ts`,
+`d1-activity.ts`) rather than by exemption: that gate is a blunt pattern over
+the whole artifact, so an example file renamed into `storage/cloudflare` would
+fail the pack even though nothing about the published surface had changed.
 
 Two more runners are deliberately outside `check`:
 
@@ -221,13 +261,14 @@ justification for *not* re-running it in workerd, so "it was easier" is not one.
 | Suite | Covers | Why Node |
 | --- | --- | --- |
 | `deployment-shapes.test.ts` | the Worker as the only example, one Node template that is also its own container, the same source running locally and in the container, the full operator surface in both, a template that cannot start on its own `.env.example`, a Worker README naming every optional peer its entrypoint imports, and the initializer's `.gitignore` staying in step | walks the template and example trees with Node filesystem APIs |
-| `doc-links.test.ts` | the documentation checker itself — local file and fragment resolution, duplicate heading slugs, fenced-code exclusion, and useful failures | spawns the Node checker against filesystem fixtures |
+| `doc-links.test.ts` | the documentation checker itself — local file and fragment resolution, repository URLs resolved back to the checkout, duplicate heading slugs, fenced-code exclusion, and useful failures | spawns the Node checker against filesystem fixtures |
 | `doctor-cli.test.ts` | `connecta doctor`'s executor line end to end — the sandbox the deployment reports is the one named, an unidentifiable executor gets an executor-neutral line, and a hostile name is bounded and stripped before it reaches a terminal | spawns the CLI against a Node HTTP deployment over real sockets |
 | `drift-check.test.ts` | the maintainer drift checker — recorded touched endpoints, a quiet revision bump, clear failures for an unavailable spec/manifest/credential, `$ref` traversal, and one well-formed row per endpoint | spawns the Node checker against filesystem fixtures |
 | `file-storage.test.ts` | `fileStorage()` across instances, logical TTL plus physical pruning without clobbering a newer value, and corrupt-file quarantine | exercises the Node filesystem storage adapter |
 | `guest-api-contract-quickjs.test.ts` | the shared guest-contract cases on the real QuickJS executor | runs the contract cases on the Node QuickJS executor |
 | `node.test.ts` | the `listen()` adapter propagating an HTTP client disconnect through the Web `Request` and the MCP handler into a program's connector call, releasing both admission permits | exercises the Node HTTP adapter over real TCP sockets |
-| `package-surface.test.ts` | the published boundary — built output shipped, only generic factories, platform storage kept in examples, Clerk and QuickJS behind optional subpaths, every provider independently importable, and the Cloudflare provider free of bare specifiers | walks the package tree with Node filesystem APIs |
+| `packed-links.test.ts` | the packed-link gate itself — shipped targets and repository URLs accepted, relative links into unshipped paths and directories rejected with the citation to write instead, reference definitions seen, fenced examples ignored, the changelog exempt | spawns the Node packed-link gate against filesystem fixtures |
+| `package-surface.test.ts` | the published boundary — built output shipped, the `exports` map carrying exactly the documented subpaths plus `./package.json`, only generic factories, platform storage kept in examples, Clerk and QuickJS behind optional subpaths, every provider independently importable, and the Cloudflare provider free of bare specifiers | walks the package tree with Node filesystem APIs |
 | `purity.test.ts` | the import-graph guardrail ([architecture](./architecture.md#import-graph-purity)) — the core stays Workers-clean | walks the source import graph with Node filesystem APIs |
 | `quickjs-child-entry.test.ts` | a missing QuickJS child entry failing before `fork()`, with the expected path and the bundler-externalization constraint | mocks Node child-process and filesystem APIs |
 | `quickjs-child-stderr.test.ts` | abnormal child exits retaining only an 8 KiB stderr tail, included in the parent-side diagnostic | mocks Node child-process streams |
@@ -235,6 +276,7 @@ justification for *not* re-running it in workerd, so "it was easier" is not one.
 | `quickjs-log-limits.test.ts` | bounded `console.*` capture — per-entry cut, cumulative character and transport budgets, escape-heavy floods preserving the guest result | runs the Node QuickJS child-process executor |
 | `suite-partition.test.ts` | this partition, including itself: every `*.test.ts` in exactly one list, stale entries and empty reasons refused | walks the test directory to guard the partition |
 | `template-file-activity.test.ts` | the Node template's own activity store — persistence across restart, torn-line repair, newest-first paging, and compaction past the slack window | runs it against real files |
+| `upgrade-guide.test.ts` | the [upgrade guide](./upgrading.md)'s claims about somebody else's deployment — the generated file inventory, the seven tool names doctor demands, version boundaries that actually shipped, a bump target that is this release, and the three places a reader finds it | reads the guide, the template tree, and the CLI with Node filesystem APIs |
 | `version.test.ts` | `CONNECTA_VERSION` matching `package.json` | reads `package.json` with Node filesystem APIs |
 
 ### Outside `npm run check`

package/documentation/provider-audit.md

@@ -14,7 +14,7 @@ error, not a finding, so the proxy reports have no H rows.
 Every miss below is fixed in the same change that recorded it
 ([#342](https://github.com/zackbart/connecta/issues/342)), except where the row
 says otherwise. The mechanically checkable half of the hand-written bar is now
-a test — [`test/provider-conventions.test.ts`](../test/provider-conventions.test.ts)
+a test — [`test/provider-conventions.test.ts`](https://github.com/zackbart/connecta/blob/main/test/provider-conventions.test.ts)
 walks the shipped surface of both `api()` providers on every run, so these
 verdicts cannot rot quietly back into prose. The proxies' mechanical rows live
 in their own suites, because what they assert is the wrapper's identity,

package/documentation/provider-conventions.md

@@ -64,7 +64,9 @@ floor. From `src/catalog.ts` and `src/catalog-service.ts`:
   fallback summary for a guide with no usable body line. Routing facts belong
   in the title and the guide's first line; a routing fact that lives only in
   the connector description has been written into a field the model does not
-  read.
+  read. Neither the `id` nor the `title` is a lexical document, so a term drawn
+  from one of them is not a search hit — it is a no-match whose guidance names
+  the connector and points at a scoped browse.
 
 Two construction-time checks enforce the floor beneath all of this. The hard
 one is `api()` itself: since
@@ -108,7 +110,10 @@ write never hides behind a neutral one. Escape hatches are named
 `<provider>_api_<class>` so they sort together and read as generic.
 
 *Why:* the name is the only thing lexical search indexes besides the
-description, and it is what an agent skims first. *Cost:* wrong-tool selection.
+description, and it is what an agent skims first. A connector's `id` and
+`title` are displayed, not indexed — a search for one of them matches no tool,
+and the miss is answered by guidance naming that connector rather than by a
+ranked result. *Cost:* wrong-tool selection.
 
 ### H3 — The selection sentence fits in 160 characters; the whole description in 240
 
@@ -217,6 +222,37 @@ convenient reading. A call that can only fail is refused locally as
 `invalid_args` before the round trip. Provider error prose is never parsed to
 invent a classification.
 
+**A downstream 404 is `not_found` — when the provider means it.** The code
+exists because the next move is none of the others': you do not wait, you do
+not send the agent to `authorize_connector`, you do not repair the argument
+object. You re-address — look the id up again, or accept the absence and carry
+on — and a program looping over ids inside `execute_code` can continue past
+`not_found` where `connector_call_failed` would have to abort the run, reading
+the code off a `connecta.batch` entry's `errorDetails` rather than off a caught
+error, which the guest bridge has already stripped to prose. That
+control-flow difference is the H11 test being met; it is not a label for the
+cause.
+
+The qualifier is the whole rule. Map a status to `not_found` only where the
+provider distinguishes absence from a permission gap. Where it does not —
+Notion returns `object_not_found` both for an object that is gone and for one
+that was never shared with the integration, and will not say which — the honest
+code stays `connector_call_failed` (or `auth_required`, where a credential
+really is the fix) and the message states the ambiguity, exactly as the
+paragraph above requires. Cloudflare is the other side of the pair: a token
+that may not touch a resource is refused with 401 or 403, so its 404 is an
+absence and maps to `not_found`. Neither connector's mapping changed shape when
+the code arrived; one of them changed codes.
+
+Two boundaries. `not_found` is about a resource the *downstream* owns: an
+address connecta cannot resolve is already framed as `unknown_address` or
+`unknown_tool` and never reaches a connector. And it never appears on the
+hosted-MCP proxy path, because `P1` forbids re-shaping downstream framing and
+prose is never parsed to invent a classification — a proxied server's own
+missing-resource error arrives as that server wrote it. The two paths do not
+diverge on the rule; they diverge on who is entitled to apply it, which is the
+same split every other code already has.
+
 *Why:* a misrouted error sends an agent down a recovery path that cannot
 succeed. *Cost:* argument retries.
 
@@ -508,7 +544,7 @@ whether or not anybody noticed it arrived.
 ([#351](https://github.com/zackbart/connecta/issues/351)): a human at a laptop,
 before a release, with local credentials and the published specifications in
 front of them. It lives in
-[`scripts/drift-check.mjs`](../scripts/drift-check.mjs) and ships nowhere —
+[`scripts/drift-check.mjs`](https://github.com/zackbart/connecta/blob/main/scripts/drift-check.mjs) and ships nowhere —
 `scripts/` is outside the package, no runtime module imports it, and nothing it
 reads becomes a runtime input.
 
@@ -528,7 +564,7 @@ message naming it rather than reporting an empty catalog as mass removal.
 
 **Touched endpoints.** A hand-written provider is written against a published
 OpenAPI document and calls a few dozen of its operations, so
-[`scripts/drift/`](../scripts/drift/) commits exactly those: method, path, the
+[`scripts/drift/`](https://github.com/zackbart/connecta/tree/main/scripts/drift) commits exactly those: method, path, the
 specification revision a release reviewed the endpoint at, whether the
 operation was deprecated at that revision, and a digest of that endpoint's
 contract. `--specs` fetches each provider's published document and reports four
@@ -580,7 +616,7 @@ the reason). A convention is never quietly skipped, and an accepted miss is
 recorded as a provider-specific exception with its argument, not left blank.
 Its five reports live in [provider-audit.md](./provider-audit.md), and the
 mechanically checkable half of the hand-written bar runs on every test run in
-[`test/provider-conventions.test.ts`](../test/provider-conventions.test.ts) —
+[`test/provider-conventions.test.ts`](https://github.com/zackbart/connecta/blob/main/test/provider-conventions.test.ts) —
 so a convention that was met once stays met, or fails loudly.
 
 Hand-written providers are audited against H1–H14; hosted-MCP proxies against
@@ -620,7 +656,7 @@ beats the escape hatch — is a reading, and the audit reports it as one. The
 Cloudflare keep/prune half of that judgment was made in
 [#350](https://github.com/zackbart/connecta/issues/350): 30 keep, 18 improve,
 3 prune, measured per tool in
-[`eval/current-version/results/issue-350-evidence.md`](../eval/current-version/results/issue-350-evidence.md).
+[`eval/current-version/results/issue-350-evidence.md`](https://github.com/zackbart/connecta/blob/main/eval/current-version/results/issue-350-evidence.md).
 Its eighteen `improve` rows are H8 and H9 misses on tools that clearly earn
 their place, so they are this audit's work, not a second removal argument.