@jskit-ai/connectors-catalog 0.1.1

package/docs/aws-athena.md

@@ -0,0 +1,150 @@
+# AWS Athena
+
+Import `awsAthenaProvider` from
+`@jskit-ai/connectors-catalog/server/aws-athena`. Use the same connection service,
+Feature, file storage and shared configuration form as other API-key providers.
+The fragment executes Athena SQL operations through the official AWS SDK.
+
+## Portable configuration
+
+```json
+{
+  "schemaVersion": 1,
+  "registrations": {},
+  "integrations": {
+    "queries": {
+      "provider": "aws-athena",
+      "accountMode": "shared",
+      "scopes": [],
+      "authentication": {
+        "method": "api-key",
+        "secretRef": "env:AWS_SECRET_ACCESS_KEY"
+      },
+      "settings": {
+        "region": "ap-southeast-2",
+        "accessKeyIdRef": "env:AWS_ACCESS_KEY_ID",
+        "workgroup": "reports",
+        "resultLocation": "s3://query-results/reports/"
+      }
+    }
+  }
+}
+```
+
+`workgroup` defaults to `primary`. Omit `resultLocation` when the workgroup
+supplies result storage. Enforced workgroup configuration takes precedence over
+client result settings, as documented in
+[Override client-side settings](https://docs.aws.amazon.com/athena/latest/ug/workgroups-settings-override.html).
+Temporary credentials also need `settings.sessionTokenRef`. `assistant`
+ownership is supported; application users still share the configured AWS identity.
+
+## Administrator setup
+
+1. In the Athena console, select the intended AWS account and region.
+2. Open **Workgroups** in the navigation pane. Select an existing SQL workgroup or
+   choose **Create workgroup**, enter its name, and select the Athena SQL engine and **AWS Identity and Access Management (IAM)** authentication.
+3. Configure result storage for that workgroup. For S3-backed results, select a
+   bucket/prefix with the intended encryption and ownership. Set a per-query
+   data scan limit; choose **Override client-side settings** if the workgroup
+   must enforce those settings. Choose **Create workgroup** or save your edits.
+4. Give the backend identity `athena:GetWorkGroup`, `StartQueryExecution`,
+   `GetQueryExecution`, `GetQueryResults` and `StopQueryExecution` on the intended
+   workgroup. Grant only the required source data, catalog, result storage and
+   encryption access. Permissions depend on the actual query's data sources.
+5. Follow [AWS credential setup](aws-credentials.md), enter the references,
+   region and workgroup in Vibe64 or the JSON file, and save.
+6. In the editor, use **Set credential in Env** for each saved reference and enter
+   its value, then return and choose **Connect account**. CLI callers resolve the
+   same references from their private environment and call `connectApiKey`.
+   Temporary credentials require all three values to be renewed together.
+   The connection check reads workgroup metadata; it does
+   not run a query, verify table access or prove result-bucket permissions.
+
+Console configuration follows [Create a workgroup](https://docs.aws.amazon.com/athena/latest/ug/creating-workgroups.html).
+An authorized AI can automate workgroup creation with
+[CreateWorkGroup](https://docs.aws.amazon.com/athena/latest/APIReference/API_CreateWorkGroup.html)
+and separately configure IAM, Glue/S3 resources and encryption. It cannot grant
+itself account access. Neither provisioning nor credential renewal is part of
+this fragment.
+
+For Online and public operation there is **no OAuth callback URL** in this
+mode. See [AWS ownership and quota isolation](aws-credentials.md#online-public-editor-and-independent-cli).
+Separate workgroups do not isolate account service quotas. The application
+operator supplies AWS credentials, chooses resources and controls their budget.
+The same application-owned setup works from CLI or editor without a Vibe64
+managed service.
+
+## Runtime contract
+
+| Operation | Inputs | Result |
+|---|---|---|
+| `workgroup.get` | None | Configured workgroup metadata, including enabled/disabled state |
+| `catalogs.list` | Optional `maxResults` 2–50 (default 50), opaque `nextToken` | Catalog summaries |
+| `databases.list` | `catalog`; optional `maxResults` 1–50, `nextToken` | Database names and metadata |
+| `tables.list` | `catalog`, `database`; optional `maxResults` 1–50, `nextToken` | Table metadata, columns and partition-key types |
+| `query.start` | `sql`, `clientRequestToken` (32–128 chars); optional `database`, `catalog` | `QueryExecutionId` |
+| `query.status` | `queryId` | Query execution, status, statistics and result configuration |
+| `query.results` | `queryId`; optional `maxResults` 1–1000 (default 100), opaque `nextToken` | One DATA_ROWS result page |
+| `query.cancel` | `queryId` | Empty success receipt after StopQueryExecution |
+
+Query statements are not restricted to SELECT. The host's authorization policy
+must approve the exact SQL and bound data access before invocation. SQL is
+preserved, limited to 262144 UTF-8 bytes and never submitted during connection.
+A client request token must identify one application-authorized logical query;
+reuse the same token and input when resolving an uncertain submission. The SDK
+is configured for one attempt; there is no automatic query replay. AWS describes
+token reuse in [StartQueryExecution](https://docs.aws.amazon.com/athena/latest/APIReference/API_StartQueryExecution.html).
+
+Status, results and cancellation first fetch the execution and reject a query
+outside the configured workgroup. This does not isolate users within a shared
+workgroup. The host must maintain query ownership and authorize each `queryId`.
+The fragment returns queued, running, succeeded, failed and cancelled states;
+it does not poll, schedule or invent completion. See
+[GetQueryExecution](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetQueryExecution.html).
+
+Results preserve column metadata, header rows, empty cells and string values.
+Do not coerce large numbers or silently drop the first row. Follow `NextToken`
+explicitly; one page is not the full result. S3-backed results require S3 access
+as well as Athena permissions. See
+[GetQueryResults](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetQueryResults.html).
+
+Cancelling the local HTTP call or disconnecting does not stop an AWS query.
+`query.cancel` explicitly requests
+[StopQueryExecution](https://docs.aws.amazon.com/athena/latest/APIReference/API_StopQueryExecution.html);
+read status afterwards if final cancellation must be confirmed. Catalog
+provisioning, prepared statements, execution parameters, Spark, identity-center
+federation and result manifest operations are outside this fragment.
+
+Local tests exercise real SDK serialization/signing against controlled HTTP,
+file restart, permission boundaries, job states and cancellation. No live SQL,
+AWS account provisioning or generated application is used.
+
+
+## Catalog browsing
+
+Use `catalogs.list`, then `databases.list` for the selected catalog and
+`tables.list` for its selected database. Each operation returns one native AWS
+page; pass `NextToken` unchanged to continue. Column types remain provider
+strings, including decimal precision and nested types. These calls do not run SQL.
+
+The configured workgroup is sent on each request, but does not restrict which
+catalogs are visible to that IAM identity. Authorize the exact catalog/database
+and returned metadata in the application, separately from query ownership.
+Grant `athena:ListDataCatalogs`, `athena:ListDatabases` and
+`athena:ListTableMetadata` as needed. Glue-backed catalogs also require the
+appropriate `glue:GetDatabase`, `glue:GetDatabases`, `glue:GetTable` and
+`glue:GetTables` resource grants. Do not broaden them automatically after denial.
+
+```js
+const databases = await service.invoke({ context, integrationId: "queries",
+  operation: "databases.list", input: { catalog: authorizedCatalog } });
+const tables = await service.invoke({ context, integrationId: "queries",
+  operation: "tables.list",
+  input: { catalog: authorizedCatalog, database: authorizedDatabase } });
+```
+
+Native implementations in other frameworks use AWS
+[ListDataCatalogs](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListDataCatalogs.html),
+[ListDatabases](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListDatabases.html)
+and [ListTableMetadata](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListTableMetadata.html)
+with the same project credential bindings and application authorization.

package/docs/aws-credentials.md

@@ -0,0 +1,75 @@
+# AWS credentials and ownership
+
+S3 and Athena use AWS Signature Version 4, implemented by the official AWS SDK.
+The shared runtime resolves explicit credential references for each operation.
+It never falls back to environment names, AWS profiles, instance metadata or the
+machine operator's account. CLI and Vibe64 use the same configuration and file
+connection store. This is useful library code; provisioning remains host work.
+
+## Create or obtain credentials
+
+Prefer temporary role credentials. An administrator supplies a role with the
+resource permissions listed in the provider guide; an authorized host can use
+[STS AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)
+to obtain access key ID, secret access key and session token. Trust policies,
+external IDs for third-party access, MFA requirements and expiration belong to
+that setup. This fragment accepts the resulting three bindings; it does not
+assume roles or refresh STS credentials itself. The resolver must return a
+consistent credential set and renew it before expiration.
+
+For a deliberately selected IAM-user key:
+
+1. Sign into the AWS console as that IAM user, in the intended account.
+2. Open your account menu at the top right, then **Security credentials**.
+3. Under **Access keys**, choose **Create access key**. Review the alternatives.
+4. If a long-lived key is appropriate, select **Other**, then **Next**.
+5. Add a description identifying this application and environment. Choose
+   **Create access key**.
+6. On **Retrieve access keys**, save the ID and secret into the backend's secret
+   environment. AWS reveals the secret only at creation. Choose **Done**.
+7. Put references such as `env:AWS_ACCESS_KEY_ID` and
+   `env:AWS_SECRET_ACCESS_KEY` in the integration configuration. Leave the
+   optional session-token reference absent for long-lived IAM-user keys.
+
+These are AWS's [documented console steps](https://docs.aws.amazon.com/IAM/latest/UserGuide/access-key-self-managed.html).
+Use an IAM identity restricted to the intended resources, not an account root key.
+Account enrollment, billing and administrator access are prerequisites; adding
+an integration does not create an AWS account or confer administrator rights.
+
+## Online, public editor and independent CLI
+
+There is **no OAuth registration, redirect URI or universal callback URL** for
+these credential modes. The app's VPS and custom domain do not change the AWS
+account, region or identity. Browser S3 access can require a CORS update when the
+app changes domain; server-side Athena calls do not use browser CORS.
+
+The application owner supplies the AWS identity and resource set. CLI and editor
+configuration use the same application-owned Env bindings. Hosted and installed
+editors do not supply shared AWS credentials. Two access keys or roles in one
+account do not create separate quota pools.
+
+After saving the configuration, Vibe64 provides a **Set credential in Env**
+link for the access key ID, secret access key and any configured session token.
+Each link opens that project's Env screen with the referenced variable name.
+Only references are saved in the integration file. Clearing the optional token
+reference removes its shortcut; it does not delete the existing Env value.
+
+AWS's [Athena quota documentation](https://docs.aws.amazon.com/athena/latest/ug/service-limits.html)
+explicitly shares service quotas across an account's workgroups. Separate
+workgroups are useful for policies and query limits; they do not isolate account
+capacity. Account and role provisioning are operator responsibilities, separate
+from these runtime adapters.
+
+## Can an AI automate setup?
+
+With explicitly authorized administrative credentials, an AI can compose and
+apply resource policies, create service resources, and call
+[CreateAccessKey](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateAccessKey.html)
+for an existing IAM user. Secret output must be captured directly into the
+chosen secret store. Resource creation and policy changes are separate from
+runtime verification; these adapters never perform them on Connect.
+
+An AI cannot bootstrap trust or permissions that the owner has not granted.
+The current package includes guidance and runtime operations, not an automated
+AWS account factory, IAM policy deployment or STS renewal service. Follow the
+[S3](aws-s3.md) or [Athena](aws-athena.md) setup for the actual resources.

package/docs/aws-s3.md

@@ -0,0 +1,193 @@
+# AWS S3
+
+Import `awsS3Provider` from `@jskit-ai/connectors-catalog/server/aws-s3` and use
+`createConnectionService` or the ordinary JSKIT connector Feature. The shared
+catalogue definition drives Vibe64's form. Runtime state can use encrypted JSON
+files; no database or generated application is required.
+
+## Portable configuration
+
+```json
+{
+  "schemaVersion": 1,
+  "registrations": {},
+  "integrations": {
+    "files": {
+      "provider": "aws-s3",
+      "displayName": "Application files",
+      "accountMode": "shared",
+      "scopes": ["read"],
+      "authentication": {
+        "method": "api-key",
+        "secretRef": "env:AWS_SECRET_ACCESS_KEY"
+      },
+      "settings": {
+        "region": "ap-southeast-2",
+        "bucket": "my-app-files",
+        "accessKeyIdRef": "env:AWS_ACCESS_KEY_ID"
+      }
+    }
+  }
+}
+```
+
+Optional `settings.sessionTokenRef` binds temporary credentials. The form
+initially selects read and write, matching the captured two-permission setup;
+remove write for a reader. Read access is mandatory: the configuration validator
+rejects its absence and the editor keeps that checkbox selected and disabled.
+These are local operation limits, not an IAM grant.
+The returned `grantedScopes` remains empty because AWS did not issue OAuth
+consent. `assistant` ownership is also supported; neither mode represents a
+separate AWS account for each end user.
+
+## Administrator setup
+
+1. Open **Amazon S3 > General purpose buckets** in the intended AWS account.
+   Select an existing bucket, or choose **Create bucket**, select the region,
+   supply a valid unique bucket name and create it. Retain blocked public access
+   and disabled ACLs unless your application specifically requires otherwise.
+2. Copy the bucket name and its region into the form. This fragment supports the
+   18 regions listed by its shared definition, using the commercial AWS
+   partition and general purpose buckets in the shared global namespace.
+3. Give the backend identity `s3:ListBucket` on the bucket ARN and
+   `s3:GetObject` on the permitted object ARNs. Add `s3:PutObject` only for uploads.
+   Encryption or cross-account policies can require additional permissions.
+4. Follow [AWS credential setup](aws-credentials.md). Store references in the
+   form, save the file, then let the runtime call `connectApiKey`.
+5. For browser fetches or uploads, open the bucket's **Permissions** tab. Under
+   **Cross-origin resource sharing (CORS)** choose **Edit**, add the app's exact
+   origins and needed methods/headers, then **Save changes**. Add a verified
+   custom-domain origin when it becomes active. CORS does not grant object access.
+
+For the native Fetch example, this is a starting CORS document. Replace the
+illustrative origin with the application's real HTTPS origin, without a path
+or trailing slash. Remove PUT for a download-only app. Preserve any existing
+rules required by other applications using the bucket.
+
+```json
+[
+  {
+    "AllowedOrigins": ["https://your-app.example.com"],
+    "AllowedMethods": ["GET", "PUT"],
+    "AllowedHeaders": ["Content-Type"],
+    "ExposeHeaders": ["ETag"],
+    "MaxAgeSeconds": 300
+  }
+]
+```
+
+If your upload code adds checksum or other request headers, list those headers
+too. A server-side transfer does not require browser CORS. Keep the AWS keys on
+the server; the browser receives only the URL for its authorized object.
+
+The [bucket API guide](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html)
+explains bucket types, regions and public-access settings. Browser setup follows
+[AWS's CORS instructions](https://docs.aws.amazon.com/AmazonS3/latest/userguide/enabling-cors-examples.html).
+An authorized AI can use CreateBucket, IAM policies and
+[PutBucketCors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketCors.html)
+to perform these administrative steps. Provisioning is not an adapter operation.
+For application-owned credentials, quota boundaries and the absence of a callback URL,
+see [AWS ownership](aws-credentials.md#online-public-editor-and-independent-cli).
+
+## Runtime operations
+
+| Operation | Inputs | Behavior |
+|---|---|---|
+| `objects.list` | Optional `maxKeys` 1–1000 (default 100), `prefix`, delimiter `/`, opaque `continuationToken` | One ListObjectsV2 page in the configured bucket; also the connection check |
+| `objects.downloadUrl` | Exact `key`; optional `expiresInSeconds` 1–900 (default 300) | Returns `{url, method: "GET", expiresInSeconds}` |
+| `objects.uploadUrl` | Same fields; requires local `write` permission | Returns `{url, method: "PUT", expiresInSeconds}` |
+
+Listing preserves AWS's response shape and uses `EncodingType: "url"`.
+Decode the listed `Contents[].Key` and `CommonPrefixes[].Prefix` with
+`decodeURIComponent` once before displaying or passing a key to a URL operation;
+do not decode opaque continuation tokens. Empty pages are valid; continue using
+`NextContinuationToken` when `IsTruncated` is true. See
+[ListObjectsV2](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html).
+
+Keys preserve spaces, Unicode, plus signs and literal percent signs. Keys over
+1024 UTF-8 bytes, and standalone `.` or `..` path segments, are rejected to avoid
+URL normalization changing object identity. These are deliberate fragment bounds
+based on [AWS key behavior](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html).
+No directory buckets, access-point ARNs, alternate endpoints, multipart uploads,
+version selection, delete, ACL or encryption-header operations are implemented.
+
+Presigning is local. It does not prove that an object exists, a transfer
+succeeded or IAM permits it. Use the returned method and unmodified URL without
+an Authorization header. PUT sends the file body and can overwrite that key.
+URLs are bearer credentials, reusable until effective expiration; temporary
+credentials can expire first. Do not log them or put them in public source.
+Local disconnect prevents future use through the service but cannot revoke an
+already issued URL. See [presigned URL behavior](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html).
+
+The host must authorize the exact key/prefix before invocation. A shared bucket
+connection alone does not isolate application users. SDK calls use one attempt,
+explicit credentials and a fixed regional origin; wrong-region responses and
+expired credentials remain observable. Local tests use controlled HTTP with
+real SDK signing and encrypted file persistence. They do not access a live bucket
+or transfer files through issued URLs.
+
+## Application-owned file transfers
+
+The tested [transfer example](../patterns/aws-storage-queries/example/s3-transfer.js)
+composes the existing connection service with native Fetch. Copy it into an
+application server module or CLI; it needs no Vibe64 process. Supply the same
+authorized context and integration ID used by the service, an exact permitted
+key, and a timeout/cancellation signal. The upload body is a Blob, ArrayBuffer
+or typed array. Downloads return a Response whose body can be streamed to a file
+or a format reader. Await body consumption before reporting completion.
+
+```js
+const response = await transferS3Object({ service, context,
+  integrationId: "files", key: authorizedKey, direction: "download",
+  signal: AbortSignal.timeout(60_000) });
+// For a bounded JSON document; validate its schema in your application.
+const document = await response.json();
+```
+
+For CSV and Parquet, preserve the response bytes and use the application's
+selected CSV/Parquet reader; S3 does not interpret these formats. The
+[native format example](../patterns/aws-storage-queries/example/formats/data-formats.js)
+implements JSON, CSV and Parquet encoding/decoding through native libraries.
+Its separate package manifest and lockfile are illustrative application
+dependencies, not dependencies of the connector runtime.
+
+Copy the `example/formats` directory to an isolated working directory, run
+`npm ci --ignore-scripts`, then `npm test`. This exercises only the format
+libraries; it does not generate or launch an application or contact AWS.
+An existing application can instead install the listed libraries using its
+normal dependency workflow and adapt `data-formats.js` into its own server code.
+
+```js
+const encoded = encodeDataFile("csv", [
+  ["id", "description"], ["001", "A description, with punctuation"]
+]);
+await transferS3Object({ service, context, integrationId: "files",
+  key: authorizedKey, direction: "upload", body: encoded,
+  signal: AbortSignal.timeout(60_000) });
+const downloaded = await transferS3Object({ service, context,
+  integrationId: "files", key: authorizedKey, direction: "download",
+  signal: AbortSignal.timeout(60_000) });
+const rows = await decodeDataFile("csv", new Uint8Array(await downloaded.arrayBuffer()));
+```
+
+CSV preserves row arrays, quoting, newlines and leading zeroes; the application
+decides which row is the header and validates its business schema. Parquet
+encoding accepts explicit native `{name, type, data}` columns; decoding returns
+row objects. The example uses in-memory parsing with an 8 MiB input limit.
+That limit is checked after download and is not a network-transfer or decompressed
+memory limit. Large or untrusted datasets need the application's bounded stream,
+row/column selection and resource policy. Other Parquet codecs and schemas should
+use the native reader's documented options rather than a new connector API.
+
+The example refuses redirects, omits cookies, sends no Authorization header,
+and does not retry transfers. A failed PUT connection can mean an unknown
+outcome: inspect the intended object before deciding to repeat the upload.
+HTTP failures remain failures even when URL signing succeeded. A stream can
+also fail after receiving successful response headers. Follow the provider's
+[upload instructions](https://docs.aws.amazon.com/AmazonS3/latest/userguide/PresignedUrlUploadObject.html)
+when using a URL in another framework or a browser.
+
+Controlled tests exercise real SDK signing followed by fixture GET/PUT
+transfers, binary chunk consumption, transfer errors and denied authorization.
+Separate format checks exercise JSON, quoted CSV and typed nullable Parquet
+content with the real libraries. Neither suite establishes live AWS interoperability.

package/docs/bigquery.md

@@ -0,0 +1,146 @@
+# BigQuery
+
+Import `bigqueryProvider` from `@jskit-ai/connectors-catalog/server/bigquery`.
+**Existing-scope delivery: delegated OAuth only.** Federation is not implemented. Query
+submission and results use the configured project. The project-list connection
+check does not establish job or dataset permissions.
+
+This fragment lists projects and datasets, reads table metadata, submits GoogleSQL queries and retrieves results
+using delegated Google OAuth. The generated application owns these operations.
+
+## Registration and manual setup
+
+1. Follow the numbered [Google OAuth setup](google-oauth.md) to choose/create
+   the Cloud project and configure branding, audience and test users.
+2. In **APIs & Services → Library**, enable **BigQuery API**
+   (`bigquery.googleapis.com`). Create a Web application OAuth client with the
+   exact callback URI served by the backend.
+3. In **Data Access**, add
+   `https://www.googleapis.com/auth/bigquery`. Store client secret and
+   callback URL in Env, then save their references and client ID in the shared
+   registration. Choose provider `bigquery` and the OAuth registration reference.
+4. Enter **Google Cloud project ID**: the project intended to run and pay for
+   queries. It may differ from the dataset project. This is saved as
+   `settings.projectId`; it is not an OAuth registration or secret.
+5. Connect the Google account that should read project metadata. Project IAM
+   access is separate from OAuth consent; the list filters to enabled projects
+   on which the caller has an applicable project-level role.
+   [Project-list requirements](https://docs.cloud.google.com/bigquery/docs/reference/rest/v2/projects/list).
+
+## Runtime and AI composition
+
+`projects.list` calls `GET https://bigquery.googleapis.com/bigquery/v2/projects`.
+It accepts `maxResults` (1–50, default 50 in this fragment) and optional
+`pageToken`. Keep following `nextPageToken` even if a page is shorter than
+requested: server filtering can shorten pages. Results retain `totalItems`
+and project references; `projects` may be absent when `totalItems` is zero.
+[Endpoint](https://docs.cloud.google.com/bigquery/docs/reference/rest/v2/projects/list).
+
+The form also exposes broader documented scopes, including Cloud read-only
+and full access. Query operations require `bigquery` or `cloud-platform`. Compose
+the [connection pattern](../patterns/api-key-connection/PATTERN.md) with the
+file store and OAuth `beginAuthorization` / `completeAuthorization`; verification
+input is empty. The application owns callback routing and access policy.
+Service-account keys, ADC and workload identity are separate authentication
+options, not implemented by this delegated-OAuth fragment.
+[Authentication options](https://docs.cloud.google.com/bigquery/docs/authentication).
+
+`jobs.query` submits GoogleSQL to `settings.projectId`. Input includes `query`,
+optional `location`, `maximumBytesBilled` and `requestId`; `maxResults` defaults
+to 100 (maximum 1000), and `timeoutMs` to 1000 (maximum 10000). This operation
+can incur charges and perform writes permitted by IAM. The application's
+backend must authorize its use and supply trusted SQL; never concatenate user
+input into SQL. Pass up to 100 named scalar `parameters`, each with `name`,
+`type` and a string `value`. For example, SQL `SELECT @name` takes
+`parameters: [{ name: "name", type: "STRING", value: userInput }]`.
+Values are sent separately from SQL using Google's named parameter format.
+Array, struct and null parameters are not currently supported.
+[Parameterized queries](https://docs.cloud.google.com/bigquery/docs/parameterized-queries).
+
+If `jobComplete` is false, call `jobs.getQueryResults` with the returned `jobId`
+and location. Pass `pageToken` for subsequent pages. Both operations use the
+configured project; callers cannot override it. Results remain provider-shaped,
+including warnings/errors for application handling. SQL and query-result page
+tokens preserve whitespace. Rows retain native cells, nested records/repeated
+values, nulls and decimal/large-integer strings; do not coerce them to JavaScript
+numbers. Structural response validation rejects malformed row containers. There is no automatic retry
+or polling, dry-run operation, or job ownership registry here.
+The application must restrict job access within its own authorization policy.
+[Query API](https://docs.cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query),
+[result API](https://docs.cloud.google.com/bigquery/docs/reference/rest/v2/jobs/getQueryResults).
+
+## Dataset, table and job operations
+
+All operations below use `settings.projectId`; operation inputs cannot override
+it. Use another project-owned configuration slot for metadata in another project.
+Discovery requires the corresponding dataset/table IAM access independently of
+OAuth consent. Neither discovery nor connection verification submits SQL.
+
+| Operation | Inputs | Returned data |
+|---|---|---|
+| `datasets.list` | Optional `maxResults` 1–1000 (default 100), `pageToken` | Native dataset page |
+| `tables.list` | `datasetId`; optional `maxResults`, `pageToken` | Native table page |
+| `tables.get` | `datasetId`, `tableId` | Table metadata and schema, not table rows |
+| `jobs.get` | `jobId`; optional `location` | Job status, statistics and error details |
+| `jobs.cancel` | `jobId`; optional `location` | Cancellation response containing job metadata |
+
+Metadata listing preserves references and opaque pagination tokens. Empty lists
+can omit their collection field. Table schemas retain provider field types and
+nested structure. Use query results to obtain data; fetching table metadata does
+not fetch its rows. Native framework consumers can use the same
+[datasets.list](https://docs.cloud.google.com/bigquery/docs/reference/rest/v2/datasets/list),
+[tables.list](https://docs.cloud.google.com/bigquery/docs/reference/rest/v2/tables/list)
+and [tables.get](https://docs.cloud.google.com/bigquery/docs/reference/rest/v2/tables/get)
+methods with their own Google libraries.
+
+The application must authorize each job ID before inspection or cancellation.
+Retain its region and use it when calling these operations. `jobs.get` preserves
+PENDING, RUNNING and DONE, including `status.errorResult`: DONE does not mean
+success. Job metadata can contain SQL and errors, so do not expose it to other
+users. See [jobs.get](https://docs.cloud.google.com/bigquery/docs/reference/rest/v2/jobs/get).
+
+`jobs.cancel` requests cancellation; it does not prove the job stopped or that
+charges were avoided. Inspect status afterwards. A local abort/disconnect does
+not cancel the remote job. The cancellation request is not automatically retried.
+See [jobs.cancel](https://docs.cloud.google.com/bigquery/docs/reference/rest/v2/jobs/cancel).
+
+## Federation ownership — not implemented yet
+
+Federation needs a trusted external identity as well as a workload identity
+provider audience and a service-account email. Those two settings alone cannot
+produce credentials. The generated application's deployment must supply the
+identity; an editor login, project URL or OAuth client ID is not that identity.
+
+For a deployment with an OIDC issuer, its operator configures a Google workload
+identity pool/provider, grants that identity permission to impersonate the
+service account, and generates Google's external-account credential
+configuration. The Node application can use Google's authentication library;
+other frameworks use their supported Google authentication tools. File-sourced
+OIDC tokens require the deployment to update the token file before expiration.
+[Google authentication library federation setup](https://github.com/googleapis/google-auth-library-nodejs#workload-identity-federation).
+
+Vibe64 should edit the application configuration and Env references. It must
+not issue deployment identities or require an exported application to call a
+Vibe64 token gateway. The runtime implementation still needs to define and
+validate its credential-source input and prove exchange and renewal before this
+mode can be offered as working.
+
+## Automation and application ownership
+
+An authorized AI can prepare configuration, enable the API and assist with IAM
+using existing Google administration APIs or gcloud. Web-client registration,
+branding/review and account consent follow the common console guide.
+The application owner supplies its OAuth registration and data-project access.
+Separate OAuth projects do not automatically separate compute billing or resource
+limits. Query submission uses the configured billing/execution project.
+
+Automated tests cover consent, scopes, replay, private-file restart, isolation,
+pagination, empty pages and provider failures without live queries or projects.
+
+## Existing-scope closeout — 13 September 2026
+
+Project-owned delegated Google OAuth supports project/dataset/table discovery, table metadata, named scalar GoogleSQL parameters, query submission, job status, result pagination and cancellation in the configured execution project.
+
+No service-account key, ADC, workload-identity federation or deployment identity issuance. No array/struct/null parameters, automatic retry/polling/pagination, dry-run operation, load/extract/copy/streaming jobs, dedicated dataset/table administration or cross-project input override. SQL may incur charges and perform IAM-permitted writes; maximumBytesBilled is optional, not an account budget. Connection checking lists projects and does not prove query/dataset permissions. The app owns SQL authorization, per-user job ownership, result rendering, billing choices and cancellation follow-up; DONE or a cancellation acknowledgement does not prove successful execution/stopping. To extend: implement deployment-owned federation and its renewal/tests, then only required job/parameter modes. No Vibe64 identity gateway. No live provider account, provider registration, paid request or generated-application execution was tested. No new editor coding-assistant tool attachment is claimed. Other frameworks use the same project configuration and their own native tools; JSKIT is optional.
+
+9 source and 9 installed-package BigQuery checks passed on September 13. September 12 compact/expanded configuration, IAM guidance and lifecycle browser evidence is retained; no new UI run.