Skip to content

org: publish the btravstack DNA document (org-wide conventions and decisions) #554

Description

@btravers

Org-level issue (filed here because btravstack.github.io has issues disabled — transfer if that changes). Outcome of the July 2026 cross-project DNA review (unthrown, amqp-contract, temporal-contract, demesne, hub). The mechanical layer is already highly aligned; the remaining drift is conventions that were never written down. Publish a canonical DNA document (hub page and/or a shared agent-rules template) capturing:

  • Naming grammar: define* = pure contract declarations · declare* = implementation bindings · Typed*.create() = runtime instances, always AsyncResult-returning. (Resolves amqp defineHandlers vs temporal declareActivitiesHandler/createWorker drift.)
  • Error DNA: unthrown three-channel model; TaggedError namespaced _tag + bare Error.name; .match/.recoverErr/.flatMapErr in real code; .getOrThrow() only in tests/scripts/examples; qualify factories over hand-written mappers; documented exceptions (temporal's ApplicationFailure-extending ValidationError).
  • Contract DNA: Standard Schema v1; composition-first (never inline in defineContract); define-time structural validation; role-prefixed Infer* helpers; typed contract-declared errors (schema-validated wire conversion + degrading rehydration); unified context model (createContext seed + accumulating middleware + { context, errors } helpers); client interceptors.
  • Agent-docs standard: AGENTS.md source of truth; CLAUDE.md + .github/copilot-instructions.md symlinks; .agents/rules/ split for monorepos, monolithic spec for focused libraries; load-bearing invariants mapped to named guarding tests (invariants.spec.ts).
  • Testing standard: vitest 4 unit/integration projects; @unthrown/vitest matchers; one type-test style (proposal: vitest typecheck + expectTypeOf); enforced coverage thresholds; an in-process/no-Docker story per project.
  • Release/versioning: fixed changeset group per repo + satellites outside it tracking upstream cadence (@unthrown/prisma/@unthrown/orpc pattern — applies to future experimental-* packages); peers for anything in public types; Trusted Publishing OIDC, workflow_run-gated.
  • CI baseline: Format/Lint/TypeCheck/Knip/Tests(+engine-floor matrix)/Build/Package(publint+attw)/Changeset/SecurityAudit/BundleSize; SHA-pinned actions.
  • Phase 2: the oRPC v2 DNA traits each project adopts (typed error maps, middleware+context, interceptors, in-process transport, meta plugins, type<T>() — consider a shared @btravstack contract-kit for the last two + shared error shape + formatIssue).

Implementing issues: amqp-contract #549#553 (+#541#544), temporal-contract #301#304, demesne #24#25, and the shared-tooling issue below.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions