Skip to content

Resolve #2753: Document Prisma readiness without AsyncLocalStorage#2762

Merged
ayden94 merged 1 commit into
mainfrom
issue-2753-prisma-als-readiness-docs
Jul 14, 2026
Merged

Resolve #2753: Document Prisma readiness without AsyncLocalStorage#2762
ayden94 merged 1 commit into
mainfrom
issue-2753-prisma-als-readiness-docs

Conversation

@ayden94

@ayden94 ayden94 commented Jul 14, 2026

Copy link
Copy Markdown
Contributor

Summary

Linked context: #2753[audit][area:persistence] Document Prisma readiness without AsyncLocalStorage (priority:p2).

The Prisma package already implements the not-ready readiness state when the host runtime does not provide AsyncLocalStorage (packages/prisma/src/status.ts and service.ts), but that state was not surfaced in the Prisma README or the beginner book chapter. Operators could not distinguish an unsupported transaction context from an ordinary database readiness failure. This PR documents the unavailable-ALS readiness behavior and the application-owned fallback boundary.

Changes

  • packages/prisma/README.md — Extended the Shutdown and Status Contracts readiness bullet to include the ALS-unavailable condition (client supports interactive transactions but host has no AsyncLocalStorage), the readiness reason text, and the details.transactionContext: 'unavailable' value. Added a paragraph describing the application-owned fallback boundary: callers must use the raw PrismaClient (via PRISMA_CLIENT) and manage their own consistency, or run on a host that provides ALS. Surface the unavailable state in health checks and route traffic away from transaction-dependent handlers.
  • packages/prisma/README.ko.md — Korean mirror of the same README changes (behavioral contract Rule 1 EN/KO parity).
  • book/beginner/ch12-prisma.md — Added a Readiness Without AsyncLocalStorage section after Transaction Awareness so readers meet the unavailable readiness state before the transaction chapter.
  • book/beginner/ch12-prisma.ko.md — Korean mirror of the same book section.

Testing

Doc-only change. Verification run in the dedicated worktree:

  • pnpm verify:platform-consistency-governancePlatform consistency governance checks passed.
  • pnpm lint — No new diagnostics on changed files (only pre-existing warnings/infos on unrelated files).
  • pnpm verify:public-export-tsdocPublic export TSDoc checks passed (changed mode).

No runtime behavior, public API, package contents, or release metadata changed; no tests added because no behavior changed.

Release impact

  • This PR has consumer-visible release impact and includes a changeset.
  • This PR has no consumer-visible release impact.

Doc-only edit. No public @fluojs/* package behavior, API surface, package contents, or release metadata changed. Per CONTRIBUTING.md, docs-only edits do not require a changeset.

Public export documentation

See docs/contracts/public-export-tsdoc-baseline.md for the repo-wide authoring baseline.

  • Changed public exports include a source-level summary. — No public exports changed.
  • Changed exported functions document matching @param / @returns tags where applicable. — No exported functions changed.
  • Source @example blocks and README scenario examples still play complementary roles. — README scenario examples extended, not replaced.

Behavioral contract

See docs/contracts/behavioral-contract-policy.md for full details.

  • No documented behavioral contracts were removed without migration notes. — No contracts removed; an existing implemented contract (ALS-unavailable readiness) is now documented.
  • New behavioral contracts are documented in the affected package README. — The unavailable-ALS readiness behavior and application-owned fallback boundary are now in the Prisma README.
  • Intentional limitations are explicitly stated (not silently removed). — The no-synchronous-stack-fallback limitation is now explicit in the README and book.
  • Runtime invariants are covered by regression tests. — No new invariants; existing status.ts/service.ts behavior is already covered by module.test.ts and transaction-compat.test.ts.

Platform consistency governance (SSOT)

See docs/architecture/platform-consistency-design.md and docs/contracts/release-governance.md.

  • SSOT English/Korean mirror structure remains synchronized for changed governance docs. — README.md/README.ko.md and ch12-prisma.md/ch12-prisma.ko.md updated in parallel.
  • If platform contract docs changed, companion updates include discoverability/docs index, tooling or CI enforcement, and regression-test evidence. — No platform contract docs changed; pnpm verify:platform-consistency-governance passed.
  • Any package README alignment/conformance claims are backed by the applicable platform harness tests. — No new alignment claims; existing harness tests remain authoritative.

Closes #2753

…d fallback boundary

Document the not-ready readiness state when the host runtime does not
provide AsyncLocalStorage while the Prisma client supports interactive
transactions. The readiness reason, details.transactionContext
'unavailable' value, and the application-owned fallback boundary were
implemented in status.ts and service.ts but not surfaced in the Prisma
README or the beginner book chapter.

- README.md / README.ko.md: extend the Shutdown and Status Contracts
  readiness bullet with the ALS-unavailable condition, the readiness
  reason text, and a paragraph describing the application-owned fallback
  boundary (raw PrismaClient via PRISMA_CLIENT, or a host that provides
  ALS).
- book/beginner/ch12-prisma.md / ch12-prisma.ko.md: add a
  Readiness Without AsyncLocalStorage section after Transaction Awareness
  so readers meet the unavailable readiness state before the transaction
  chapter.

Closes #2753
@ayden94
ayden94 merged commit 0e3513b into main Jul 14, 2026
19 of 20 checks passed
@ayden94
ayden94 deleted the issue-2753-prisma-als-readiness-docs branch July 14, 2026 01:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[audit][area:persistence] Document Prisma readiness without AsyncLocalStorage (priority:p2)

1 participant