Shared constructs

A shared construct is an export that owns logic that several call sites share. Use it instead of writing the logic again. Read about a construct in three steps, each only when you need it:

1. This index: each category and each construct in one line.
2. Its contract, on the page of its category: signature, errors, requirements, side effects, how it works, one use, and the misuse to avoid.
3. Its consumers: just constructs consumers <name> prints the modules that import it. No page lists them, so an import changes no page.

The JSDoc of a construct carries @construct <category>, a summary sentence, @remarks, @sideEffects, @example, and @avoid, and its parameters and return type carry annotations. Tag a construct only when at least 2 modules outside its own module and the tests of its app or package import it. just constructs fails when these pages differ from the tags, when a construct lacks one of these tags or annotations, and when fewer modules import it. It lists untagged functions that 3 or more modules outside their app or package import.

• policy: Pure domain eligibility decisions over decoded facts and an explicit instant.
  • admissionStanding: Admission standing of the application's own period and semester at one instant.
• http-transport: Reads native HTTP requests and writes their representations: bounded JSON, preconditions, idempotency keys, entity tags, and cache headers.
  • encodePathIdentity: Encodes one decoded identity as an uppercase RFC 3986 path segment.
  • normalizeTarget: Fills a route template with its encoded identities; a missing identity is a malformed request.
  • deriveHttpIdentity: Derives the private storage digest and domain command ID from the identity tuple.
  • withIdentityRequestCancellation: Keeps an identity request's cancellation signal attached to its native Effect fiber.
• http-problem: Answers a native HTTP request with a declared problem: failure mapping, credential classification, authorization, and decoding.
  • authorizeAdmissionPerson: Evaluates one admission person AccessSpec through the generated guard of its endpoint.
  • returningAuthorization: Resolves the current person and authorizes one returning-assistant operation on that person's own profile.
  • admissionActorForAuthority: The admission actor of one department scope.
  • admissionProblems: The one answer for every admission failure.
  • contentProblems: The one answer for every content domain failure.
  • contentActorProblems: A staff person rejected after ingress is answered from the credential the request presented.
  • problemWebResponse: Renders one problem outside HttpApi encoding, with the encoder's body and headers.
  • jsonText: The JSON text of a representation, byte for byte what JSON.stringify writes.
  • webHandler: Runs one Effect-native Web transport operation.
  • semanticProblem: Runs a throwing semantic parser.
  • problemMapper: Builds the one failure-to-problem mapper of a domain.
  • requireNoQuery: An operation that accepts no query answers any query as malformed.
  • readJsonBody: Reads a bounded JSON body of the one media type mediaType accepts.
  • idempotencyKeyOf: Decodes the one Idempotency-Key a replayable mutation requires.
  • requiredIfMatchOf: Decodes the one strong If-Match an item mutation requires.
  • httpIdentity: Derives a command's idempotency identity; a tuple outside the frozen grammar is a request problem.
  • requireCurrentETag: Fails a mutation whose If-Match no longer names the current representation.
  • conditionalJson: Answers a conditional JSON read after authority and concealment: the representation, a bodyless 304, or precondition.failed.
  • personPresentation: The person credential a request presented, for a rejection answered after ingress.
  • isSerializationConflict: Whether a failure, or one of its causes, is a lost serialization or deadlock race: a transaction.conflict the client may retry.
  • requestInvalid: The request as a whole fails validation; no single member is singled out.
  • decodeRequest: Decodes one JSON request value strictly; any mismatch fails the whole request's validation.
  • strictOutput: Decodes one response value strictly.
  • commandReceiptProblems: HTTP command receipts: the transport's own persistence failures.
  • commandOutcomeResponse: Answers a command receipt outcome: committed and replayed results, or an idempotency problem.
  • authorizeAnonymous: An anonymous AccessSpec grants every caller and conceals nothing, so a denial means the spec and its scope resolution disagree: a defect.
  • authorizePerson: A rejected person credential is answered from the ingress evidence, never by string choice.
  • unreachable: Marks problems a shared mapper can produce but this operation cannot, such as a serialization conflict inside a read-only snapshot.
  • ProblemBoundaryLive: The only Cause consumer.
  • receiptProblems: The one answer for every receipt failure other than a rejected credential, including an unavailable store, Identity, or E2E barrier.
  • receiptCredentialProblems: A credential rejected inside a receipt handler is answered from the request's own evidence.
  • interviewAuthorizationInTransaction: Resolves the current person and authorizes one interview inside the caller's transaction; a rejected credential is answered from the request's evidence.
  • readRecruitmentBody: Every recruitment request body is one bounded application/json document.
  • recruitmentProblems: The one answer for every recruitment failure.
  • raceProblems: A failure that lost a serialization or deadlock race answers transaction.conflict, whatever failure carried it.
  • problemUnion: Creates a closed endpoint-specific Problem Details union.
  • Problem: One RFC 9457 failure in an Effect error channel.
  • isProblem: Narrows a caught value to a Problem, also one that another copy of this module created.
  • problemBody: The frozen RFC 9457 body: the registry entry, then code, instance, and validation.
  • makeNativeProblem: Builds one safe fixed public problem value.
• sql-lock: Transaction-scoped PostgreSQL advisory locks under registered keys.
  • AdvisoryLockKey: The registered advisory-lock keys, one constructor per namespace.
  • lockAdvisory: Waits for the advisory lock on key until the current transaction ends.
  • lockPersonAuthorization: Serializes one person's protected command with person-keyed authority writers.
• sql-lifecycle: Claim-fenced row lifecycles in PostgreSQL, such as outbox claims and account access.
  • lockApplicationDecisionWithSql: Fences this application's decision-sensitive writes in the caller's transaction.
  • readApplicationAdmissionEvidenceWithSql: Reads decoded admission evidence from the application's own period and semester.
  • withNativeAuthProvisioning: Runs one explicit native provisioning attempt through Better Auth's public endpoint context API.
  • accountAccessEnabled: Whether the native account of personId exists and is not disabled.
  • outboxClaimAssignments: SET list for the aggregate's claim UPDATE; targetAlias names the updated outbox row.
  • markOutboxDelivered: Settles the claimed row as Delivered, with delivery evidence when the table records it.
  • markOutboxFailed: Settles the claimed row as Failed with its failure tag, so a later claim retries it.
  • quarantineOutboxClaim: Settles the claimed row as Quarantined, a terminal status, with its failure tag.
  • releaseOutboxClaim: Returns an interrupted claim to Pending without a provider outcome; a lost claim needs none.
  • recoverStaleOutboxClaims: Recovers every Processing row claimed before claimedBefore.
  • nativePgLayer: Builds the native SQL layer with an explicit host-owned connection limit.
  • AuthPoolLive: Builds the supported Better Auth pool with its own host-supplied capacity.
  • executePostgresMigration: Executes parsed statements sequentially on the provided native SQL client.
• delivery: Delivers committed effects to providers after the transaction.
  • deliverJson: Shared acknowledged JSON transport; deliberately no retry on ambiguous acceptance.
• worker: Runs background workers on the Effect clock.
  • pollForever: Runs tick at once, then again after each success.
• pagination: Keyset cursors and pages over ordered PostgreSQL reads.
  • CursorPositioned: A row with the ordering text that receiptCursorTimestamp selects.
  • receiptCursorTimestamp: Selects the ordering column as microsecond UTC text so cursor positions compare exactly.
  • receiptCursorPage: Keeps one page of the rows, encodes the next cursor when a further row was read, and drops the ordering text.
• digest: Canonical JSON and SHA-256 digests that evidence and idempotency identities hash.
  • SecretEqualityLive: Supplies constant-time comparison of raw secrets under one process-owned HMAC key.
  • canonicalJsonValue: The plain JSON value of a datum, with sorted object keys and non-finite numbers as null.
  • canonicalJson: The canonical JSON text of a datum, to hash or compare; a SQL json parameter takes canonicalJsonValue instead.
  • canonicalJsonBytes: The UTF-8 bytes of the canonical JSON text of a datum.
  • sha256Hex: The lowercase hexadecimal SHA-256 digest of bytes.
• test-harness: Starts and drives disposable infrastructure for tests, proofs, and journeys: PostgreSQL clusters, loopback ports, and the local backend.
  • selectDatabaseMigration: Selects the registered migration id and the migrations that run before it.
  • journeyClock: A journey clock at a reference instant that the caller pins.
  • admissionJourneyClock: The backend's admission clock: ADMISSION_FIXED_NOW when the runner pins one, otherwise the current time.
  • localBackendEnvironment: The environment of a disposable local native backend for one composition.
  • postgresProgram: Absolute path of a client program of the selected PostgreSQL major.
  • postgresVersion: The postgres --version line of the selected major, such as postgres (PostgreSQL) 18.6, for evidence that names the toolchain whether or not a cluster started.
  • loopbackPortFree: Whether a listener can bind port on loopback now.
  • reserveLoopbackPorts: Reserves count distinct loopback ports for the servers that a journey starts: its backend, dashboard, receivers, and clusters.
  • startDisposablePostgres: Starts a fresh cluster of the selected major on a private port and socket directory with trust authentication.
  • withDisposablePostgres: Runs use against the database database of a fresh cluster, which startDisposablePostgres starts, and removes the cluster when use settles, also when it fails.
• request-ledger: Classifies the requests that journey recorders observe by whole path segments: native contract operations and legacy routes.
  • isNativeRequest: Whether a dashboard-to-backend request stays on the native surface: an operation of the native HTTP contract or an email-password route of the identity engine.
  • addressesAnyRoute: Whether a request path addresses any of the routes, each matched by whole path segments.
• ui-target: Derives stable UI element identities and selectors from decoded model identities.
  • correctionReopenTarget: Derives the Reopen button's stable id and eligible focus selector from its interview.