[antoinetoussaint-byte]

Refs #1211, section (d): key patterns on a bucket source. Host-side only; codefly-dev/service-object-storage#108 needs nothing for it. Based on main and independent of #1213 and #1214 (see "Merge order").

What changes

• Contract. UploadDatasourceConfig gains include_patterns and exclude_patterns. Each is at most 16 RE2 expressions of at most 256 characters, matched against the object key with the prefix removed: unanchored and case-sensitive, with ^/$ and (?i) available. Exclude wins, and an empty include admits everything. It also gains file_extensions with GitHub's semantics, intersected with the patterns. UpdateSourceRequest takes the patterns as fields 7–8 and its existing file_extensions (5), and SourceFetchScope carries the patterns too, so the expected rule covers them.
• Refused at the call, never at sync. AddSource and UpdateSource compile every pattern. An invalid one, an empty one, more than 16, or one too long is refused as INVALID_ARGUMENT with a google.rpc.BadRequest field violation and a message that leads with the field path: upload.include_patterns[1]: "(" is not a valid RE2 expression: … on add, and include_patterns[1]: … on update. That leading path is stated in the proto comment as the contract, because the TypeScript SDK carries no error-detail types.
• Applied by the connector, before any fetch. The filter is not in objectstore/client.go, the file Object-storage datasource: the contract says a client offers and flags providers by the catalog, no client reads it, and the connector that exists cannot take a new source (no cursor, no push, no admission) #1211 deletes; it is in the connector package beside it (the owner's review of 2026-10-23). objectstore.Scope (scope.go) holds the host's InScope predicate (uploadKeyScope), as the GitHub connector's SourceConfig.InScope does, together with the object cap. Window applies both to whatever listed the prefix. It drops a refused key before counting it, so an excluded object is never fetched and never uses up max_objects. client.go now returns the store's page whole, and the cap it used to apply moved into Scope with the filter. When the object-storage service replaces the client, the filter and the cap stay where they are. The closing listing is built from what was delivered, so it names only matches.
• Narrowing deletes. UpdateSource on an upload source replaces the patterns and file types and refuses branch and paths. It runs under the same lock, expected check and source.updated audit event as a GitHub edit (bucket, prefix, include_patterns and exclude_patterns are declared on the event). It then queues the source's pull sync. That sync's closing listing omits what the narrower filter excludes, and the store tombstones it.
• Access is stated. A source is (bucket, prefix, filter) → one collection → one grant. The catalog description and the connect form now say so.
• Kit version. v0.0.105 released saas-ui 0.12.15 and saas-sdk 0.3.35, so this PR moves @codefly-dev/saas-ui and @codefly-dev/ui (co-versioned) to 0.12.16 and @codefly-dev/saas-sdk to 0.3.36. These are patches, because the changes are additive. saas-ui's SDK floor rises to ^0.3.36, because the form sends fields that only that SDK carries, and the README floor sentence says why. The portal's exact SDK pin follows, as in feat(saas-ui): a person connects a generic OAuth api source through the kit #1201. package-lock.json was regenerated by npm install --package-lock-only, not edited by hand. feat(saas-ui): the datasources panel offers what the connector catalog admits and names the rest #1214 makes the same ui/saas-ui bump, so whichever lands second has nothing to add.
• Kit. ConnectObjectStorageForm takes include/exclude patterns, one per line (a comma is part of a pattern), and file types. It places a host refusal under the field it names. objectStorageInputFrom maps its values for the client's new optional addObjectStorageSource. The form and its shared CollectionField move here from feat(saas-ui): the datasources panel offers what the connector catalog admits and names the rest #1214, which keeps only the catalog read, because the form's purpose is now the key filter. Nothing mounts the form yet: the host refuses new object-storage sources until the provider is conformant, and mounting it is part of the change that admits it.

The five tests the issue requires

1. Matcher: TestUploadKeyScope covers precedence, matching relative to the prefix, case and file-type intersection. TestNormalizeKeyPatternsRefusesByName covers an invalid RE2 (including a backreference) refused with the pattern named, the count and length caps, an empty pattern, and the field in both message and BadRequest.
2. Validation: TestAddSource_UploadRefusesAnInvalidKeyFilterByField (include, exclude and file type, each by field, nothing stored) and TestUpdateSource_UploadRefusesAnInvalidKeyFilterByField (an invalid exclude and paths on a bucket source, each by field, nothing written, no audit). The add test goes through AddExistingSource, the test-only path into the same addSource validation. The AddSource RPC itself admits before it validates, by design, and refuses the provider while it is non-conformant.
3. Mixed listing on the datasource_upload_mirror_test.go seam: only matching keys are enqueued, the fetch log shows an excluded key never read, and the closing listing names exactly the matches. The source's cap is 3 against four listed keys, three of them matches, so an excluded key that counted against the cap would leave the listing incomplete. TestWindow pins the same rule at the connector: the cap counts only admitted keys, and a cut is reported.
4. Narrowing: UpdateSource with a tighter exclude queues a re-sync, and its closing listing drops exactly the newly excluded key and nothing else. A later edit against the old scope is refused as ErrDatasourceSourceScopeChanged.
5. Kit: connect-object-storage-form.test.tsx covers patterns and file types submitted intact (a pattern containing {1,3} survives), a host refusal shown under the field it names and not repeated, and an unplaced refusal kept in the form's slot.

Each guard was checked by mutation, and each mutation turned a test red: no filter passed at sync (3/4), exclude no longer winning (1/3), Window counting before matching (TestWindow and test 3), no expected check on an upload edit (4), and the kit's refusal parser not recognising fields (5).

Reuse

• Reused: GitHub's file filter and normalizeFileExtensions (the matcher sits beside them in datasource_file_filter.go), the GitHub connector's SourceConfig.InScope shape (the host builds the predicate, the connector applies it), the BadRequest refusal precedent in source_operation_invoke.go, UpdateSource's lock/expected/audit structure and its store write (the config JSONB already holds the upload config, so there is no migration), enqueuePullSync for the re-sync (it now returns the job id), and the GitHub form's collection field.
• Deliberately not: the GitHub reconcile (datasource.github.reconcile), which is the wrong engine for a pull source; and generated TypeScript error-detail types, a larger SDK change than this needs while the message carries the field.

Fix or hack

A fix at the owner: the filter is per-source host config, applied by the connector to the listing. Nothing in it is transitional. objectstore/client.go, the engine #1211 deletes, holds neither the filter nor the cap; it only lists. runUploadSync is the one call site that changes when the envelope connector replaces it, and Scope goes with it unchanged.

Generated code

Proto, Go, the frontend _pb.ts, the catalogs and the exported contracts come from CI's pinned codefly (source 5234ce24). The TypeScript SDK comes from codefly 0.1.191, the release that generated main's copy. For each tool, the no-change control on clean main came back clean first. Regenerating the SDK with CI's pin instead rewrites library.codefly.yaml's generated-by stamp on unchanged input, so I did not use it for the SDK. generate contracts --check and the module-package run-generators drift gate pass, and only the contract digests moved in module.package.codefly.yaml.

Verified

• Full accounts suite (go test -p 1 ./..., DB packages included), rerun after the move into Scope: 50 packages passed in the run, and pkg/auth/pg, whose harness failed to reach the codefly socket before any test ran, passed when rerun alone. The Scope mutations (count before filter; no InScope at sync) each turn TestWindow and test 3 red.
• The generated-pins, interface-docs, authz-coverage, naming and boundary gates.
• Kit: tsc, ESLint and its 350 tests. Portal: tsc, the type-primitive and inventory gates, and the full pure project (4,893 tests in 345 files).
• kit-version.mjs check passes on this branch merged into current main, which contains the v0.0.105 tag. My earlier "rides main's unreleased versions" was checked against a base that predated that tag, and CI's red on "Frontend kit version" / "Release gates" was that.

Not verified

• Live under codefly run. Admission refuses new object-storage sources and the dev fixture seeds none, so no source exists to filter. The behaviour is proven on the sync seam and the service tests only.
• The real Postgres round trip of the patterns in the config JSONB. It goes through the existing datasourceConfigJSON/scan of the struct, and I did not add a DB test for it.
• RE2 dialect parity in the browser. The kit checks only count and length, and the host is authoritative.

Size

About 875 net non-test lines against the merge base, counting docs, the 73-line proto change and the version bumps, and excluding generated files, the lockfile and ui-inventory.json. About 330 of those are the object-storage form and collection field moved here from #1214, so this PR's own work is about 545. Tests add about 500. Moving the filter into the connector added about 30 lines net: scope.go (50) against the cap and match it took out of client.go. That is just over the ~500 budget. I kept the kit test with the PR that needs it rather than split it off.

Merge order

This PR and #1214 add kit lines at the same anchors (a client call, a hook, the export lists, the README hooks line). Whichever lands second needs a trivial rebase. #1213 is independent of this PR, and the two touch disjoint files in objectstore. Whichever of them lands second gives #1213's FilesConnector this Scope in its SourceConfig, applied in Changes before the listing is digested. That is a few lines of wiring, and the filter itself does not move.

Docs

module/services/accounts/AGENTS.md gains "An object-storage source is a prefix and a key filter", which says the connector's Scope applies the filter, not the listing source. The kit README gains the form, objectStorageInputFrom and useAddObjectStorageSource. The proto comments state the semantics and the refusal shape.

🤖 Generated with Claude Code

[antoinetoussaint-byte]

Closing as finished work with no remaining home: #1235 contains this branch's head commit outright.

315dd360 (#1235's head) begins with 413084a9 (#1213's head) and 4762aa8d (#1216's head), followed by 264f6d69 Merge remote-tracking branch 'origin/issue-1211-bucket-key-patterns'. GitHub's compare confirms it: 4762aa8d...315dd360 is behind_by=0, status=ahead, i.e. nothing here is missing from there.

So this needs no rebase and no review. Rebasing it onto main — it is 22 commits behind — would re-run a full strict-main CI cycle on commits that already sit in a newer, green PR. #1235 is the one self-contained PR for issue #1211 and is where the review is happening.

Reopen if that compare ever stops being true.

🤖 Generated with Claude Code