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

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions