@functional-systems/lambdadb-cli 0.1.0-dev.4 → 0.1.0

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 ## [Unreleased]
 
+## [0.1.0] - 2026-09-18
+
+### Added
+
+- First stable release of the project-scoped LambdaDB CLI: configure, doctor,
+  collection list/describe/create, JSONL ordinary/bulk import, query and ID fetch.
+- Explicit branch/tag/alias read targets, noninteractive commands, versioned JSON
+  output and documented exit codes, including partial and unknown write outcomes.
+- Reuse of TypeScript SDK 0.5.1 for authentication, transport, read retries,
+  pagination, bulk transfers and large response downloads.
+- Apache-2.0 licensing, installed-package contract tests, opt-in development-project
+  smoke tests and provenance-enabled npm publication.
+
+### Fixed
+
+- Development publication verifies registry propagation for up to five minutes,
+  including bounded read subprocesses and polling sleeps. Transient read failures
+  can recover without repeating the successful publication. Authentication,
+  malformed metadata and source/artifact conflicts still fail verification.
+- Publication logs distinguish an accepted write from verification still pending;
+  a pending result remains nonzero and requires registry reads before a rerun.
+
+### Documentation
+
+- Record the completed bootstrap, initial OIDC publication, provenance/consumer
+  checks and the observed bootstrap `latest` tag behavior.
+
 ## [0.1.0-dev.1] - 2026-09-18
 
 ### Added
@@ -37,9 +64,10 @@
 
 ### Release status
 
-Prepared for the first public development release on npm's `dev` channel. This
-entry records the candidate contents and preparation date, not a publication.
-The development-project smoke is recorded in VALIDATION.md. npm organization
-permission verification, authorized bootstrap publication and Trusted Publishing
-setup remain pending. Automatic dev publication is disabled until maintainers
-enable `NPM_DEV_PUBLISH_ENABLED`; main promotion is required only for rc/stable.
+Published publicly on npm's `dev` channel on 2026-09-18 as the manual bootstrap.
+The initial OIDC build `0.1.0-dev.4` followed from the same reviewed develop
+commit; generated dev versions do not create separate source changelog entries.
+Automatic dev publication is enabled. The observed `latest` tag remains at the
+bootstrap until a reviewed stable release replaces it. Publication, provenance,
+installation and development-project smoke evidence are recorded in VALIDATION.md.
+Main promotion is required only for rc/stable.

package/CONTRIBUTING.md

@@ -14,9 +14,6 @@ not LambdaDB collection branches or refs.
 4. Address review feedback and pass both required CI checks before merging.
 5. Delete the short-lived branch after verifying the merge.
 
-For the initial MVP, `feat/cli-mvp` targets the initial `develop` commit. The
-review includes the CLI implementation, tests, documentation and CI setup.
-
 ## Local and CI validation
 
 ```sh
@@ -67,14 +64,18 @@ commit so the shared branch ancestry is preserved. After promotion, synchronize
 `develop`, especially release-only changes or hotfixes. Include the next intended
 development base in that synchronization PR so develop retains a dev version.
 
-A separate `release/*` branch is optional when stabilization must proceed while
-new work continues on `develop`. It is not required for the initial release.
+A separate `release/*` branch can be created from reviewed develop and target
+main when preparing rc/stable metadata while develop retains its automatic dev
+base. The first stable release uses `release/0.1.0` for this reason. Do not merge
+stable package metadata into develop without setting its next dev base, because
+automatic development publication requires an `X.Y.Z-dev.N` version.
 
 The first npm bootstrap, rc/stable tags and GitHub Releases remain explicit
 release actions. Subsequent dev publication is automatic once enabled.
-The `0.1.0-dev.1` candidate sets `private: false` and prepares metadata
-for the `dev` channel; the development-project smoke is recorded in
-[VALIDATION.md](VALIDATION.md), and publication remains pending. Follow
+Bootstrap `0.1.0-dev.1` and the first OIDC development publication `0.1.0-dev.4`
+were verified on 2026-09-18; automatic dev publication is enabled. Publication,
+provenance and development-project smoke evidence are recorded in
+[VALIDATION.md](VALIDATION.md). Follow
 [RELEASING.md](RELEASING.md) for package preparation, version/channel rules,
 credentialed live evidence, initial npm bootstrap and Trusted Publishing.
 Local tests and PR validation alone never trigger publication.

package/README.md

@@ -10,7 +10,7 @@ Requires Node.js 22.14 or newer and npm.
 
 ### Install from npm
 
-After the first development version is published, install the `dev` channel:
+The verified development build is available on the `dev` channel:
 
 ```sh
 npm install --global @functional-systems/lambdadb-cli@dev
@@ -18,6 +18,13 @@ lambdadb --version
 lambdadb --help
 ```
 
+This checkout prepares `0.1.0`. Once its GitHub Release and npm publication are
+complete, install the stable version with:
+
+```sh
+npm install --global @functional-systems/lambdadb-cli@0.1.0
+```
+
 The `dev` channel contains prerelease versions. For reproducible CI runs, pin an
 exact published version instead of the moving `dev` tag. See
 [RELEASING.md](RELEASING.md#current-status) for release preparation status and

package/RELEASING.md

@@ -2,18 +2,43 @@
 
 ## Current status
 
-The first public development candidate is `0.1.0-dev.1`, targeting npm's `dev`
-channel. Release preparation sets `private: false`; metadata now permits
-publication, but no package has been published by this project workflow.
+The `release/0.1.0` candidate prepares the first stable version from reviewed
+`develop` commit `c8947e9`. It changes package/lock versions and release documents;
+CLI runtime, dependencies, tests and workflows match the verified development build.
+The promotion PR targets `main` directly so `develop` keeps its automatic dev base.
+Merge with a merge commit, then obtain authorization for `v0.1.0` and a non-prerelease
+GitHub Release. Main promotion alone does not publish npm. After publication,
+verify `latest=0.1.0`, provenance and a clean consumer installation. Synchronize
+main back to develop through a PR that also sets the next development base.
+Stable publication has not yet been performed.
+
+The ordinary develop merge published `0.1.0-dev.5` through OIDC in
+[one successful workflow attempt](https://github.com/lambdadb/lambdadb-cli/actions/runs/35344153978).
+The new verification logic handled approximately three minutes of registry
+propagation without repeating the write or rerunning the workflow. A fresh npm
+installation passed 35 CLI contracts, integrity and provenance/signature checks.
+
+Bootstrap and initial OIDC publication were completed on 2026-09-18:
+
+- `0.1.0-dev.1` was published publicly from reviewed develop as the manual bootstrap.
+- `0.1.0-dev.4` was published by GitHub Actions with verified provenance for
+  commit `f2397ba`. Its registry installation passed all 35 CLI contract tests.
+- The repository variable `NPM_DEV_PUBLISH_ENABLED=true` enables eligible develop
+  pushes after Node 22/24 CI. Main promotion is required only for rc/stable.
+
+These are recorded validation milestones, not a continuously updated list of
+versions. Check npm for current dist-tags. At verification, `dev` pointed to
+`0.1.0-dev.4` and `latest` remained at the bootstrap `0.1.0-dev.1`: the first
+publication created both tags despite `--tag dev`, and removing `latest` returned
+HTTP 400. The next dev publication preserved `latest`. No stable version has been
+published; explicitly select `@dev` or an exact development version until a
+reviewed rc/stable release is available. Do not repeatedly delete the bootstrap
+tag or publish a placeholder to work around it.
+
 The CLI is licensed under [Apache-2.0](LICENSE), with matching package metadata.
-The development-project smoke is recorded in [VALIDATION.md](VALIDATION.md).
-npm organization permission verification and an authorized first bootstrap from
-reviewed `develop` remain required. Main promotion is required for rc/stable
-releases, not for development publication. Automatic dev publication is disabled
-until the repository variable `NPM_DEV_PUBLISH_ENABLED` is set to `true` after
-bootstrap and Trusted Publishing setup.
-The public npm lookup for `@functional-systems/lambdadb-cli` returned E404 on
-2026-09-18; this is not proof that the name is available or that ownership exists.
+Publication, provenance and development-project smoke evidence are recorded in
+[VALIDATION.md](VALIDATION.md). Local bootstrap has no GitHub Actions provenance;
+the automated development artifact does.
 
 The workflow rejects private packages and missing license metadata. Explicit
 rc/stable releases also require matching tags, prerelease flags and dated
@@ -76,9 +101,23 @@ and skips publication only when they agree and the dev tag already points there.
 Conflicts fail; missing or older tag state requires maintainer investigation.
 Registry authentication, transport and invalid-response failures are not treated
 as missing versions. A publish request is never retried automatically. After a
-successful write, bounded registry reads verify the manifest and dev tag. If
-propagation is delayed, retry reads before rerunning the job. Newer dev versions
-and stale commits are skipped without changing tags.
+successful write, registry reads get a shared five-minute monotonic budget to
+verify the source commit, tarball integrity and dev tag. Each read has at most
+15 seconds, capped to the remaining budget; polling sleeps are at most 10 seconds.
+Reads prefer fresh metadata and disable npm's nested fetch retries. Missing
+metadata, HTTP 429/5xx and recognized temporary connection/timeout errors are
+retried only after a successful publish. Authentication, malformed responses and
+artifact conflicts remain fatal. Process termination or scheduling can delay
+reporting, but responses at or after the deadline cannot pass verification.
+
+The script reports successful publication before waiting. If propagation still
+exceeds the budget, it emits `result=published-verification-pending` and exits
+nonzero. This means the write succeeded but verification is incomplete; it does
+not authorize another publish. Retry registry reads first. Once the manifest and
+dev tag agree, rerun the failed job: an identical artifact reports
+`result=already-published` without another write. Newer dev versions and stale
+commits are skipped without changing tags. A failed publish remains an uncertain
+write and is never automatically retried.
 
 After setup, an eligible push is sufficient; no manual version increment is
 needed. Users update with `npm install -g @functional-systems/lambdadb-cli@dev`,
@@ -152,6 +191,8 @@ Trusted Publishers are package-specific. The SDK's configuration does not cover
 this CLI. npm requires an existing package before configuring its trust policy.
 See the official [npm trust prerequisites](https://docs.npmjs.com/cli/v11/commands/npm-trust/).
 
+This one-time bootstrap was completed for this package on 2026-09-18. The steps
+below document setup and recovery; do not repeat the bootstrap for normal dev builds.
 For a new package, first complete the reviewed release preparation and preflight.
 An authorized npm organization owner performs the bootstrap from the verified
 develop commit, using interactive `npm login` and the account's MFA, then

package/VALIDATION.md

@@ -3,7 +3,112 @@
 Date: 2026-09-18. Local contract tests use loopback servers and synthetic
 credentials. A separate authenticated development-project smoke is recorded below.
 
-## Automatic development-release validation
+## Stable 0.1.0 candidate
+
+Prepared `release/0.1.0` from reviewed develop commit
+`c8947e96308283ac593e712716f0732121bb1958`. Relative to that commit, only package
+versions and release documents change. Runtime source, dependencies, tests,
+examples and workflows are unchanged. Stable publication remains pending.
+
+On Node.js 24.15.0 / npm 11.12.1, a new worktree passed `npm ci`, lint, type
+checking, all 59 source tests, and 35 installed-package contract tests.
+`RELEASE_TAG=v0.1.0 RELEASE_PRERELEASE=false npm run check:version -- --release`
+passed and selected `latest`. CI results for the final commit belong to the
+promotion PR; local success is not a substitute for those required checks.
+
+A newly packed `0.1.0` tarball was installed into an isolated temporary consumer.
+Its executable reported `0.1.0` and was selected with `LAMBDADB_TEST_CLI` while
+running `node --test --test-reporter=tap test/live/cli.test.mjs`. The launcher used
+the maintainer's existing opt-in development settings and the in-memory variable
+mapping described below; it did not change or copy `.env.local` into the worktree.
+Target: `bench-recall` at
+`https://internal-dev-aws-apne2-v3-c05a2b5d492a.lambdadb.ai`.
+
+- Doctor and temporary collection creation passed within the first second.
+- Two ordinary documents with 3 MiB payloads each and one bulk document were
+  accepted at approximately 3 seconds. Acceptance did not imply search visibility.
+- Query and ID fetch on `branch:main` returned all three documents with exact
+  contents at approximately 69 seconds, without a pending-write overlay.
+- The live test passed in 69.6 seconds. Cleanup was accepted, then an independent
+  SDK get returned `ResourceNotFoundError` for
+  `cli-smoke-b854ef72-1448-42ae-8c9a-ce5c0441f104`, confirming its absence.
+- The source `.env.local` was byte-for-byte unchanged, and the temporary consumer
+  and tarball were removed. No key or signed URL is recorded here.
+
+Only documentation was updated after this live run; the final package is checked
+again with the installed-package contracts. This is development-service evidence
+for a bounded sample, not a latency/readiness guarantee or live tag/alias coverage.
+The stable npm artifact and release-event workflow remain unverified until the
+explicit publication and subsequent consumer/provenance checks.
+
+## Public bootstrap and OIDC publication
+
+On 2026-09-18, the maintainer authorized the public bootstrap
+[`0.1.0-dev.1`](https://www.npmjs.com/package/@functional-systems/lambdadb-cli/v/0.1.0-dev.1)
+from reviewed develop commit `f2397ba`. Clean installation, lint, types and
+53 source tests passed; the exact tarball passed 35 installed-CLI tests and its
+published integrity matched. This local publication has no GitHub provenance.
+
+After npm Trusted Publisher setup and repository variable activation, the
+[develop push workflow, attempt 2](https://github.com/lambdadb/lambdadb-cli/actions/runs/35340278724/attempts/2)
+passed Node 22/24 validation, prepared `0.1.0-dev.4`, tested its exact tarball,
+and published with OIDC and provenance. The old six-attempt verification loop
+exhausted its five 5-second sleeps before npm metadata propagation completed, so
+the job failed after a successful publication. Read-only checks subsequently
+confirmed the artifact. The
+[protected rerun, attempt 3](https://github.com/lambdadb/lambdadb-cli/actions/runs/35340278724/attempts/3)
+completed with `result=already-published`, proving the same source/artifact was
+recognized without a second registry write.
+
+The public [`0.1.0-dev.4` provenance](https://registry.npmjs.org/-/npm/v1/attestations/@functional-systems%2flambdadb-cli@0.1.0-dev.4)
+identifies `lambdadb/lambdadb-cli`, `.github/workflows/publish.yaml`,
+`refs/heads/develop`, source commit `f2397ba102c67f1af9ed5ae0b8b8d47c06da7d4b`,
+and workflow attempt 2. Registry `gitHead`, downloaded tarball digest, installed
+lockfile integrity and provenance subject agreed. A clean `@dev` installation
+using an isolated npm cache passed version/help and all 35 CLI contract tests
+with the generated package metadata. `npm audit signatures` verified four package
+signatures and three attestations, including the CLI. No credentials were added
+to GitHub validation jobs or repository files.
+
+At this verification, `dev=0.1.0-dev.4` and `latest=0.1.0-dev.1`. Bootstrap had
+created both tags despite `--tag dev`; a removal attempt for `latest` returned
+HTTP 400. The automated dev publication left `latest` unchanged. This observation
+does not establish a general version-count rule for npm. Bootstrap and OIDC setup
+are complete; main promotion and rc/stable publication remain unperformed.
+
+## Publication verification hardening
+
+The follow-up script uses a five-minute monotonic verification budget, 15-second
+maximum read subprocesses and 10-second maximum polling sleeps. It retries only
+missing/lagging metadata and transient post-publication reads. It reports an
+accepted write separately from `published-verification-pending`, which still exits
+nonzero. Authentication, malformed responses and source/artifact mismatches fail
+closed. No late response can satisfy the deadline, and no verification path
+repeats the registry write.
+
+Deterministic tests exercise 150/180-second metadata/tag propagation, five-minute
+expiration, read time consuming the budget, capped final I/O/sleep, late success,
+temporary HTTP/transport failures and permanent errors. The changed publication
+logic passed all 59 source tests (12 release-automation tests), lint, type checks
+and version checks on Node 24.15.0; the installed tarball passed 35 CLI contracts.
+A read-only probe used the actual npm CLI and new bounded-read flags to verify
+the existing `0.1.0-dev.4` manifest/tag. Only its preflight and accepted write were
+simulated; the probe performed no registry mutation.
+
+The [ordinary develop merge workflow](https://github.com/lambdadb/lambdadb-cli/actions/runs/35344153978)
+published `0.1.0-dev.5` from `c8947e96308283ac593e712716f0732121bb1958`
+on attempt 1. Node 22/24 validation and exact-artifact tests passed. Publication
+succeeded at 12:22:09 UTC; registry verification completed at 12:25:10 UTC with
+`result=published`. The approximately 181-second propagation delay required only
+read retries, with no manual rerun or repeated publication.
+
+A fresh npm `@dev` install with an isolated cache passed all 35 CLI contract tests,
+version/help, tarball/lockfile integrity checks and npm signature verification.
+Provenance identified the expected repository, develop ref, workflow, source
+commit and attempt 1. `dev=0.1.0-dev.5`; `latest` remained `0.1.0-dev.1`.
+These registry checks are separate from the development-service smoke below.
+
+## Initial local automation validation (before publication)
 
 On Node.js 24.15.0, lint, type checking and all 46 source tests passed, including
 six release-automation tests. The tests cover deterministic first-parent version
@@ -24,8 +129,9 @@ all 35 installed-CLI contracts.
 `Node.js 22` and `Node.js 24` check names are retained. Publishing needs both jobs
 and is restricted to explicit releases or opted-in develop pushes. The repository
 variable enabling automatic dev publication was not set during this validation.
-Actual OIDC authentication, registry writes, provenance and GitHub job ordering
-remain unverified until the first authorized automated publication.
+At that stage, OIDC authentication, registry writes, provenance and GitHub job
+ordering were unverified. The later publication evidence above supersedes that
+limitation; it does not turn these original local tests into live registry writes.
 
 ## Authenticated development-project smoke
 
@@ -192,12 +298,9 @@ deployment state of an individual LambdaDB endpoint.
   receipt. Those capabilities are not implemented.
 - No Windows-specific permission or signal validation. POSIX modes and injected
   SIGINT/SIGTERM were checked on macOS; CI targets Linux.
-- No npm publication, Trusted Publisher configuration, registry provenance or
-  release-workflow execution. The `0.1.0-dev.1` candidate sets `private: false`
-  and targets the `dev` channel. npm organization permissions, authorized
-  bootstrap publication, trust setup and automatic-dev activation remain pending.
-  Main promotion is required for explicit rc/stable releases;
-  Apache-2.0 is recorded in LICENSE and package metadata.
+- No main promotion, explicit rc/stable publication or GitHub Release workflow
+  execution. Public bootstrap and automatic dev/OIDC publication are verified
+  above, including the five-minute verification behavior on an ordinary develop merge.
 - Mock large-response tests cover SDK routing/credential separation at 1 MiB;
   the live sample verifies combined content above 6 MiB. Neither is an exhaustive
   memory/size stress test. Imports buffer a maximum 64 MiB source file

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@functional-systems/lambdadb-cli",
-  "version": "0.1.0-dev.4",
+  "version": "0.1.0",
   "private": false,
   "description": "Project-scoped LambdaDB command-line tools",
   "type": "module",
@@ -52,6 +52,5 @@
   "bugs": {
     "url": "https://github.com/lambdadb/lambdadb-cli/issues"
   },
-  "license": "Apache-2.0",
-  "gitHead": "f2397ba102c67f1af9ed5ae0b8b8d47c06da7d4b"
+  "license": "Apache-2.0"
 }