Prove first-run and recovery paths

[cardmagic]

Summary

• rebuild the README around per-identity race-free realtime state, an early-release notice, fit boundaries, and factual provenance
• add a clean packaged SQLite quickstart and an npm tarball smoke gate
• add deterministic multi-process serialization, retry, crash recovery, and fencing proof
• add reproducible SQLite, PostgreSQL, and MySQL benchmarks with observed results and measurement limitations
• add comparison, support, contribution, security, correctness, and release documentation

Impact

The 0.13.0 package now has an executable first-run path, release-artifact verification, prominent delivery limitations, and reproducible technical evidence. No external service is required for the public SQLite quickstart.

Validation

• pnpm run format:check
• pnpm run check
• pnpm run test:coverage
• pnpm run build
• pnpm run pack:check
• pnpm run test:package
• pnpm run test:recovery
• pnpm audit --audit-level=high
• SQLite, PostgreSQL 18, and MySQL 8.4 benchmark runs

[greptile-apps]

Greptile Summary

The PR adds executable first-run, package-smoke, benchmark, and multi-process recovery evidence while substantially revising the project documentation.

• Adds packaged SQLite quickstart and release-artifact verification.
• Adds reproducible benchmark orchestration and observed database results.
• Adds deterministic serialization, retry, crash-recovery, and fencing demonstrations.
• Expands correctness, support, security, comparison, and release documentation.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
benchmarks/processes.ts	Adds readiness and exit helpers that detect worker startup exits and settle after removing event listeners.
benchmarks/run.ts	Adds multi-process benchmark orchestration and now terminates sibling workers when startup fails.
examples/failure-recovery/demo.ts	Adds deterministic recovery assertions and validates parsed event fields before constructing concrete event values.
scripts/release-artifact-smoke.mjs	Adds a clean-install smoke test for the generated npm package.
src/cli.ts	Adds the packaged SQLite quickstart command used by first-run and artifact verification paths.
.github/workflows/ci.yml	Extends CI with package and recovery validation gates.

_{Reviews (2): Last reviewed commit: "fix: fail fast when benchmark workers ex..." | Re-trigger Greptile}

[greptile-apps]

Worker startup failure hangs benchmark

When a worker exits during module loading or runtime.install(), it never sends ready, and this promise does not observe the exit, causing the benchmark command to wait indefinitely instead of reporting the startup failure.

Suggested change

	new Promise<void>((resolvePromise, reject) => {
	worker.once("error", reject)
	worker.on("message", (message) => {
	if (message === "ready") resolvePromise()
	})
	}),
	new Promise<void>((resolvePromise, reject) => {
	worker.once("error", reject)
	worker.once("exit", (code, signal) => {
	reject(new Error(`benchmark worker exited before ready with code ${code} and signal ${signal}`))
	})
	worker.on("message", (message) => {
	if (message === "ready") resolvePromise()
	})
	}),

Prompt To Fix With AI

This is a comment left during a code review.
Path: benchmarks/run.ts
Line: 238-243

Comment:
**Worker startup failure hangs benchmark**

When a worker exits during module loading or `runtime.install()`, it never sends `ready`, and this promise does not observe the exit, causing the benchmark command to wait indefinitely instead of reporting the startup failure.

```suggestion
        new Promise<void>((resolvePromise, reject) => {
          worker.once("error", reject)
          worker.once("exit", (code, signal) => {
            reject(new Error(`benchmark worker exited before ready with code ${code} and signal ${signal}`))
          })
          worker.on("message", (message) => {
            if (message === "ready") resolvePromise()
          })
        }),
```

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[greptile-apps]

Parsed events retain unknown fields

jsonLines casts every parsed line to Record<string, unknown> and callers then access its fields without narrowing. Define and validate a concrete recovery-event shape so event-schema mistakes remain visible to TypeScript.

Rule Used: What: Disallow the use of unknown in TypeScript ... (source)

Prompt To Fix With AI

This is a comment left during a code review.
Path: examples/failure-recovery/demo.ts
Line: 178-183

Comment:
**Parsed events retain unknown fields**

`jsonLines` casts every parsed line to `Record<string, unknown>` and callers then access its fields without narrowing. Define and validate a concrete recovery-event shape so event-schema mistakes remain visible to TypeScript.

**Rule Used:** What: Disallow the use of `unknown` in TypeScript ... ([source](https://app.greptile.com/craftsmanfounder/-/custom-context?memory=af673ae0-6488-4c8b-8b4a-1bfea4eb4de7))

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!