fix: harden options and publication contracts

Author: tensornull

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -12,7 +12,8 @@ body:
     id: version
     attributes:
       label: CometAPI SDK version
-      placeholder: 0.1.0-alpha.1
+      description: Run `npm list cometapi` and report the installed package version.
+      placeholder: Paste the installed package version
     validations:
       required: true
   - type: input

AGENTS.md

@@ -51,14 +51,15 @@ repository.
   merely to complete lifecycle cleanup. Fail closed and report the exact state
   whenever a required cleanliness, fetch, or fast-forward condition is not met.
 
-## Current Milestone: Stable 0.1.1 and Repository Foundation Complete
+## Current Milestone: Stable 0.1.x Maintenance
 
-Private Remote Validation, Public Preview, Registry Alpha, stable `0.1.0`, and
-the `0.1.1` maintenance patch are complete. The canonical repository is public,
-`0.1.1` is available from npm's `latest` channel, and `0.1.0-alpha.3` remains
-available from `next`; the published lines have verified provenance and
-public-install evidence. No later milestone is active. Do not begin the 0.2
-provider adapters without an explicit maintainer request.
+Private Remote Validation, Public Preview, Registry Alpha, and Repository
+foundation are complete. The canonical repository is public and remains in
+stable 0.1.x maintenance: stable packages use npm's `latest` channel and
+Registry Alpha artifacts use `next`. Do not pin an exact current package or
+Release version in durable repository guidance. Query npm and GitHub when exact
+state matters. No later milestone is active; do not begin the 0.2 provider
+adapters without an explicit maintainer request.
 
 The accepted identity is:
 
@@ -78,21 +79,23 @@ The unscoped `cometapi` package is the primary Node SDK. `@cometapi` is the
 standard scope for future official scoped packages; do not introduce new
 official packages under `@cometapi-dev`.
 
-Stable `0.1.1` corrected the public options boundary without expanding the 0.1
-resource surface. Release Please created the reviewed patch PR, immutable tag,
-and GitHub Release. Publication required a disclosed one-time main-context
-recovery because the immutable tag predated the repaired tag handoff. The
-recovery published only the exact previously verified artifact through npm
-OIDC, then the repository restored its variables and tag-only Environment
-policy. The current workflow contains no publication-recovery input, fixed
-recovery run or artifact ID, prior-package-artifact or live-evidence reuse, or
-branch-context publication path.
+Stable `0.1.1` established the runtime options boundary and repaired the release
+path without expanding the 0.1 resource surface. Release Please created the
+reviewed patch PR, immutable tag, and GitHub Release. Publication required a
+disclosed one-time main-context recovery because the immutable tag predated the
+repaired tag handoff. The recovery published only the exact previously verified
+artifact through npm OIDC, then the repository restored its variables and
+tag-only Environment policy. The current workflow contains no
+publication-recovery input, fixed recovery run or artifact ID,
+prior-package-artifact or live-evidence reuse, or branch-context publication
+path.
 
 Release Please remains disabled between explicitly authorized release
 operations. Permanent stable patches follow only the tag-bound path in
-`RELEASING.md`. The `0.1.1` recovery provenance is historical evidence, not
-proof that the current permanent tag path has completed a registry publication;
-the next explicitly authorized stable patch is its first end-to-end execution.
+`RELEASING.md`. The recovery provenance for stable `0.1.1` is historical
+evidence and does not prove an execution of the permanent path. The next
+explicitly authorized stable patch is that path's first end-to-end registry
+execution.
 
 ## Product Contract
 
@@ -125,6 +128,11 @@ message translation are not 0.1 features.
   Do not hand-write replacements for those layers.
 - Use only documented public OpenAI constructor and client options. Do not
   depend on private upstream attributes or methods.
+- Declare CometAPI-owned `provider`, `workloadIdentity`, and
+  `dangerouslyAllowBrowser` fields as optional `never` properties on
+  `CometAPIOptions`. The constructor and `withOptions` must reject every
+  non-`undefined` value at runtime as well as through TypeScript variables,
+  spreads, and constrained generics.
 - Preserve official OpenAI request, response, stream, and exception types for
   the supported 0.1 operations.
 - Keep CometAPI-specific resources in `src/resources/` and their types in
@@ -243,6 +251,10 @@ repository root.
 - Inspect `npm pack` output, install the exact tarball in clean ESM, CommonJS,
   and compatible-OpenAI host fixtures, and verify version agreement before
   publication.
+- Treat `package.json` as the sole candidate-version authority. A normal stable
+  Release Please PR changes exactly `.release-please-manifest.json`,
+  `CHANGELOG.md`, `package-lock.json`, and `package.json`; all four version
+  records must agree, while durable documentation remains publication-neutral.
 - Keep development checks compatible with unresolved maintainer input, but
   make the publish workflow fail closed until maintainers have supplied the
   copyright holder, canonical security and support contacts, repository

ARCHITECTURE.md

@@ -29,14 +29,16 @@ only for CometAPI defaults and public branding:
 3. The default base URL is `https://api.cometapi.com/v1`.
 4. Other documented and supported OpenAI client options pass through unchanged.
 
-The public `CometAPIOptions` type excludes the upstream `provider`,
-`workloadIdentity`, and `dangerouslyAllowBrowser` fields in addition to the
-CometAPI-owned `apiKey` and `baseURL` fields. Provider and workload-identity
-routing conflict with the API key and base URL that this client injects.
-Browser-side long-lived key use is outside the 0.1 security boundary. These
-fields never represented valid CometAPI behavior, so their removal from the
-public type is a 0.1.1 contract correction rather than a supported feature
-removal.
+The public `CometAPIOptions` type omits the upstream definitions of `provider`,
+`workloadIdentity`, and `dangerouslyAllowBrowser`, then redeclares those names as
+`provider?: never`, `workloadIdentity?: never`, and
+`dangerouslyAllowBrowser?: never`. Provider and workload-identity routing
+conflict with the API key and base URL that this client injects. Browser-side
+long-lived key use is outside the 0.1 security boundary. The optional-`never`
+contract makes variables, spreads, and constrained generics structurally
+incompatible when they carry a non-`undefined` reserved value. These fields
+never represented valid CometAPI behavior, so tightening the declaration within
+stable 0.1.x is not a supported feature removal.
 
 The inherited `withOptions` path is constrained to the same
 `CometAPIOptions` contract. Both the constructor and `withOptions` validate
@@ -99,15 +101,22 @@ The package manifest declares only intended runtime files. Generated build
 artifacts and dependency directories are not committed. A successful source-tree
 import is not package evidence; verification must use the packed artifact.
 
-`package.json` is the source of the candidate version. Local and release checks
-derive the version from it and require agreement with the package-lock root,
-the Release Please manifest or the documented one-time bootstrap, the single
-candidate changelog heading, and packed metadata. Remote publication adds exact
-tag and GitHub release agreement.
+`package.json` is the sole source of the candidate version. Local and release
+checks derive the version from it and require agreement with the package-lock
+root, the Release Please manifest or the documented one-time bootstrap, the
+single candidate changelog heading, and packed metadata. A normal stable
+Release Please PR changes exactly `.release-please-manifest.json`,
+`CHANGELOG.md`, `package-lock.json`, and `package.json`; version-specific status
+does not belong in its durable documentation. Remote publication adds exact tag
+and GitHub Release agreement.
 
 The publish workflow is the sole source of npm dist-tag selection: prereleases
 use `next`, stable versions use `latest`. The package manifest must not carry a
 static dist-tag because that would make stable and prerelease policy diverge.
+Exact registry and Release state must be queried from npm and GitHub rather than
+inferred from repository prose. The unversioned package page is
+<https://www.npmjs.com/package/cometapi>, and GitHub release state is available
+from <https://github.com/cometapi-dev/cometapi-node/releases>.
 Trusted Publishing is the only executable authentication path. The protected-
 environment token bootstrap used for `0.1.0-alpha.1` is historical evidence;
 current workflows contain no token publication path and reject registry-token

COMPATIBILITY.md

@@ -3,9 +3,12 @@
 Compatibility document version: 0.1  
 Package line: `0.1.x`
 
-Stable release: `0.1.1`; the immutable Release, bounded live smoke, npm OIDC
-publication, and separate public-registry verification completed on 2026-07-30.
-Registry Alpha `0.1.0-alpha.3` remains available from npm's `next` channel.
+Maintenance status: stable `0.1.x`. Stable packages use npm's `latest` channel,
+and Registry Alpha artifacts use `next`. Exact package, dist-tag, and GitHub
+Release state is intentionally not pinned here; query
+<https://www.npmjs.com/package/cometapi> and
+<https://github.com/cometapi-dev/cometapi-node/releases>. Dated evidence for
+each completed release remains below.
 
 This matrix defines the contract-tested 0.1 compatibility surface. Inheritance
 from the official OpenAI client does not by itself establish CometAPI support.
@@ -42,24 +45,27 @@ error contract.
 
 The 0.1 client keeps supported OpenAI transport and observability options, while
 reserving CometAPI routing, authentication, and the browser security boundary.
-The 0.1.0 declarations mistakenly admitted the three reserved fields even
-though they could not produce valid, supported CometAPI behavior; 0.1.1 corrects
-that contract:
+Earlier stable declarations omitted the three reserved fields, which rejected
+fresh object literals but still admitted structurally typed variables. Those
+fields never produced valid, supported CometAPI behavior. Stable maintenance
+therefore makes the prohibition structural:
 
 | Option group                                                                                 | Contract                                     |
 | -------------------------------------------------------------------------------------------- | -------------------------------------------- |
 | `timeout`, `maxRetries`, `fetch`, `fetchOptions`, `defaultHeaders`, `defaultQuery`, `logger` | Supported constructor pass-through           |
 | `organization`, `project`, `webhookSecret`, `adminAPIKey`                                    | Supported constructor pass-through           |
 | Per-request options                                                                          | Supported for the contract-tested operations |
-| `provider`, `workloadIdentity`, `dangerouslyAllowBrowser`                                    | Rejected by declarations and at runtime      |
+| `provider?: never`, `workloadIdentity?: never`, `dangerouslyAllowBrowser?: never`            | Rejected by declarations and at runtime      |
 
 `provider` and `workloadIdentity` would conflict with the CometAPI API key and
 base URL injected by the SDK. `dangerouslyAllowBrowser` would cross the 0.1
-long-lived-key boundary. The constructor and `withOptions` enforce the same
-rule. Runtime rejections use the official OpenAI `OpenAIError`, identify only
-the forbidden field, and do not include its value. Compile-time negative tests
-are executed by TypeScript against source and packed ESM/CommonJS declarations;
-runtime tests cover plain JavaScript and type-cast bypasses.
+long-lived-key boundary. Redeclaring all three fields as optional `never` makes
+non-`undefined` values incompatible through object literals, inferred
+variables, spreads, and constrained generics. The constructor and `withOptions`
+enforce the same rule at runtime. Runtime rejections use the official OpenAI
+`OpenAIError`, identify only the forbidden field, and do not include its value.
+Compile-time negative tests run against source and packed ESM/CommonJS
+declarations; runtime tests cover plain JavaScript and type-cast bypasses.
 
 ## Inherited but unsupported in 0.1
 

README.md

@@ -4,11 +4,11 @@ The official CometAPI entry point for the OpenAI-compatible API. The SDK keeps
 the official OpenAI JavaScript request, response, stream, and error types while
 defaulting the client to CometAPI.
 
-> **Stable 0.1 release:** `0.1.1` is published on npm's default `latest`
-> dist-tag. Its immutable GitHub Release, bounded live smoke, npm OIDC
-> publication, provenance, signature, and separate public-registry installation
-> verification are complete. The supported API remains limited to the
-> contract-tested 0.1 surface documented here and in
+> **Stable 0.1.x maintenance:** Stable packages install from npm's default
+> `latest` dist-tag, while prerelease artifacts use `next`. Exact package,
+> dist-tag, and GitHub Release state is intentionally not pinned in this README;
+> query the registries when that state matters. The supported API remains
+> limited to the contract-tested 0.1 surface documented here and in
 > [COMPATIBILITY.md](./COMPATIBILITY.md).
 
 ## Supported 0.1 surface
@@ -46,6 +46,17 @@ Install the stable package from npm's default `latest` dist-tag:
 npm install cometapi
 ```
 
+The unversioned registry page is
+<https://www.npmjs.com/package/cometapi>. Query npm and GitHub instead of using
+an exact version copied from repository prose:
+
+```bash
+npm view cometapi version
+npm view cometapi dist-tags --json
+gh release view --repo cometapi-dev/cometapi-node \
+  --json tagName,isDraft,isPrerelease,publishedAt,url
+```
+
 The release workflow is the sole source of the npm dist-tag: prerelease
 versions publish to `next`, while stable versions publish to `latest`. The
 package manifest does not declare a static dist-tag.
@@ -164,12 +175,13 @@ const response = await client.chat.completions.create(
 );
 ```
 
-Starting with 0.1.1, the public type matches the runtime boundary that 0.1.0
-intended. The SDK owns CometAPI routing, authentication, and the Node-only
-secret boundary. Consequently, `provider`, `workloadIdentity`, and
-`dangerouslyAllowBrowser` are not `CometAPIOptions`. They are rejected both by
-the TypeScript declarations and at runtime when plain JavaScript or a type cast
-bypasses those declarations. The same restriction applies to inherited
+The 0.1.x public type matches the enforced runtime boundary. The SDK owns
+CometAPI routing, authentication, and the Node-only secret boundary.
+`CometAPIOptions` therefore declares `provider?: never`,
+`workloadIdentity?: never`, and `dangerouslyAllowBrowser?: never`. Non-`undefined`
+values are rejected by TypeScript, including through inferred variables,
+spreads, and constrained generics, and runtime validation protects plain
+JavaScript and type-cast bypasses. The same restriction applies to inherited
 `withOptions` calls. A rejection is an official OpenAI `OpenAIError` and names
 only the forbidden field; it never includes the supplied value.
 
@@ -229,24 +241,20 @@ parent.
 
 ## Project status
 
-The repository has completed Public Preview, Registry Alpha, stable `0.1.0`,
-the `0.1.1` maintenance patch, and Repository foundation. Blocking CI,
-protected repository rules, security reporting, protected environments, and
-the authorized bounded live smoke have passed. Stable `0.1.1` is available from
-`latest`; Registry Alpha `0.1.0-alpha.3` remains available from `next`. A
-separate public-registry check passed ESM, CommonJS, declarations, supported
-mocked calls, the compatible-OpenAI host fixture with one effective OpenAI
-installation, official error identity, integrity, signature, and provenance.
-
-The immutable `0.1.0-alpha.2` GitHub release remains as an unpublished failure
-record because its guard stopped before invoking npm. Mocked responses, packed
-artifacts, GitHub Actions, trusted live tests, and npm publication remain
-separate evidence layers and must not be represented as another. Published npm
-artifacts are immutable, so the `0.1.1` tarball retains its candidate-era
-README; this post-release status first ships in a later package version. The
-one-time `0.1.1` publication recovery is documented as historical evidence in
-[RELEASING.md](./RELEASING.md); the current permanent release workflow is
-immutable-tag-bound. No 0.2 provider adapter work is included.
+The repository is in stable 0.1.x maintenance, and no 0.2 provider-adapter
+milestone is active. Repository foundation, Public Preview, and Registry Alpha
+are complete. Stable packages use `latest`; Registry Alpha artifacts use
+`next`. Use the npm and GitHub queries in [Installation](#installation) for
+exact current state. Release-specific CI, live-smoke, registry, integrity,
+signature, provenance, and public-install evidence is retained in
+[RELEASING.md](./RELEASING.md), not restated as mutable version status here.
+
+Mocked responses, packed artifacts, GitHub Actions, trusted live tests, and npm
+publication remain separate evidence layers and must not be represented as one
+another. Exact failed-release, immutable-artifact, and one-time recovery history
+is retained in [RELEASING.md](./RELEASING.md) rather than reproduced in this
+consumer README. The permanent release workflow is immutable-tag-bound and
+publishes through npm OIDC.
 
 See: