Skip to content
ContractSpec
Start here

Package manual · platform

·Forms, data views and data exchange

module.forms

Reusable builder, respondent, results, and administration module for the shared Forms platform.

platformmodulev2.0.4experimentalservernode
@lssm-tech/module.forms
bun add @lssm-tech/module.forms
Package source ↗Manifest ↗

Manifest declarations describe the current workspace; they do not verify registry publication or runtime execution.

Package guide

Provider-neutral Forms feature composition for web and native hosts.

The module owns reusable builder, respondent-session, results, administration, verification/resume DTO, and localized chrome behavior. Product hosts inject authenticated authority, PostgreSQL storage, delivery providers, AI adapters, public routing, branding, and feature flags. Public payloads never carry tenant or workspace authority, and Forms has no dependency on OPA.

Milestones

Each capability has an independent flag (forms.v0 through forms.v0_6). Publishing fails closed when a document requires a disabled milestone.

  • v0: localized one-page authoring, immutable publish/share, anonymous response capture, keyset results, response detail, and audited streaming CSV.
  • v0.1-v0.3: accessible steps, deterministic server-authoritative branching, browser-session progress, encrypted resumable drafts, and provider-backed email/phone verification with expiry, throttling, replay, and attempt limits.
  • v0.4: portable full-FormSpec compilation, including groups, arrays, resolvers, computations, constraints, projections, layouts, and actions.
  • v0.5: consent-aware, redacted or self-hosted AI follow-ups and cited analysis, with recursive declared-PII/contact redaction, versioned consent receipts, pre-invocation call reservations, cumulative remaining token/cost limits, frozen localized questions, and a hard ten-turn ceiling including failed provider calls.
  • v0.6: portable import/export, duplication and revision comparison, extension registries, bounded signed-webhook retries with terminal failed states, signed origin-bound embed grants, SDK/agent adapters, typed OPA destinations, and web, mobile, desktop, native, embed, and MCP surfaces.

Host contract

Hosts mount management at their product route and public responses at /f/{opaqueToken}, backed by /api/forms/v1. They inject a product-owned PostgreSQL connection, authenticated creator authority, a data-protection key, and milestone flags. Verification, AI, distributed request defense, secret resolution, and outbox delivery are optional ports but required when the corresponding published policy needs them.

The PostgreSQL schema forces tenant/workspace/owner RLS and binds anonymous database sessions to the exact response, draft, challenge, or extension being handled. It encrypts answers and verification destinations, pins responses to immutable revisions, and stores only scoped digests where deduplication is required. CSV exports use an exact response-set watermark and redact typed or explicitly classified sensitive fields unless an audited sensitive-export grant is present. Recursive FormSpec model roots and frozen AI extension answers use stable CSV columns. Retention cleanup and audited erasure are scope-bound. Logs and integration events exclude raw answers, contact destinations, verification codes, and raw IP addresses.

Author catalogs may use any valid BCP-47 locale. The built-in authoring chrome ships in English, French, and Spanish; answers remain canonical and locale-independent.

Canonical source ownership: @lssm-tech/lib.contracts-runtime-kernel owns the existing framework-neutral implementation; module.forms/runtime owns the existing Forms service and FormsPlatformError; Observability/contracts-runtime owns the existing automatic backend event binding. Legacy five maps and default behavior are preserved. Clean artifact qualification and runtime authority remain separate requirements.

The runtime-only leaf owns the existing Forms service, FormsPlatformError, immutable revisions, assurance, consent, idempotency, navigation and PII-safe CSV behavior. It imports existing Forms contracts and no UI root. UI and server composition remain existing supported roots. Declared source-unused React-runtime and Legacy RuntimeCore dependencies are removed in this source implementation and require real consumer qualification. Producer declarations/physical consumers/release/final-tree acceptance remain pending.

Relationships

THIS PACKAGEmodule.forms95 import paths

Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.

5 declarations

Declared capabilities

Module Forms

Reusable builder, respondent, results, and administration module for the shared Forms platform.

Scripts

  • buildcontractspec-bun-build build
  • build:bundlecontractspec-bun-build transpile
  • build:typescontractspec-bun-build types
  • cleanrimraf dist .turbo
  • lint:checknode ../../../../scripts/biome.cjs check .
  • lint:fixnode ../../../../scripts/biome.cjs check --write .
  • testbun test
  • typechecktsgo --noEmit