From dfa0ab05ffe0467a8029aafc6a9bd5919e5f3b42 Mon Sep 17 00:00:00 2001 From: Erik LaBianca Date: Wed, 11 Nov 2026 17:09:57 -0500 Subject: [PATCH 1/7] Remove process material and unimplemented specs; move approval model to the example Move the approval UMF model from docs/helix/reference-apps to examples/approval-desk/model (the example wheel and prepare_approval read it). Delete the 12 reference-app specs, the evidence/verification JSON, boundary audit, test plan, release notes, the micro-app gate, quality baseline and ratchet ADRs/contracts; collapse unbuilt work into ROADMAP.md. prepare_approval installs UMF from PyPI instead of hash-checked release URLs. Co-Authored-By: Claude Sonnet 5.5 --- .gitignore | 6 + AGENTS.md | 85 +- README.md | 16 +- ROADMAP.md | 41 + .../boundary-audit/external-nodes.csv | 157 -- .../boundary-audit/import-graph.csv | 2368 ----------------- .../00-discover/boundary-audit/modules.csv | 224 -- .../boundary-audit/static-cycles.csv | 12 - .../00-discover/boundary-audit/summary.json | 29 - .../current-state-inventory-boundaries.md | 103 - docs/helix/00-discover/intent-and-intake.md | 143 - docs/helix/00-discover/product-vision.md | 2 +- docs/helix/00-discover/research/convex.md | 42 - .../helix/00-discover/research/foundations.md | 56 - docs/helix/00-discover/research/mcp-apps.md | 41 - docs/helix/01-frame/feature-registry.md | 2 +- .../FEAT-002-operations-and-interfaces.md | 2 +- ...005-sdk-series-and-cohort-compatibility.md | 83 - .../adr/ADR-007-quality-and-test-ratchets.md | 117 - ...ndependent-reference-app-specifications.md | 56 - docs/helix/02-design/architecture.md | 4 +- .../contracts/CONTRACT-001-public-host-api.md | 2 - .../CONTRACT-002-boundaries-and-quality.md | 320 --- .../CONTRACT-011-micro-app-conformance.md | 134 - .../SD-002-lintel-graphql-relay.md | 136 - docs/helix/03-test/.gitkeep | 0 docs/helix/03-test/test-plan.md | 389 --- docs/helix/04-build/.gitkeep | 0 docs/helix/04-build/batten-app-workflow.md | 97 - .../dependency-upgrade/implementation-plan.md | 97 - .../dependency-upgrade/verification.json | 801 ------ docs/helix/04-build/implementation-plan.md | 88 - docs/helix/04-build/integration-gaps.md | 116 - .../04-build/local-storage-verification.json | 69 - .../micro-app-corpus-verification.json | 25 - docs/helix/05-deploy/.gitkeep | 0 docs/helix/05-deploy/release-notes.md | 94 - .../05-deploy/runtime-release-0.1.0a1.md | 139 - .../05-deploy/runtime-release-0.1.0a2.md | 123 - .../05-deploy/storage-release-0.1.0a1.md | 74 - docs/helix/06-iterate/.gitkeep | 0 docs/helix/README.md | 199 +- docs/helix/guide/developer/about.md | 10 +- docs/helix/guide/developer/architecture.md | 5 +- docs/helix/guide/developer/composition.md | 2 - .../developer/example-access-attestation.md | 38 - .../guide/developer/example-approval-desk.md | 6 +- .../guide/developer/example-case-tracker.md | 38 - .../developer/example-data-reconciliation.md | 38 - .../developer/example-document-review.md | 38 - .../developer/example-entity-directory.md | 42 - .../developer/example-evidence-library.md | 38 - .../developer/example-knowledge-assistant.md | 38 - .../guide/developer/example-model-triage.md | 38 - .../developer/example-scheduled-digest.md | 38 - .../developer/example-service-handoff.md | 38 - .../guide/developer/example-service-intake.md | 38 - docs/helix/guide/developer/examples.md | 80 - docs/helix/guide/developer/index.md | 7 +- docs/helix/guide/developer/integrations.md | 1 - docs/helix/reference-apps/README.md | 42 - .../access-attestation/.helix.yml | 12 - .../access-attestation/AGENTS.md | 19 - .../access-attestation/fixtures.json | 13 - .../features/FEAT-111-business-journey.md | 71 - .../access-attestation/specs/01-frame/prd.md | 105 - .../01-frame/user-stories/US-111-journey.md | 70 - .../specs/03-test/test-plan.md | 96 - .../reference-apps/approval-desk/.helix.yml | 12 - .../reference-apps/approval-desk/AGENTS.md | 19 - .../approval-desk/fixtures.json | 13 - .../features/FEAT-101-business-journey.md | 77 - .../approval-desk/specs/01-frame/prd.md | 111 - .../01-frame/user-stories/US-101-journey.md | 72 - .../solution-designs/SD-101-approval-desk.md | 144 - .../technical-designs/TD-101-approval-desk.md | 108 - .../specs/03-test/local-execution.json | 138 - .../approval-desk/specs/03-test/test-plan.md | 97 - .../test-plans/STP-101-approval-desk.md | 118 - .../specs/04-build/implementation-plan.md | 86 - .../reference-apps/case-tracker/.helix.yml | 12 - .../reference-apps/case-tracker/AGENTS.md | 19 - .../reference-apps/case-tracker/fixtures.json | 13 - .../features/FEAT-103-business-journey.md | 71 - .../case-tracker/specs/01-frame/prd.md | 105 - .../01-frame/user-stories/US-103-journey.md | 70 - .../case-tracker/specs/03-test/test-plan.md | 96 - docs/helix/reference-apps/catalog.json | 264 -- .../data-reconciliation/.helix.yml | 12 - .../data-reconciliation/AGENTS.md | 19 - .../data-reconciliation/fixtures.json | 13 - .../features/FEAT-109-business-journey.md | 71 - .../data-reconciliation/specs/01-frame/prd.md | 105 - .../01-frame/user-stories/US-109-journey.md | 70 - .../specs/03-test/test-plan.md | 96 - .../reference-apps/document-review/.helix.yml | 12 - .../reference-apps/document-review/AGENTS.md | 19 - .../document-review/fixtures.json | 13 - .../features/FEAT-105-business-journey.md | 71 - .../document-review/specs/01-frame/prd.md | 105 - .../01-frame/user-stories/US-105-journey.md | 70 - .../specs/03-test/test-plan.md | 96 - .../entity-directory/.helix.yml | 12 - .../reference-apps/entity-directory/AGENTS.md | 19 - .../entity-directory/fixtures.json | 13 - .../features/FEAT-106-business-journey.md | 71 - .../entity-directory/specs/01-frame/prd.md | 105 - .../01-frame/user-stories/US-106-journey.md | 70 - .../specs/03-test/test-plan.md | 96 - .../evidence-library/.helix.yml | 12 - .../reference-apps/evidence-library/AGENTS.md | 19 - .../evidence-library/fixtures.json | 13 - .../features/FEAT-104-business-journey.md | 71 - .../evidence-library/specs/01-frame/prd.md | 105 - .../01-frame/user-stories/US-104-journey.md | 70 - .../specs/03-test/test-plan.md | 96 - .../knowledge-assistant/.helix.yml | 12 - .../knowledge-assistant/AGENTS.md | 19 - .../knowledge-assistant/fixtures.json | 13 - .../features/FEAT-107-business-journey.md | 71 - .../knowledge-assistant/specs/01-frame/prd.md | 105 - .../01-frame/user-stories/US-107-journey.md | 70 - .../specs/03-test/test-plan.md | 96 - .../reference-apps/model-triage/.helix.yml | 12 - .../reference-apps/model-triage/AGENTS.md | 19 - .../reference-apps/model-triage/fixtures.json | 13 - .../features/FEAT-108-business-journey.md | 71 - .../model-triage/specs/01-frame/prd.md | 105 - .../01-frame/user-stories/US-108-journey.md | 70 - .../model-triage/specs/03-test/test-plan.md | 96 - .../scheduled-digest/.helix.yml | 12 - .../reference-apps/scheduled-digest/AGENTS.md | 19 - .../scheduled-digest/fixtures.json | 13 - .../features/FEAT-110-business-journey.md | 71 - .../scheduled-digest/specs/01-frame/prd.md | 105 - .../01-frame/user-stories/US-110-journey.md | 70 - .../specs/03-test/test-plan.md | 96 - .../reference-apps/service-handoff/.helix.yml | 12 - .../reference-apps/service-handoff/AGENTS.md | 19 - .../service-handoff/fixtures.json | 13 - .../features/FEAT-112-business-journey.md | 71 - .../service-handoff/specs/01-frame/prd.md | 105 - .../01-frame/user-stories/US-112-journey.md | 70 - .../specs/03-test/test-plan.md | 96 - .../reference-apps/service-intake/.helix.yml | 12 - .../reference-apps/service-intake/AGENTS.md | 19 - .../service-intake/fixtures.json | 13 - .../features/FEAT-102-business-journey.md | 71 - .../service-intake/specs/01-frame/prd.md | 105 - .../01-frame/user-stories/US-102-journey.md | 70 - .../service-intake/specs/03-test/test-plan.md | 96 - docs/helix/site/build.py | 25 +- docs/helix/site/publication-evidence.json | 59 - docs/helix/site/verification.json | 71 - examples/approval-desk/README.md | 29 +- .../approval-desk/model}/approval.umf.json | 0 examples/approval-desk/pyproject.toml | 2 +- justfile | 4 +- playwright.config.ts | 5 - pyproject.toml | 2 +- scripts/boundary_checks.py | 34 +- scripts/browser_census.mjs | 84 - scripts/{quality.py => check.py} | 7 +- scripts/check_boundaries.py | 59 +- scripts/check_micro_apps.py | 137 - scripts/check_policy.py | 73 - scripts/prepare_approval.py | 233 +- scripts/quality-baseline.json | 4 - tests/boundaries/test_boundaries.py | 61 + tests/quality/test_gate.py | 230 -- uv.lock | 28 + 171 files changed, 261 insertions(+), 13458 deletions(-) create mode 100644 ROADMAP.md delete mode 100644 docs/helix/00-discover/boundary-audit/external-nodes.csv delete mode 100644 docs/helix/00-discover/boundary-audit/import-graph.csv delete mode 100644 docs/helix/00-discover/boundary-audit/modules.csv delete mode 100644 docs/helix/00-discover/boundary-audit/static-cycles.csv delete mode 100644 docs/helix/00-discover/boundary-audit/summary.json delete mode 100644 docs/helix/00-discover/current-state-inventory-boundaries.md delete mode 100644 docs/helix/00-discover/intent-and-intake.md delete mode 100644 docs/helix/00-discover/research/convex.md delete mode 100644 docs/helix/00-discover/research/foundations.md delete mode 100644 docs/helix/00-discover/research/mcp-apps.md delete mode 100644 docs/helix/02-design/adr/ADR-005-sdk-series-and-cohort-compatibility.md delete mode 100644 docs/helix/02-design/adr/ADR-007-quality-and-test-ratchets.md delete mode 100644 docs/helix/02-design/adr/ADR-014-independent-reference-app-specifications.md delete mode 100644 docs/helix/02-design/contracts/CONTRACT-002-boundaries-and-quality.md delete mode 100644 docs/helix/02-design/contracts/CONTRACT-011-micro-app-conformance.md delete mode 100644 docs/helix/02-design/solution-designs/SD-002-lintel-graphql-relay.md delete mode 100644 docs/helix/03-test/.gitkeep delete mode 100644 docs/helix/03-test/test-plan.md delete mode 100644 docs/helix/04-build/.gitkeep delete mode 100644 docs/helix/04-build/batten-app-workflow.md delete mode 100644 docs/helix/04-build/dependency-upgrade/implementation-plan.md delete mode 100644 docs/helix/04-build/dependency-upgrade/verification.json delete mode 100644 docs/helix/04-build/implementation-plan.md delete mode 100644 docs/helix/04-build/integration-gaps.md delete mode 100644 docs/helix/04-build/local-storage-verification.json delete mode 100644 docs/helix/04-build/micro-app-corpus-verification.json delete mode 100644 docs/helix/05-deploy/.gitkeep delete mode 100644 docs/helix/05-deploy/release-notes.md delete mode 100644 docs/helix/05-deploy/runtime-release-0.1.0a1.md delete mode 100644 docs/helix/05-deploy/runtime-release-0.1.0a2.md delete mode 100644 docs/helix/05-deploy/storage-release-0.1.0a1.md delete mode 100644 docs/helix/06-iterate/.gitkeep delete mode 100644 docs/helix/guide/developer/example-access-attestation.md delete mode 100644 docs/helix/guide/developer/example-case-tracker.md delete mode 100644 docs/helix/guide/developer/example-data-reconciliation.md delete mode 100644 docs/helix/guide/developer/example-document-review.md delete mode 100644 docs/helix/guide/developer/example-entity-directory.md delete mode 100644 docs/helix/guide/developer/example-evidence-library.md delete mode 100644 docs/helix/guide/developer/example-knowledge-assistant.md delete mode 100644 docs/helix/guide/developer/example-model-triage.md delete mode 100644 docs/helix/guide/developer/example-scheduled-digest.md delete mode 100644 docs/helix/guide/developer/example-service-handoff.md delete mode 100644 docs/helix/guide/developer/example-service-intake.md delete mode 100644 docs/helix/guide/developer/examples.md delete mode 100644 docs/helix/reference-apps/README.md delete mode 100644 docs/helix/reference-apps/access-attestation/.helix.yml delete mode 100644 docs/helix/reference-apps/access-attestation/AGENTS.md delete mode 100644 docs/helix/reference-apps/access-attestation/fixtures.json delete mode 100644 docs/helix/reference-apps/access-attestation/specs/01-frame/features/FEAT-111-business-journey.md delete mode 100644 docs/helix/reference-apps/access-attestation/specs/01-frame/prd.md delete mode 100644 docs/helix/reference-apps/access-attestation/specs/01-frame/user-stories/US-111-journey.md delete mode 100644 docs/helix/reference-apps/access-attestation/specs/03-test/test-plan.md delete mode 100644 docs/helix/reference-apps/approval-desk/.helix.yml delete mode 100644 docs/helix/reference-apps/approval-desk/AGENTS.md delete mode 100644 docs/helix/reference-apps/approval-desk/fixtures.json delete mode 100644 docs/helix/reference-apps/approval-desk/specs/01-frame/features/FEAT-101-business-journey.md delete mode 100644 docs/helix/reference-apps/approval-desk/specs/01-frame/prd.md delete mode 100644 docs/helix/reference-apps/approval-desk/specs/01-frame/user-stories/US-101-journey.md delete mode 100644 docs/helix/reference-apps/approval-desk/specs/02-design/solution-designs/SD-101-approval-desk.md delete mode 100644 docs/helix/reference-apps/approval-desk/specs/02-design/technical-designs/TD-101-approval-desk.md delete mode 100644 docs/helix/reference-apps/approval-desk/specs/03-test/local-execution.json delete mode 100644 docs/helix/reference-apps/approval-desk/specs/03-test/test-plan.md delete mode 100644 docs/helix/reference-apps/approval-desk/specs/03-test/test-plans/STP-101-approval-desk.md delete mode 100644 docs/helix/reference-apps/approval-desk/specs/04-build/implementation-plan.md delete mode 100644 docs/helix/reference-apps/case-tracker/.helix.yml delete mode 100644 docs/helix/reference-apps/case-tracker/AGENTS.md delete mode 100644 docs/helix/reference-apps/case-tracker/fixtures.json delete mode 100644 docs/helix/reference-apps/case-tracker/specs/01-frame/features/FEAT-103-business-journey.md delete mode 100644 docs/helix/reference-apps/case-tracker/specs/01-frame/prd.md delete mode 100644 docs/helix/reference-apps/case-tracker/specs/01-frame/user-stories/US-103-journey.md delete mode 100644 docs/helix/reference-apps/case-tracker/specs/03-test/test-plan.md delete mode 100644 docs/helix/reference-apps/catalog.json delete mode 100644 docs/helix/reference-apps/data-reconciliation/.helix.yml delete mode 100644 docs/helix/reference-apps/data-reconciliation/AGENTS.md delete mode 100644 docs/helix/reference-apps/data-reconciliation/fixtures.json delete mode 100644 docs/helix/reference-apps/data-reconciliation/specs/01-frame/features/FEAT-109-business-journey.md delete mode 100644 docs/helix/reference-apps/data-reconciliation/specs/01-frame/prd.md delete mode 100644 docs/helix/reference-apps/data-reconciliation/specs/01-frame/user-stories/US-109-journey.md delete mode 100644 docs/helix/reference-apps/data-reconciliation/specs/03-test/test-plan.md delete mode 100644 docs/helix/reference-apps/document-review/.helix.yml delete mode 100644 docs/helix/reference-apps/document-review/AGENTS.md delete mode 100644 docs/helix/reference-apps/document-review/fixtures.json delete mode 100644 docs/helix/reference-apps/document-review/specs/01-frame/features/FEAT-105-business-journey.md delete mode 100644 docs/helix/reference-apps/document-review/specs/01-frame/prd.md delete mode 100644 docs/helix/reference-apps/document-review/specs/01-frame/user-stories/US-105-journey.md delete mode 100644 docs/helix/reference-apps/document-review/specs/03-test/test-plan.md delete mode 100644 docs/helix/reference-apps/entity-directory/.helix.yml delete mode 100644 docs/helix/reference-apps/entity-directory/AGENTS.md delete mode 100644 docs/helix/reference-apps/entity-directory/fixtures.json delete mode 100644 docs/helix/reference-apps/entity-directory/specs/01-frame/features/FEAT-106-business-journey.md delete mode 100644 docs/helix/reference-apps/entity-directory/specs/01-frame/prd.md delete mode 100644 docs/helix/reference-apps/entity-directory/specs/01-frame/user-stories/US-106-journey.md delete mode 100644 docs/helix/reference-apps/entity-directory/specs/03-test/test-plan.md delete mode 100644 docs/helix/reference-apps/evidence-library/.helix.yml delete mode 100644 docs/helix/reference-apps/evidence-library/AGENTS.md delete mode 100644 docs/helix/reference-apps/evidence-library/fixtures.json delete mode 100644 docs/helix/reference-apps/evidence-library/specs/01-frame/features/FEAT-104-business-journey.md delete mode 100644 docs/helix/reference-apps/evidence-library/specs/01-frame/prd.md delete mode 100644 docs/helix/reference-apps/evidence-library/specs/01-frame/user-stories/US-104-journey.md delete mode 100644 docs/helix/reference-apps/evidence-library/specs/03-test/test-plan.md delete mode 100644 docs/helix/reference-apps/knowledge-assistant/.helix.yml delete mode 100644 docs/helix/reference-apps/knowledge-assistant/AGENTS.md delete mode 100644 docs/helix/reference-apps/knowledge-assistant/fixtures.json delete mode 100644 docs/helix/reference-apps/knowledge-assistant/specs/01-frame/features/FEAT-107-business-journey.md delete mode 100644 docs/helix/reference-apps/knowledge-assistant/specs/01-frame/prd.md delete mode 100644 docs/helix/reference-apps/knowledge-assistant/specs/01-frame/user-stories/US-107-journey.md delete mode 100644 docs/helix/reference-apps/knowledge-assistant/specs/03-test/test-plan.md delete mode 100644 docs/helix/reference-apps/model-triage/.helix.yml delete mode 100644 docs/helix/reference-apps/model-triage/AGENTS.md delete mode 100644 docs/helix/reference-apps/model-triage/fixtures.json delete mode 100644 docs/helix/reference-apps/model-triage/specs/01-frame/features/FEAT-108-business-journey.md delete mode 100644 docs/helix/reference-apps/model-triage/specs/01-frame/prd.md delete mode 100644 docs/helix/reference-apps/model-triage/specs/01-frame/user-stories/US-108-journey.md delete mode 100644 docs/helix/reference-apps/model-triage/specs/03-test/test-plan.md delete mode 100644 docs/helix/reference-apps/scheduled-digest/.helix.yml delete mode 100644 docs/helix/reference-apps/scheduled-digest/AGENTS.md delete mode 100644 docs/helix/reference-apps/scheduled-digest/fixtures.json delete mode 100644 docs/helix/reference-apps/scheduled-digest/specs/01-frame/features/FEAT-110-business-journey.md delete mode 100644 docs/helix/reference-apps/scheduled-digest/specs/01-frame/prd.md delete mode 100644 docs/helix/reference-apps/scheduled-digest/specs/01-frame/user-stories/US-110-journey.md delete mode 100644 docs/helix/reference-apps/scheduled-digest/specs/03-test/test-plan.md delete mode 100644 docs/helix/reference-apps/service-handoff/.helix.yml delete mode 100644 docs/helix/reference-apps/service-handoff/AGENTS.md delete mode 100644 docs/helix/reference-apps/service-handoff/fixtures.json delete mode 100644 docs/helix/reference-apps/service-handoff/specs/01-frame/features/FEAT-112-business-journey.md delete mode 100644 docs/helix/reference-apps/service-handoff/specs/01-frame/prd.md delete mode 100644 docs/helix/reference-apps/service-handoff/specs/01-frame/user-stories/US-112-journey.md delete mode 100644 docs/helix/reference-apps/service-handoff/specs/03-test/test-plan.md delete mode 100644 docs/helix/reference-apps/service-intake/.helix.yml delete mode 100644 docs/helix/reference-apps/service-intake/AGENTS.md delete mode 100644 docs/helix/reference-apps/service-intake/fixtures.json delete mode 100644 docs/helix/reference-apps/service-intake/specs/01-frame/features/FEAT-102-business-journey.md delete mode 100644 docs/helix/reference-apps/service-intake/specs/01-frame/prd.md delete mode 100644 docs/helix/reference-apps/service-intake/specs/01-frame/user-stories/US-102-journey.md delete mode 100644 docs/helix/reference-apps/service-intake/specs/03-test/test-plan.md delete mode 100644 docs/helix/site/publication-evidence.json delete mode 100644 docs/helix/site/verification.json rename {docs/helix/reference-apps/approval-desk/specs/02-design/models => examples/approval-desk/model}/approval.umf.json (100%) delete mode 100644 scripts/browser_census.mjs rename scripts/{quality.py => check.py} (69%) delete mode 100644 scripts/check_micro_apps.py delete mode 100644 scripts/check_policy.py delete mode 100644 scripts/quality-baseline.json create mode 100644 tests/boundaries/test_boundaries.py delete mode 100644 tests/quality/test_gate.py diff --git a/.gitignore b/.gitignore index 3da7490..c117f34 100644 --- a/.gitignore +++ b/.gitignore @@ -13,3 +13,9 @@ build/ .cache/ .local/ + +# generated test output +test-results/ +playwright-report/ +**/evidence/ +*verification.json diff --git a/AGENTS.md b/AGENTS.md index 62a76dc..660f8d3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,70 +1,19 @@ # Working in Batten -Batten is an open-source application SDK in the Novirhyza family. Start with -`docs/helix/README.md`, the product vision, PRD, concerns, and relevant contracts. - -## Scope and handling - -- Use the installed HELIX skill. Read `.helix.yml`; keep project artifacts under - `docs/helix/` and resolve graph/templates/prompts/meta from the installed plugin. - Read governing artifacts before downstream work; preserve IDs, frontmatter, - deliberate trace links, and unknown extension content. -- MIT OR Apache-2.0; copyright Synaptiq. Use fabricated data only. No credentials, - tokens, token-shaped literals, private client material, or operational data. -- Cleanroom implementation: reference evidence informs behaviors and boundaries. - Do not copy private source, tests, documents, or git history. Do not depend on, - locate, or import a consuming application's internals. Source-specific audit - material stays outside this repository. -- Native UMF authoring and typed access are settled. Use public UMF, Weft, Arras, - and Tether dependencies; do not vendor or reimplement their engines. The - consuming host owns legacy compatibility. Qualify support by cohort, subset, - and observed evidence; make unsupported meaning and loss explicit. -- Plugins are trusted first-party code; containment limits permissions. Do not - claim hostile-code security. No new environment variables. Resolve typed file - configuration once at composition, with environment only as explicit fallback. -- Public I/O is async-first. Pure declarations/factories/planners may be sync. - PostgreSQL 18 is the only supported database major. -- Do not introduce a framework/runtime/dependency without a selected concern or - ADR. Follow the module ownership and import contracts. Pure core contains no - ontology-specific types or branches. - -## Review boundary and work items - -The current authorized delivery is genesis/framing artifacts, the boundary audit, -and the proposed split/ADRs/contracts. Wait for owner review before migration -planning or product code, including executable quality scaffolding. After review, -establish real checks before dependent source work. Build all specified behavior; -do not replace requirements with a list of omitted capabilities. - -Work items are project-scoped ddx beads, never GitHub issues. Run the CLI from -this repository with `DDX_BEAD_DIR="$PWD/.ddx" DDX_BEAD_PREFIX=batten` to select -this workspace. The installed CLI resolves its canonical project store outside -Git; the variable selects the workspace rather than forcing an in-tree store. -`docs/helix/01-frame/work-items.jsonl` is the review export, not a second live store. -Refresh it with `ddx --no-update-check bead export` after tracker changes. -Do not push, create a remote, or commit unless asked. A future requested commit -follows the owner's attribution instructions; no identity is invented. - -## Tests and quality - -- Use the fewest tests that pin behavior: one test per observable behavior, - asserting the whole outcome. Vary inputs with a table, not more test functions. -- Search existing tests first. Extend a covering scenario or parameter table. - Test public boundaries; add another layer only for a distinct observable outcome. -- Do not test language/type-checker guarantees, constructor defaults, incidental - wording, private helper structure, or a mock interaction with no observable effect. -- Preserve each distinct authorization, non-disclosure, isolation, ordering, - and concurrency invariant exactly once. Name behaviors and trace acceptance IDs. -- Consolidation removes duplicate code. Renamed former tests, helper wrappers, - hidden bodies, dynamic registration, and skipped tests do not evade the budget. -- The first reviewed behavioral suite establishes a measured function-count - ceiling. Afterward the count and ceiling only decrease; no automatic positive - growth exception. Preserve coverage while consolidating; do not weaken assertions. -- Database-process tests are integration tests; registry inventories are marked. - Keep the fast gate independent of database processes. Await observable state, - events, or controlled clocks; no test sleeps or blind browser retries. -- Enforce CONTRACT-002's global size/complexity/import/public-surface ceilings; - no per-file exception or suppression. Split by responsibility rather than raise - a limit. Local, edit, hook, and CI checks use the same gate. -- Installed-artifact/native/browser/deployed evidence are separate. Never call a - documented checker enforced, an offline double native, or an unrun check passing. +Batten is an application SDK: a UMF/Weft/PostgreSQL-backed local host, an ASGI +registry and an object store. Packages live in `packages/`, the example app in +`examples/approval-desk`. + +- Setup and checks: `uv sync --frozen --all-packages`, `bun install --frozen-lockfile`, + `uv run python scripts/check.py` (boundaries, ruff, pyright, oxlint, tsc, pytest). +- Integration and browser tests need native PostgreSQL via pgserver: + `uv run python scripts/prepare_approval.py`, `uv run pytest -m integration`, + `bun run test:native`. They run nightly in CI; run them locally only on macOS or + Linux with PostgreSQL on a Unix socket, never TCP 5432. +- Import boundaries (`scripts/boundary_model.py`, `scripts/public-api.json`): portable + packages must not import native or platform modules. Keep new public names in + `public-api.json`. +- Use fabricated data only; no credentials. MIT OR Apache-2.0. +- CI is the gate. Do not commit evidence, receipts, verification JSON or + qualification packets. `ROADMAP.md` lists what is not built; do not describe it as + supported. diff --git a/README.md b/README.md index 3366c39..8687bc1 100644 --- a/README.md +++ b/README.md @@ -17,10 +17,6 @@ The microsite explains the design. The first source implementation is the option [local object-storage package](packages/batten-storage/README.md); the complete application runtime remains in design. -Start with the [review packet](docs/helix/README.md), including the product -requirements, boundary audit, and proposed module/distribution split. The owner has authorized the local storage implementation. Broader runtime -implementation follows its governed contracts. - Dual licensed under [MIT](LICENSE-MIT) OR [Apache-2.0](LICENSE-APACHE). Copyright Synaptiq. @@ -31,7 +27,7 @@ workspace. Oxlint and TypeScript 7 supply the browser quality checks: ```sh uv sync --frozen --all-packages bun install --frozen-lockfile -uv run python scripts/quality.py +uv run python scripts/check.py ``` `just test` runs both the Python suite and the two JavaScript Playwright scenarios. @@ -40,13 +36,7 @@ provides the configured local pre-commit check. Product storage has no third-par runtime dependencies. Quality tools remain outside its wheel. -The [enterprise micro-app library](docs/helix/reference-apps/README.md) contains -independently HELIX-scoped app specifications and fabricated conformance fixtures. -Use the [Batten app workflow](docs/helix/04-build/batten-app-workflow.md) and -[integration queue](docs/helix/04-build/integration-gaps.md). Initial UI delivery -uses authored TypeScript apps; table and graph persistence integrate existing -UMF/PostgreSQL and UMF/Truss capabilities. These specs are qualification targets, -not twelve implemented apps. +What is not built is listed in the [roadmap](ROADMAP.md). ## Run the first reference application @@ -54,5 +44,5 @@ The [approval desk](examples/approval-desk/README.md) uses original UMF tables a Weft on a dedicated PostgreSQL 18 pgserver, a modular local Batten host and an authored TypeScript UI. Start with `just approval-prepare`, explicitly initialize with `just approval-init`, then run `just approval`. The installed app opens at -. Native/browser qualification is `just approval-test`; +. Browser tests run with `just approval-test`; `just check` stays independent of database processes. diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..628bd76 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,41 @@ +# Roadmap + +What Batten does today is in the [README](README.md). This file lists what is +designed but not built. Nothing here is a claim about the current release. + +## Not built yet + +- **Lintel GraphQL/Relay API.** A read API over the approval desk: a Lintel + execution port over `batten.umf_postgres.UmfTableProvider` (read-only + `get_many`), mounted by `batten.asgi.create_app` under + `/apps/approval-desk/graphql`. Batten host composition constructs the optional + adapter; generic core and ASGI code import neither Lintel nor GraphQL, and + resolvers never call providers around admission, permissions or audit. + Needs a Lintel release that ships its public build API. No dependency on + Lintel exists today. +- **Arras ontology provider.** There is no shared backend yet (Arras talks to + Truss; Batten uses UMF Access tables), so this stays a design. +- **Truss graph storage.** A UMF/Truss graph binding alongside the PostgreSQL + table binding. No dependency on Truss exists today. +- **Tether agent execution** and scoped retrieval. +- **ux-builder binding** for design artifacts. UI today is the authored + TypeScript app in `examples/approval-desk`. +- **Messaging, jobs and schedules** on PostgreSQL (CONTRACT-007 describes the + intended shape). +- **Remote object storage adapters.** Only the local filesystem store ships. +- **Production identity.** The local host uses loopback development identities. +- **More example apps.** Only the approval desk exists. Twelve were specified + (service intake, case tracker, evidence library, document review, entity + directory, knowledge assistant, inbox triage, data reconciliation, scheduled + digest, access attestation, service handoff); those specifications were + removed from the tree and remain in git history before the 0.1.0a3 reset. + +## Design records kept + +ADRs and contracts under `docs/helix/02-design/` describe the shipped packages +and the intended direction. ADR-005 (series/cohort compatibility), ADR-007 +(quality ratchets), ADR-014 (reference-app specifications), CONTRACT-002 +(boundaries and quality) and CONTRACT-011 (micro-app conformance) were removed: +the repository now has one version for all packages, plain CI instead of +ratchets, and no reference-app corpus. Remaining prose that cites those +identifiers is historical. diff --git a/docs/helix/00-discover/boundary-audit/external-nodes.csv b/docs/helix/00-discover/boundary-audit/external-nodes.csv deleted file mode 100644 index 53ca0d4..0000000 --- a/docs/helix/00-discover/boundary-audit/external-nodes.csv +++ /dev/null @@ -1,157 +0,0 @@ -module_id,classification -X001,standard library or external package -X002,standard library or external package -X003,standard library or external package -X004,standard library or external package -X005,standard library or external package -X006,standard library or external package -X007,standard library or external package -X008,standard library or external package -X009,standard library or external package -X010,standard library or external package -X011,standard library or external package -X012,standard library or external package -X013,standard library or external package -X014,standard library or external package -X015,standard library or external package -X016,standard library or external package -X017,standard library or external package -X018,standard library or external package -X019,standard library or external package -X020,standard library or external package -X021,standard library or external package -X022,standard library or external package -X023,standard library or external package -X024,standard library or external package -X025,standard library or external package -X026,standard library or external package -X027,standard library or external package -X028,standard library or external package -X029,standard library or external package -X030,standard library or external package -X031,standard library or external package -X032,standard library or external package -X033,standard library or external package -X034,standard library or external package -X035,standard library or external package -X036,standard library or external package -X037,standard library or external package -X038,standard library or external package -X039,standard library or external package -X040,standard library or external package -X041,standard library or external package -X042,standard library or external package -X043,standard library or external package -X044,standard library or external package -X045,standard library or external package -X046,standard library or external package -X047,standard library or external package -X048,standard library or external package -X049,standard library or external package -X050,standard library or external package -X051,standard library or external package -X052,standard library or external package -X053,reference-host outside selected modules -X054,reference-host outside selected modules -X055,reference-host outside selected modules -X056,reference-host outside selected modules -X057,reference-host outside selected modules -X058,reference-host outside selected modules -X059,reference-host outside selected modules -X060,reference-host outside selected modules -X061,reference-host outside selected modules -X062,reference-host outside selected modules -X063,reference-host outside selected modules -X064,reference-host outside selected modules -X065,reference-host outside selected modules -X066,reference-host outside selected modules -X067,reference-host outside selected modules -X068,reference-host outside selected modules -X069,reference-host outside selected modules -X070,reference-host outside selected modules -X071,reference-host outside selected modules -X072,reference-host outside selected modules -X073,reference-host outside selected modules -X074,reference-host outside selected modules -X075,reference-host outside selected modules -X076,reference-host outside selected modules -X077,reference-host outside selected modules -X078,reference-host outside selected modules -X079,reference-host outside selected modules -X080,reference-host outside selected modules -X081,reference-host outside selected modules -X082,reference-host outside selected modules -X083,reference-host outside selected modules -X084,reference-host outside selected modules -X085,reference-host outside selected modules -X086,reference-host outside selected modules -X087,reference-host outside selected modules -X088,reference-host outside selected modules -X089,reference-host outside selected modules -X090,reference-host outside selected modules -X091,reference-host outside selected modules -X092,reference-host outside selected modules -X093,reference-host outside selected modules -X094,reference-host outside selected modules -X095,reference-host outside selected modules -X096,reference-host outside selected modules -X097,reference-host outside selected modules -X098,reference-host outside selected modules -X099,reference-host outside selected modules -X100,reference-host outside selected modules -X101,reference-host outside selected modules -X102,reference-host outside selected modules -X103,reference-host outside selected modules -X104,reference-host outside selected modules -X105,reference-host outside selected modules -X106,reference-host outside selected modules -X107,reference-host outside selected modules -X108,reference-host outside selected modules -X109,reference-host outside selected modules -X110,reference-host outside selected modules -X111,reference-host outside selected modules -X112,standard library or external package -X113,standard library or external package -X114,standard library or external package -X115,standard library or external package -X116,standard library or external package -X117,standard library or external package -X118,standard library or external package -X119,standard library or external package -X120,standard library or external package -X121,standard library or external package -X122,standard library or external package -X123,standard library or external package -X124,standard library or external package -X125,standard library or external package -X126,standard library or external package -X127,standard library or external package -X128,standard library or external package -X129,standard library or external package -X130,standard library or external package -X131,standard library or external package -X132,standard library or external package -X133,standard library or external package -X134,standard library or external package -X135,standard library or external package -X136,standard library or external package -X137,standard library or external package -X138,standard library or external package -X139,standard library or external package -X140,standard library or external package -X141,standard library or external package -X142,standard library or external package -X143,standard library or external package -X144,standard library or external package -X145,standard library or external package -X146,standard library or external package -X147,standard library or external package -X148,standard library or external package -X149,standard library or external package -D001,computed runtime target; observation required -D002,computed runtime target; observation required -D004,literal dynamic target -D005,computed runtime target; observation required -D006,computed runtime target; observation required -D007,computed runtime target; observation required -D008,computed runtime target; observation required diff --git a/docs/helix/00-discover/boundary-audit/import-graph.csv b/docs/helix/00-discover/boundary-audit/import-graph.csv deleted file mode 100644 index 544d9c8..0000000 --- a/docs/helix/00-discover/boundary-audit/import-graph.csv +++ /dev/null @@ -1,2368 +0,0 @@ -source_id,target_id,source_line,kind,target_in_survey -M001,M002,4,static,True -M001,M004,5,static,True -M001,M006,6,static,True -M001,M007,7,static,True -M001,M011,12,static,True -M001,M020,21,static,True -M001,M023,22,static,True -M001,M024,23,static,True -M001,M027,24,static,True -M001,M029,25,static,True -M001,M040,26,static,True -M001,M044,36,static,True -M001,M050,42,static,True -M001,M052,43,static,True -M001,M053,44,static,True -M001,M055,50,static,True -M001,M059,59,static,True -M001,M076,60,static,True -M001,M095,61,static,True -M001,M096,68,static,True -M001,M117,69,static,True -M002,X021,8,static,False -M002,M011,10,static,True -M002,M019,11,static,True -M003,X002,13,static,False -M003,X044,14,static,False -M003,X132,15,static,False -M003,X008,16,static,False -M003,X050,17,static,False -M003,X139,18,static,False -M003,M010,20,static,True -M003,M008,21,static,True -M003,M008,22,static,True -M003,M015,23,static,True -M003,M017,24,static,True -M003,M022,25,static,True -M003,M025,26,static,True -M003,M032,27,static,True -M003,M033,28,static,True -M003,M034,29,static,True -M003,M036,30,static,True -M003,M038,31,static,True -M003,M054,32,static,True -M003,M095,33,static,True -M003,M097,34,static,True -M004,X021,13,static,False -M004,X022,14,static,False -M004,X043,15,static,False -M004,M011,17,static,True -M005,X120,28,static,False -M005,X008,29,static,False -M005,X021,30,static,False -M005,X139,31,static,False -M005,M011,33,static,True -M005,M021,34,static,True -M005,M058,44,static,True -M006,X120,24,static,False -M006,X008,25,static,False -M006,X021,26,static,False -M006,X139,27,static,False -M006,M005,29,static,True -M006,M011,30,static,True -M006,M019,31,static,True -M007,X120,17,static,False -M007,X008,18,static,False -M007,X021,19,static,False -M007,X139,20,static,False -M007,M011,22,static,True -M008,X002,17,static,False -M008,X044,18,static,False -M008,X049,19,static,False -M008,X123,20,static,False -M008,X124,21,static,False -M008,X131,22,static,False -M008,X132,23,static,False -M008,X008,24,static,False -M008,X021,25,static,False -M008,X050,26,static,False -M008,X139,27,static,False -M008,M017,29,static,True -M008,M036,30,static,True -M008,M037,31,static,True -M009,X002,5,static,False -M009,X021,6,static,False -M009,X120,7,static,False -M009,X139,8,static,False -M009,M003,51,static,True -M009,M055,83,static,True -M010,X024,11,static,False -M010,X120,12,static,False -M010,X021,13,static,False -M010,X036,14,static,False -M010,X038,15,static,False -M010,X050,16,static,False -M010,M009,18,static,True -M011,X139,8,static,False -M012,X008,22,static,False -M012,X011,23,static,False -M012,X021,24,static,False -M012,X139,25,static,False -M012,M011,27,static,True -M012,M019,28,static,True -M012,M047,29,static,True -M013,M014,7,static,True -M013,M015,8,static,True -M013,M016,9,static,True -M013,M017,10,static,True -M014,X024,3,static,False -M014,X030,4,static,False -M014,M016,6,static,True -M015,X002,3,static,False -M015,X044,4,static,False -M015,X132,5,static,False -M015,X008,6,static,False -M015,M014,8,static,True -M015,M016,9,static,True -M016,X120,15,static,False -M016,X021,16,static,False -M016,X036,17,static,False -M017,X008,3,static,False -M017,X139,4,static,False -M017,M014,6,static,True -M018,X031,29,static,False -M018,X008,30,static,False -M018,X011,31,static,False -M018,X021,32,static,False -M018,X139,33,static,False -M018,M011,35,static,True -M019,X120,9,static,False -M019,X008,10,static,False -M019,M011,12,static,True -M020,X021,9,static,False -M020,X139,10,static,False -M020,M004,12,static,True -M020,M007,13,static,True -M020,M011,14,static,True -M020,M019,15,static,True -M020,M085,23,static,True -M021,X005,13,static,False -M021,X006,14,static,False -M021,X044,15,static,False -M021,X120,16,static,False -M021,X008,17,static,False -M021,X022,18,static,False -M021,X023,19,static,False -M021,X139,20,static,False -M021,X143,21,static,False -M022,X002,20,static,False -M022,X031,21,static,False -M022,X044,22,static,False -M022,X132,23,static,False -M022,X050,24,static,False -M022,M011,26,static,True -M022,M017,27,static,True -M022,M036,28,static,True -M022,M038,29,static,True -M022,M097,30,static,True -M023,X046,15,static,False -M023,X134,16,static,False -M023,X135,17,static,False -M023,X008,18,static,False -M023,X011,19,static,False -M023,X021,20,static,False -M023,X139,21,static,False -M023,M011,23,static,True -M023,M019,24,static,True -M024,X044,18,static,False -M024,X021,19,static,False -M024,X139,20,static,False -M024,M011,22,static,True -M024,M019,23,static,True -M024,M020,33,static,True -M024,M027,34,static,True -M024,M040,35,static,True -M024,M050,36,static,True -M024,M055,37,static,True -M024,M056,38,static,True -M024,M096,39,static,True -M025,X002,12,static,False -M025,X044,13,static,False -M025,X132,14,static,False -M025,X050,15,static,False -M025,M017,17,static,True -M025,M024,18,static,True -M025,M036,19,static,True -M025,M037,20,static,True -M025,M078,21,static,True -M025,M081,30,static,True -M025,M082,31,static,True -M025,M086,32,static,True -M025,M088,33,static,True -M025,M092,34,static,True -M026,X008,26,static,False -M026,X021,27,static,False -M026,X139,28,static,False -M026,M011,30,static,True -M027,X044,19,static,False -M027,X008,20,static,False -M027,X021,21,static,False -M027,X139,22,static,False -M027,M011,24,static,True -M027,M019,25,static,True -M028,X005,17,static,False -M028,X006,18,static,False -M028,X044,19,static,False -M028,X120,20,static,False -M028,X008,21,static,False -M028,X021,22,static,False -M028,X139,23,static,False -M029,X005,29,static,False -M029,X006,30,static,False -M029,X120,31,static,False -M029,X008,32,static,False -M029,X021,33,static,False -M029,X022,34,static,False -M029,X139,35,static,False -M029,M011,37,static,True -M030,X139,13,static,False -M031,M032,4,static,True -M031,M033,5,static,True -M031,M035,6,static,True -M031,M036,7,static,True -M031,M037,8,static,True -M031,M038,15,static,True -M032,X124,10,static,False -M032,X131,11,static,False -M032,X008,12,static,False -M032,X021,13,static,False -M032,X050,14,static,False -M032,X139,15,static,False -M032,M033,17,static,True -M032,M034,18,static,True -M032,M035,19,static,True -M032,M036,20,static,True -M032,M037,21,static,True -M032,M038,22,static,True -M032,M039,23,static,True -M032,M095,24,static,True -M033,X021,13,static,False -M033,X050,14,static,False -M033,M011,16,static,True -M033,M024,17,static,True -M033,M034,18,static,True -M033,M035,29,static,True -M033,M036,37,static,True -M033,M037,43,static,True -M033,M038,49,static,True -M033,M055,50,static,True -M033,M095,51,static,True -M034,X003,25,static,False -M034,X031,26,static,False -M034,X044,27,static,False -M034,X120,28,static,False -M034,X008,29,static,False -M034,X036,30,static,False -M034,X050,31,static,False -M034,X139,32,static,False -M034,M027,34,static,True -M034,M036,35,static,True -M034,M037,36,static,True -M034,M040,37,static,True -M034,M049,38,static,True -M034,M050,39,static,True -M034,M055,40,static,True -M034,M078,41,static,True -M034,M081,42,static,True -M034,M086,43,static,True -M034,M088,44,static,True -M034,M092,45,static,True -M034,M096,46,static,True -M034,M117,47,static,True -M034,M025,225,static,True -M034,X033,266,static,False -M034,X034,267,static,False -M035,X003,12,static,False -M035,X031,13,static,False -M035,X008,14,static,False -M035,X050,15,static,False -M035,M011,17,static,True -M035,M024,18,static,True -M035,M036,19,static,True -M036,X021,8,static,False -M036,X139,9,static,False -M036,M011,11,static,True -M037,X036,9,static,False -M037,X120,10,static,False -M037,X132,11,static,False -M037,X136,12,static,False -M037,X008,13,static,False -M037,X021,14,static,False -M037,X050,15,static,False -M037,M011,17,static,True -M037,M024,18,static,True -M037,M036,25,static,True -M037,M055,26,static,True -M038,X005,7,static,False -M038,X010,8,static,False -M038,X014,9,static,False -M038,X031,10,static,False -M038,X041,11,static,False -M038,X120,12,static,False -M038,X148,13,static,False -M038,X021,14,static,False -M038,X025,15,static,False -M038,X050,16,static,False -M038,M011,18,static,True -M038,M024,19,static,True -M038,M035,20,static,True -M038,M036,21,static,True -M038,M037,27,static,True -M038,M095,28,static,True -M039,X148,8,static,False -M039,X008,9,static,False -M039,X021,10,static,False -M039,X050,11,static,False -M039,M024,13,static,True -M039,M038,14,static,True -M039,M095,15,static,True -M040,X008,54,static,False -M040,X021,55,static,False -M040,M011,57,static,True -M040,M019,58,static,True -M041,X139,14,static,False -M041,M011,16,static,True -M041,M012,17,static,True -M041,M040,18,static,True -M041,M052,19,static,True -M041,M059,20,static,True -M042,X008,9,static,False -M042,X139,10,static,False -M042,M011,12,static,True -M042,M052,13,static,True -M042,M059,14,static,True -M043,X005,30,static,False -M043,X044,31,static,False -M043,X008,32,static,False -M043,X021,33,static,False -M043,X139,34,static,False -M043,M011,36,static,True -M044,X008,45,static,False -M044,X021,46,static,False -M044,X139,47,static,False -M044,M005,49,static,True -M044,M011,50,static,True -M044,M012,51,static,True -M044,M018,52,static,True -M044,M026,53,static,True -M044,M047,54,static,True -M044,M051,55,static,True -M044,M052,56,static,True -M044,M053,57,static,True -M044,M058,58,static,True -M044,M059,59,static,True -M045,M046,4,static,True -M045,M047,14,static,True -M046,X045,10,static,False -M046,X120,11,static,False -M046,X008,12,static,False -M046,X021,13,static,False -M046,X139,14,static,False -M046,M011,16,static,True -M046,M019,17,static,True -M047,X046,13,static,False -M047,X008,14,static,False -M047,X021,15,static,False -M047,X139,16,static,False -M047,M011,18,static,True -M047,M020,19,static,True -M048,X021,14,static,False -M048,X040,15,static,False -M048,X120,16,static,False -M048,X138,17,static,False -M048,X139,18,static,False -M048,X008,19,static,False -M048,M040,21,static,True -M048,M044,22,static,True -M048,M055,23,static,True -M049,X120,18,static,False -M049,X139,19,static,False -M049,X146,20,static,False -M050,X120,28,static,False -M050,X021,29,static,False -M050,X139,30,static,False -M050,M011,32,static,True -M050,M019,33,static,True -M050,M049,34,static,True -M051,X005,25,static,False -M051,X031,26,static,False -M051,X044,27,static,False -M051,X120,28,static,False -M051,X008,29,static,False -M051,X021,30,static,False -M051,X139,31,static,False -M051,M011,33,static,True -M051,M019,34,static,True -M051,M040,35,static,True -M052,X120,23,static,False -M052,X008,24,static,False -M052,X021,25,static,False -M052,X139,26,static,False -M052,M011,28,static,True -M052,M019,29,static,True -M053,X046,17,static,False -M053,X120,18,static,False -M053,X008,19,static,False -M053,X021,20,static,False -M053,X139,21,static,False -M053,M011,23,static,True -M054,X002,26,static,False -M054,X044,27,static,False -M054,X132,28,static,False -M054,X008,29,static,False -M054,X021,30,static,False -M054,X050,31,static,False -M054,X139,32,static,False -M054,M011,34,static,True -M054,M017,35,static,True -M054,M022,36,static,True -M054,M036,37,static,True -M054,M037,38,static,True -M054,M038,39,static,True -M054,M040,40,static,True -M054,M042,46,static,True -M054,M052,47,static,True -M054,M053,48,static,True -M055,X008,14,static,False -M055,X021,15,static,False -M055,X139,16,static,False -M055,M002,18,static,True -M055,M006,19,static,True -M055,M011,20,static,True -M055,M019,21,static,True -M055,M020,36,static,True -M055,M027,37,static,True -M055,M029,38,static,True -M055,M040,39,static,True -M055,M041,40,static,True -M055,M044,41,static,True -M055,M050,42,static,True -M055,M051,43,static,True -M055,M052,44,static,True -M055,M053,45,static,True -M055,M058,46,static,True -M055,M059,47,static,True -M055,M076,48,static,True -M055,M096,49,static,True -M055,M117,50,static,True -M056,X031,26,static,False -M056,X044,27,static,False -M056,X008,28,static,False -M056,X021,29,static,False -M056,X139,30,static,False -M056,M002,32,static,True -M056,M006,33,static,True -M056,M007,34,static,True -M056,M011,35,static,True -M056,M020,36,static,True -M056,M027,37,static,True -M056,M029,38,static,True -M056,M040,39,static,True -M056,M042,40,static,True -M056,M050,41,static,True -M056,M051,42,static,True -M056,M053,43,static,True -M056,M055,44,static,True -M056,M058,45,static,True -M056,M076,46,static,True -M056,M096,47,static,True -M056,M117,48,static,True -M057,X008,25,static,False -M057,X139,26,static,False -M057,M021,28,static,True -M057,M058,38,static,True -M058,X008,33,static,False -M058,X021,34,static,False -M058,X139,35,static,False -M058,M011,37,static,True -M059,X046,31,static,False -M059,X120,32,static,False -M059,X134,33,static,False -M059,X135,34,static,False -M059,X008,35,static,False -M059,X011,36,static,False -M059,X012,37,static,False -M059,X021,38,static,False -M059,X139,39,static,False -M059,M011,41,static,True -M059,M019,42,static,True -M060,M023,17,static,True -M060,M061,18,static,True -M060,M062,19,static,True -M060,M063,20,static,True -M060,M064,21,static,True -M060,M065,22,static,True -M060,M066,30,static,True -M060,M067,37,static,True -M060,M068,38,static,True -M060,M069,39,static,True -M060,M070,40,static,True -M060,M071,48,static,True -M060,M072,56,static,True -M060,M073,57,static,True -M060,M074,58,static,True -M060,M075,59,static,True -M061,X008,10,static,False -M061,X021,11,static,False -M061,X139,12,static,False -M061,M002,14,static,True -M061,M055,15,static,True -M062,X008,11,static,False -M062,X011,12,static,False -M062,X139,13,static,False -M063,X120,11,static,False -M063,X008,12,static,False -M063,X011,13,static,False -M063,X021,14,static,False -M063,X139,15,static,False -M063,M011,17,static,True -M063,M019,18,static,True -M063,M023,19,static,True -M063,M043,26,static,True -M063,M058,27,static,True -M063,M061,28,static,True -M063,M062,29,static,True -M063,M064,30,static,True -M063,M070,31,static,True -M063,M074,32,static,True -M064,X008,25,static,False -M064,X021,26,static,False -M064,X139,27,static,False -M064,M005,29,static,True -M064,M021,37,static,True -M064,M058,38,static,True -M064,M066,39,static,True -M065,X008,10,static,False -M065,X021,11,static,False -M065,X139,12,static,False -M065,M023,14,static,True -M065,M053,15,static,True -M065,M055,16,static,True -M065,M061,17,static,True -M065,M062,18,static,True -M065,M063,19,static,True -M065,M064,20,static,True -M065,M067,21,static,True -M065,M068,22,static,True -M065,M069,23,static,True -M065,M070,24,static,True -M065,M071,25,static,True -M065,M073,26,static,True -M065,M074,27,static,True -M066,X139,10,static,False -M067,X041,12,static,False -M067,X008,13,static,False -M067,X011,14,static,False -M067,X021,15,static,False -M067,X022,16,static,False -M067,X139,17,static,False -M067,M018,19,static,True -M067,M040,29,static,True -M067,M055,30,static,True -M068,X044,10,static,False -M068,X008,11,static,False -M068,X021,12,static,False -M068,X139,13,static,False -M068,M011,15,static,True -M068,M019,16,static,True -M068,M020,17,static,True -M068,M047,18,static,True -M068,M055,26,static,True -M069,X046,14,static,False -M069,X120,15,static,False -M069,X149,16,static,False -M069,X008,17,static,False -M069,X021,18,static,False -M069,M026,20,static,True -M069,M040,37,static,True -M069,M055,38,static,True -M070,X013,20,static,False -M070,X007,21,static,False -M070,X008,22,static,False -M070,X011,23,static,False -M070,X021,24,static,False -M070,X139,25,static,False -M070,M028,27,static,True -M070,M066,38,static,True -M071,X008,19,static,False -M071,X011,20,static,False -M071,X021,21,static,False -M071,X139,22,static,False -M071,M012,24,static,True -M071,M040,25,static,True -M071,M047,26,static,True -M071,M052,33,static,True -M071,M055,34,static,True -M071,M059,35,static,True -M071,M062,41,static,True -M072,M044,12,static,True -M072,M065,13,static,True -M073,X120,15,static,False -M073,X008,16,static,False -M073,X021,17,static,False -M073,X139,18,static,False -M073,M040,20,static,True -M073,M051,21,static,True -M073,M055,33,static,True -M074,X120,20,static,False -M074,X008,21,static,False -M074,X021,22,static,False -M074,X139,23,static,False -M074,M040,25,static,True -M074,M055,26,static,True -M074,M057,27,static,True -M074,M057,35,static,True -M074,M058,38,static,True -M075,X044,16,static,False -M075,X008,17,static,False -M075,X050,18,static,False -M075,X139,19,static,False -M075,M011,21,static,True -M075,M029,22,static,True -M075,M055,23,static,True -M075,M096,24,static,True -M076,X120,28,static,False -M076,X021,29,static,False -M076,M011,31,static,True -M077,M078,5,static,True -M077,M079,11,static,True -M077,M080,17,static,True -M077,M081,20,static,True -M077,M082,21,static,True -M077,M083,22,static,True -M077,M084,23,static,True -M077,M085,30,static,True -M077,M086,47,static,True -M077,M088,53,static,True -M077,M089,54,static,True -M077,M091,55,static,True -M077,M092,56,static,True -M078,X120,13,static,False -M078,X008,14,static,False -M078,X021,15,static,False -M078,M081,17,static,True -M078,M082,18,static,True -M078,M083,19,static,True -M078,M084,26,static,True -M078,M085,32,static,True -M078,M088,33,static,True -M078,M093,34,static,True -M079,X008,10,static,False -M079,M081,12,static,True -M079,M085,13,static,True -M079,M093,14,static,True -M079,M094,24,static,True -M080,M085,10,static,True -M080,M087,18,static,True -M080,M090,29,static,True -M081,X021,8,static,False -M081,X139,9,static,False -M082,X021,8,static,False -M082,M079,10,static,True -M082,M081,11,static,True -M082,M083,12,static,True -M082,M084,13,static,True -M082,M085,14,static,True -M082,M088,15,static,True -M082,M089,16,static,True -M083,X139,12,static,False -M083,M079,14,static,True -M083,M081,15,static,True -M083,M084,16,static,True -M083,M085,17,static,True -M083,M090,18,static,True -M083,M093,29,static,True -M083,M094,42,static,True -M084,X031,11,static,False -M084,X120,12,static,False -M084,X021,13,static,False -M084,X139,14,static,False -M084,M081,16,static,True -M084,M094,17,static,True -M085,X021,7,static,False -M085,X139,8,static,False -M085,M081,10,static,True -M086,X008,13,static,False -M086,X021,14,static,False -M086,X050,15,static,False -M086,M081,17,static,True -M086,M085,18,static,True -M086,M088,19,static,True -M087,X031,8,static,False -M087,M085,10,static,True -M088,X046,10,static,False -M088,X120,11,static,False -M088,X008,12,static,False -M088,X030,13,static,False -M088,X139,14,static,False -M088,M080,16,static,True -M088,M081,17,static,True -M088,M084,18,static,True -M088,M085,19,static,True -M088,M087,31,static,True -M088,M092,32,static,True -M088,X147,77,static,False -M088,X147,43,static,False -M089,X021,12,static,False -M089,M080,14,static,True -M089,M084,27,static,True -M089,M085,28,static,True -M089,M087,38,static,True -M089,M090,45,static,True -M090,X008,48,static,False -M090,X021,49,static,False -M090,X139,50,static,False -M090,M085,52,static,True -M090,M087,60,static,True -M090,M091,61,static,True -M091,M087,17,static,True -M091,M094,18,static,True -M092,X120,47,static,False -M092,X008,48,static,False -M092,X021,49,static,False -M092,X139,50,static,False -M092,M081,52,static,True -M092,M085,53,static,True -M092,M087,66,static,True -M092,M090,67,static,True -M093,X021,8,static,False -M093,X139,9,static,False -M093,M081,11,static,True -M093,M094,12,static,True -M094,X120,12,static,False -M094,X021,13,static,False -M094,X139,14,static,False -M094,M081,16,static,True -M095,X021,9,static,False -M095,X139,10,static,False -M095,M011,12,static,True -M095,M019,13,static,True -M096,X120,21,static,False -M096,X021,22,static,False -M096,M011,24,static,True -M096,M019,25,static,True -M097,X044,20,static,False -M097,X049,21,static,False -M097,X124,22,static,False -M097,X140,23,static,False -M097,X141,24,static,False -M097,X142,25,static,False -M097,X021,26,static,False -M097,X050,27,static,False -M097,X139,28,static,False -M098,M101,14,static,True -M098,M107,22,static,True -M098,M108,23,static,True -M099,X044,6,static,False -M099,X132,7,static,False -M099,M108,10,static,True -M100,X044,8,static,False -M100,X049,9,static,False -M100,X132,10,static,False -M100,X008,11,static,False -M100,X139,12,static,False -M100,M011,14,static,True -M100,M043,15,static,True -M101,X044,16,static,False -M101,X008,17,static,False -M101,X011,18,static,False -M101,X021,19,static,False -M101,X139,20,static,False -M101,M005,22,static,True -M101,M011,23,static,True -M101,M019,24,static,True -M101,M023,25,static,True -M101,M058,26,static,True -M101,M100,27,static,True -M101,M115,28,static,True -M102,X005,13,static,False -M102,X006,14,static,False -M102,X031,15,static,False -M102,X032,16,static,False -M102,X044,17,static,False -M102,X135,18,static,False -M102,X008,19,static,False -M102,X021,20,static,False -M102,X139,21,static,False -M102,M053,23,static,True -M103,X044,20,static,False -M103,X008,21,static,False -M103,X011,22,static,False -M103,X012,23,static,False -M103,X139,24,static,False -M103,M011,26,static,True -M103,M012,27,static,True -M103,M043,28,static,True -M103,M047,29,static,True -M103,M055,35,static,True -M103,M101,36,static,True -M103,M102,37,static,True -M103,M109,38,static,True -M103,M114,39,static,True -M103,M116,40,static,True -M104,X008,12,static,False -M104,X021,13,static,False -M104,X139,14,static,False -M104,M040,16,static,True -M104,M040,17,static,True -M104,M040,18,static,True -M104,M040,19,static,True -M104,M055,20,static,True -M105,X008,11,static,False -M105,X139,12,static,False -M105,M011,14,static,True -M105,M047,15,static,True -M105,M101,22,static,True -M106,X046,12,static,False -M106,X121,13,static,False -M106,X135,14,static,False -M106,X008,15,static,False -M107,X049,8,static,False -M107,X120,9,static,False -M107,X137,10,static,False -M107,X008,11,static,False -M107,X037,12,static,False -M107,X139,13,static,False -M107,M011,15,static,True -M107,M024,16,static,True -M107,M055,17,static,True -M107,M056,18,static,True -M108,X049,17,static,False -M108,X132,18,static,False -M108,X008,19,static,False -M108,X139,20,static,False -M108,M011,22,static,True -M108,M043,23,static,True -M108,M055,24,static,True -M108,M106,25,static,True -M108,M100,26,static,True -M108,M101,27,static,True -M108,M107,28,static,True -M108,M111,35,static,True -M109,X044,20,static,False -M109,X120,21,static,False -M109,X021,22,static,False -M109,X139,23,static,False -M109,X141,24,static,False -M109,M043,26,static,True -M109,M055,27,static,True -M109,M058,28,static,True -M109,M102,29,static,True -M109,M114,30,static,True -M109,M116,31,static,True -M110,X005,13,static,False -M110,X041,14,static,False -M110,X008,15,static,False -M110,X011,16,static,False -M110,X139,17,static,False -M110,M011,19,static,True -M110,M018,20,static,True -M110,M026,26,static,True -M110,M051,34,static,True -M110,M101,41,static,True -M111,X132,14,static,False -M111,X139,15,static,False -M111,M011,17,static,True -M111,M043,18,static,True -M111,M055,19,static,True -M111,M106,20,static,True -M111,M100,21,static,True -M111,M101,22,static,True -M111,M102,23,static,True -M111,M103,24,static,True -M111,M109,25,static,True -M111,M113,26,static,True -M111,M116,27,static,True -M112,X008,13,static,False -M112,X011,14,static,False -M112,X139,15,static,False -M112,M011,17,static,True -M112,M052,18,static,True -M112,M059,19,static,True -M112,M101,20,static,True -M113,X008,14,static,False -M113,X021,15,static,False -M113,X139,16,static,False -M113,M011,18,static,True -M113,M044,19,static,True -M113,M053,20,static,True -M113,M101,21,static,True -M113,M102,22,static,True -M113,M103,23,static,True -M113,M105,24,static,True -M113,M110,25,static,True -M113,M112,26,static,True -M113,M115,27,static,True -M114,X044,7,static,False -M114,X139,8,static,False -M114,M030,10,static,True -M114,M043,11,static,True -M114,M055,12,static,True -M114,M116,13,static,True -M115,X008,11,static,False -M115,X139,12,static,False -M115,M011,14,static,True -M115,M058,15,static,True -M115,M100,22,static,True -M116,X004,12,static,False -M116,X036,13,static,False -M116,X044,14,static,False -M116,X139,15,static,False -M116,M043,17,static,True -M116,M055,18,static,True -M116,M102,19,static,True -M116,M104,20,static,True -M117,X044,25,static,False -M117,X120,26,static,False -M117,X136,27,static,False -M117,X008,28,static,False -M117,X021,29,static,False -M117,X050,30,static,False -M117,M011,32,static,True -M117,M019,33,static,True -M119,X132,3,static,False -M119,M121,5,static,True -M120,X044,17,static,False -M120,X049,18,static,False -M120,X050,19,static,False -M120,X026,21,static,False -M120,M011,22,static,True -M120,X129,23,static,False -M120,M122,25,static,True -M120,M124,26,static,True -M120,M127,27,static,True -M120,M135,28,static,True -M120,M137,29,static,True -M120,X037,59,static,False -M120,M221,61,static,True -M120,X075,70,static,False -M121,X002,11,static,False -M121,X049,12,static,False -M121,X125,13,static,False -M121,X132,14,static,False -M121,X008,15,static,False -M121,X050,16,static,False -M121,X139,17,static,False -M121,M118,19,static,True -M121,M136,22,static,True -M121,M136,39,static,True -M121,M136,47,static,True -M121,M129,53,static,True -M121,M129,59,static,True -M121,M135,60,static,True -M121,M128,66,static,True -M121,M128,72,static,True -M121,M134,127,static,True -M122,X120,13,static,False -M122,X136,14,static,False -M122,X008,15,static,False -M122,X021,16,static,False -M122,X050,17,static,False -M122,X139,18,static,False -M122,M131,20,static,True -M122,M134,21,static,True -M122,M137,22,static,True -M123,X044,15,static,False -M123,X131,16,static,False -M123,X050,17,static,False -M123,M134,19,static,True -M123,M135,20,static,True -M123,X061,83,static,False -M123,X061,91,static,False -M123,X052,50,static,False -M123,X051,80,static,False -M124,X044,30,static,False -M124,X049,31,static,False -M124,X008,32,static,False -M124,X021,33,static,False -M124,X036,34,static,False -M124,X050,35,static,False -M124,M122,37,static,True -M124,M135,38,static,True -M124,M137,39,static,True -M124,M184,59,static,True -M124,M222,60,static,True -M125,X008,12,static,False -M125,X021,13,static,False -M125,M053,15,static,True -M125,M054,16,static,True -M125,M122,24,static,True -M125,M132,25,static,True -M125,M134,26,static,True -M125,M202,51,static,True -M126,X002,10,static,False -M126,X049,11,static,False -M126,X132,12,static,False -M126,X144,14,static,False -M126,M131,16,static,True -M126,X053,29,static,False -M126,X063,30,static,False -M126,X074,31,static,False -M127,X044,24,static,False -M127,X008,25,static,False -M127,X035,26,static,False -M127,X001,28,static,False -M127,X129,29,static,False -M127,M122,31,static,True -M127,M131,32,static,True -M128,X044,10,static,False -M128,X007,11,static,False -M128,X050,12,static,False -M128,X139,13,static,False -M128,M129,15,static,True -M128,M133,16,static,True -M128,M134,17,static,True -M128,M135,18,static,True -M129,X049,15,static,False -M129,X125,16,static,False -M129,X131,17,static,False -M129,X132,18,static,False -M129,X134,19,static,False -M129,X008,20,static,False -M129,X139,21,static,False -M129,M122,23,static,True -M129,M123,24,static,True -M129,M130,25,static,True -M129,M134,26,static,True -M129,M135,27,static,True -M129,M136,28,static,True -M130,X039,9,static,False -M130,X049,10,static,False -M130,X132,11,static,False -M130,X050,12,static,False -M131,X042,8,static,False -M131,X126,9,static,False -M132,X031,11,static,False -M132,X124,12,static,False -M132,X148,13,static,False -M132,X008,14,static,False -M132,X021,15,static,False -M132,X050,16,static,False -M132,X139,17,static,False -M132,M032,19,static,True -M132,M038,20,static,True -M132,M054,21,static,True -M132,M134,23,static,True -M132,M135,24,static,True -M133,X044,9,static,False -M133,X140,10,static,False -M133,X142,11,static,False -M133,X021,12,static,False -M133,X139,13,static,False -M133,M131,15,static,True -M133,M134,16,static,True -M134,X044,4,static,False -M134,X132,5,static,False -M134,X008,6,static,False -M134,X139,7,static,False -M134,M008,9,static,True -M134,M017,10,static,True -M135,X044,19,static,False -M135,X049,20,static,False -M135,X124,21,static,False -M135,X008,22,static,False -M135,X021,23,static,False -M135,X050,24,static,False -M135,X139,25,static,False -M135,X112,27,static,False -M135,M134,29,static,True -M136,X049,13,static,False -M136,X125,14,static,False -M136,X131,15,static,False -M136,X132,16,static,False -M136,X134,17,static,False -M136,X137,18,static,False -M136,X008,19,static,False -M136,X021,20,static,False -M136,X022,21,static,False -M136,X050,22,static,False -M136,X138,23,static,False -M136,X139,24,static,False -M136,M122,26,static,True -M136,M123,27,static,True -M136,M124,28,static,True -M136,M125,29,static,True -M136,M130,30,static,True -M136,M131,31,static,True -M136,M132,32,static,True -M136,M133,33,static,True -M136,M134,34,static,True -M136,M135,35,static,True -M136,M137,43,static,True -M137,X010,28,static,False -M137,X044,29,static,False -M137,X120,30,static,False -M137,X131,31,static,False -M137,X134,32,static,False -M137,X135,33,static,False -M137,X008,34,static,False -M137,X021,35,static,False -M137,X050,36,static,False -M137,X139,37,static,False -M138,X045,20,static,False -M138,X008,21,static,False -M138,X021,22,static,False -M138,X139,23,static,False -M138,M002,25,static,True -M138,M011,26,static,True -M138,M055,27,static,True -M138,X117,28,static,False -M138,X054,30,static,False -M139,X044,16,static,False -M139,X045,17,static,False -M139,X120,18,static,False -M139,X008,19,static,False -M139,X021,20,static,False -M139,X139,21,static,False -M139,M005,23,static,True -M139,M011,24,static,True -M139,M012,25,static,True -M139,M018,26,static,True -M139,M019,27,static,True -M139,M020,28,static,True -M139,M023,29,static,True -M139,M026,30,static,True -M139,M027,31,static,True -M139,M043,32,static,True -M139,M043,33,static,True -M139,M043,34,static,True -M139,M047,35,static,True -M139,M051,36,static,True -M139,M052,37,static,True -M139,M055,38,static,True -M139,M058,39,static,True -M139,M059,40,static,True -M139,M140,42,static,True -M139,M140,43,static,True -M139,M140,44,static,True -M139,M140,45,static,True -M139,M140,55,static,True -M139,M141,56,static,True -M139,M142,57,static,True -M140,X031,23,static,False -M140,X122,24,static,False -M140,X134,25,static,False -M140,X008,26,static,False -M140,X021,27,static,False -M140,X022,28,static,False -M140,X139,29,static,False -M140,M011,31,static,True -M140,M043,32,static,True -M140,M058,33,static,True -M140,X118,34,static,False -M141,X005,10,static,False -M141,X006,11,static,False -M141,X008,12,static,False -M141,X139,13,static,False -M141,M011,15,static,True -M141,M018,16,static,True -M141,M026,17,static,True -M141,M051,18,static,True -M141,M110,19,static,True -M142,X008,21,static,False -M142,X021,22,static,False -M142,X139,23,static,False -M142,M011,25,static,True -M142,M012,26,static,True -M142,M047,27,static,True -M142,M052,34,static,True -M142,M059,35,static,True -M142,M112,36,static,True -M143,X045,30,static,False -M143,X120,31,static,False -M143,X143,32,static,False -M143,X008,33,static,False -M143,X021,34,static,False -M143,X139,35,static,False -M143,X026,37,static,False -M143,X028,38,static,False -M143,M011,39,static,True -M143,M029,40,static,True -M143,M055,41,static,True -M143,M096,42,static,True -M143,X117,43,static,False -M143,X054,45,static,False -M143,X058,46,static,False -M143,X079,47,static,False -M143,X085,48,static,False -M143,M158,49,static,True -M143,M172,50,static,True -M143,M174,51,static,True -M143,M193,52,static,True -M143,M202,53,static,True -M143,M211,54,static,True -M143,M213,55,static,True -M143,M218,56,static,True -M143,M220,57,static,True -M143,X091,58,static,False -M143,X102,59,static,False -M143,X105,60,static,False -M144,X008,23,static,False -M144,X021,24,static,False -M144,X050,25,static,False -M144,X139,26,static,False -M144,X026,28,static,False -M144,M055,29,static,True -M144,M143,31,static,True -M144,M197,32,static,True -M144,M202,40,static,True -M144,M209,41,static,True -M144,M223,42,static,True -M144,X102,43,static,False -M145,X050,11,static,False -M145,M011,13,static,True -M145,M040,14,static,True -M145,M077,15,static,True -M145,M078,27,static,True -M145,M084,28,static,True -M145,M205,30,static,True -M146,X031,34,static,False -M146,X120,35,static,False -M146,X008,36,static,False -M146,X021,37,static,False -M146,X139,38,static,False -M146,X113,40,static,False -M146,X115,41,static,False -M146,X116,42,static,False -M147,X120,6,static,False -M147,X139,7,static,False -M147,X117,9,static,False -M147,M153,11,static,True -M148,X045,21,static,False -M148,X120,22,static,False -M148,X143,23,static,False -M148,X008,24,static,False -M148,X021,25,static,False -M148,X050,26,static,False -M148,X139,27,static,False -M148,X015,29,static,False -M148,X047,30,static,False -M148,M020,31,static,True -M148,M055,32,static,True -M148,X117,33,static,False -M148,X054,35,static,False -M148,X057,36,static,False -M148,X062,37,static,False -M148,X070,49,static,False -M148,X073,50,static,False -M148,X106,51,static,False -M148,X015,287,static,False -M148,X018,288,static,False -M149,X008,7,static,False -M149,X139,8,static,False -M149,X062,10,static,False -M149,X073,11,static,False -M149,X015,23,static,False -M149,X015,39,static,False -M149,X020,40,static,False -M150,X008,20,static,False -M150,X021,21,static,False -M150,X139,22,static,False -M150,X026,24,static,False -M150,M001,25,static,True -M150,M020,26,static,True -M150,M055,27,static,True -M150,X054,29,static,False -M150,X062,30,static,False -M150,X068,31,static,False -M150,M148,32,static,True -M150,M158,41,static,True -M150,X091,42,static,False -M151,X031,26,static,False -M151,X008,27,static,False -M151,X050,28,static,False -M151,M011,30,static,True -M151,M040,31,static,True -M151,M055,32,static,True -M151,M077,33,static,True -M151,M146,35,static,True -M151,M171,36,static,True -M151,M203,37,static,True -M151,M205,38,static,True -M151,X104,39,static,False -M152,X031,26,static,False -M152,X122,27,static,False -M152,X134,28,static,False -M152,X135,29,static,False -M152,X008,30,static,False -M152,X021,31,static,False -M152,X022,32,static,False -M152,X139,33,static,False -M152,X026,35,static,False -M152,X028,36,static,False -M152,M029,37,static,True -M152,X117,38,static,False -M152,X054,40,static,False -M152,X085,41,static,False -M152,M143,42,static,True -M152,X091,50,static,False -M152,X102,51,static,False -M152,X103,52,static,False -M154,X044,31,static,False -M154,X143,32,static,False -M154,X008,33,static,False -M154,X021,34,static,False -M154,X139,35,static,False -M154,M012,37,static,True -M154,M055,38,static,True -M154,M058,39,static,True -M154,M103,40,static,True -M154,X061,42,static,False -M154,X070,43,static,False -M154,M139,44,static,True -M154,M142,45,static,True -M154,M155,46,static,True -M154,M185,47,static,True -M154,M195,48,static,True -M154,M196,49,static,True -M154,M204,50,static,True -M154,M220,51,static,True -M154,M222,52,static,True -M154,X102,53,static,False -M154,M194,148,static,True -M154,M194,211,static,True -M155,X143,31,static,False -M155,X008,32,static,False -M155,X011,33,static,False -M155,X012,34,static,False -M155,X021,35,static,False -M155,X139,36,static,False -M155,M011,38,static,True -M155,M012,39,static,True -M155,M020,40,static,True -M155,M047,41,static,True -M155,M055,42,static,True -M155,M059,43,static,True -M155,X117,44,static,False -M155,X107,46,static,False -M155,X054,47,static,False -M155,X058,48,static,False -M155,X070,49,static,False -M155,X072,50,static,False -M155,X079,51,static,False -M155,M163,52,static,True -M155,M174,53,static,True -M155,X098,54,static,False -M155,X105,55,static,False -M156,X133,25,static,False -M156,X008,26,static,False -M156,X011,27,static,False -M156,X021,28,static,False -M156,X022,29,static,False -M156,X139,30,static,False -M156,M018,32,static,True -M156,M040,43,static,True -M156,X117,44,static,False -M156,X107,46,static,False -M156,X054,47,static,False -M156,M138,48,static,True -M156,M157,49,static,True -M156,M176,50,static,True -M156,X108,51,static,False -M157,X124,18,static,False -M157,X133,19,static,False -M157,X008,20,static,False -M157,X011,21,static,False -M157,X022,22,static,False -M157,X050,23,static,False -M157,X139,24,static,False -M157,X108,26,static,False -M157,X109,166,static,False -M158,X008,19,static,False -M158,X021,20,static,False -M158,X139,21,static,False -M158,X026,23,static,False -M158,X027,24,static,False -M158,X029,25,static,False -M158,M011,26,static,True -M158,M019,27,static,True -M158,M053,28,static,True -M158,M055,29,static,True -M158,X117,30,static,False -M158,X128,31,static,False -M158,X054,33,static,False -M158,X055,34,static,False -M158,X085,35,static,False -M158,X091,36,static,False -M158,X102,37,static,False -M159,X143,26,static,False -M159,X008,27,static,False -M159,X021,28,static,False -M159,X139,29,static,False -M159,X026,31,static,False -M159,X028,32,static,False -M159,M043,33,static,True -M159,M055,34,static,True -M159,X127,35,static,False -M159,X054,37,static,False -M159,X085,38,static,False -M159,M139,39,static,True -M159,M158,40,static,True -M159,M222,41,static,True -M159,X091,42,static,False -M159,X102,43,static,False -M160,X045,12,static,False -M160,X008,13,static,False -M160,X021,14,static,False -M160,X139,15,static,False -M160,M047,17,static,True -M160,M053,18,static,True -M160,M055,19,static,True -M160,X117,20,static,False -M160,X054,22,static,False -M160,X061,23,static,False -M160,M138,24,static,True -M160,M165,25,static,True -M160,M181,26,static,True -M160,M182,27,static,True -M160,M186,28,static,True -M160,M192,29,static,True -M160,M196,30,static,True -M160,M204,31,static,True -M160,M214,32,static,True -M161,X045,19,static,False -M161,X008,20,static,False -M161,X011,21,static,False -M161,X114,23,static,False -M161,M055,24,static,True -M161,X113,25,static,False -M161,X116,26,static,False -M161,X054,28,static,False -M161,X061,29,static,False -M161,M138,30,static,True -M161,M146,31,static,True -M161,M177,32,static,True -M161,M196,33,static,True -M162,X134,36,static,False -M162,X008,37,static,False -M162,X011,38,static,False -M162,X021,39,static,False -M162,X050,40,static,False -M162,X139,41,static,False -M162,M019,43,static,True -M162,M020,44,static,True -M162,M023,45,static,True -M162,M055,46,static,True -M162,M058,47,static,True -M162,M077,48,static,True -M162,X113,49,static,False -M162,X116,50,static,False -M162,X054,52,static,False -M162,X061,53,static,False -M162,X069,54,static,False -M162,X072,55,static,False -M162,M146,56,static,True -M162,M161,57,static,True -M162,M163,58,static,True -M162,M177,59,static,True -M162,M196,60,static,True -M162,M203,61,static,True -M162,M204,62,static,True -M162,M205,63,static,True -M162,X093,64,static,False -M162,X098,65,static,False -M163,X045,21,static,False -M163,X143,22,static,False -M163,X008,23,static,False -M163,X011,24,static,False -M163,X021,25,static,False -M163,X139,26,static,False -M163,M011,28,static,True -M163,M019,29,static,True -M163,M020,30,static,True -M163,M047,31,static,True -M163,M055,38,static,True -M163,M077,39,static,True -M163,X113,40,static,False -M163,X117,41,static,False -M163,X054,43,static,False -M163,X070,44,static,False -M163,X072,45,static,False -M163,X098,46,static,False -M164,X045,54,static,False -M164,X120,55,static,False -M164,X008,56,static,False -M164,X022,57,static,False -M164,X139,58,static,False -M164,X113,60,static,False -M164,X114,61,static,False -M164,X015,62,static,False -M164,X016,63,static,False -M164,X017,64,static,False -M164,X019,65,static,False -M164,X113,66,static,False -M164,X117,67,static,False -M164,X054,69,static,False -M164,X061,70,static,False -M164,M138,71,static,True -M164,M177,72,static,True -M164,X015,323,static,False -M165,X045,47,static,False -M165,X120,48,static,False -M165,X134,49,static,False -M165,X008,50,static,False -M165,X021,51,static,False -M165,M011,53,static,True -M165,M077,54,static,True -M165,M087,55,static,True -M166,X008,9,static,False -M166,X139,10,static,False -M166,X105,12,static,False -M166,X111,13,static,False -M167,X045,15,static,False -M167,X008,16,static,False -M167,X021,17,static,False -M167,X036,18,static,False -M167,X037,19,static,False -M167,X050,20,static,False -M167,X139,21,static,False -M167,M011,23,static,True -M167,M024,24,static,True -M167,M035,25,static,True -M167,M037,31,static,True -M167,M055,32,static,True -M167,M095,33,static,True -M168,X045,19,static,False -M168,X120,20,static,False -M168,X132,21,static,False -M168,X135,22,static,False -M168,X008,23,static,False -M168,X021,24,static,False -M168,X139,25,static,False -M168,X141,26,static,False -M168,X076,28,static,False -M168,X077,29,static,False -M168,X078,30,static,False -M168,X084,31,static,False -M168,X103,32,static,False -M168,X105,33,static,False -M168,X111,34,static,False -M169,X045,28,static,False -M169,X120,29,static,False -M169,X135,30,static,False -M169,X008,31,static,False -M169,X011,32,static,False -M169,X021,33,static,False -M169,X022,34,static,False -M169,X050,35,static,False -M169,X113,37,static,False -M169,M019,38,static,True -M169,M040,39,static,True -M169,M055,40,static,True -M169,M077,41,static,True -M169,M091,42,static,True -M169,X113,43,static,False -M169,X116,44,static,False -M169,X061,46,static,False -M169,M145,47,static,True -M169,M165,48,static,True -M169,M175,49,static,True -M169,M196,50,static,True -M169,M205,58,static,True -M170,X045,34,static,False -M170,X134,35,static,False -M170,X135,36,static,False -M170,X007,37,static,False -M170,X008,38,static,False -M170,X021,39,static,False -M170,X022,40,static,False -M170,X139,41,static,False -M170,M026,43,static,True -M170,M040,60,static,True -M170,X117,61,static,False -M170,X107,63,static,False -M170,X054,64,static,False -M170,X064,65,static,False -M170,X079,66,static,False -M170,M138,67,static,True -M170,M176,68,static,True -M171,X031,17,static,False -M171,X021,18,static,False -M171,X050,19,static,False -M171,M055,21,static,True -M171,M077,22,static,True -M171,M086,29,static,True -M171,M205,31,static,True -M172,X008,23,static,False -M172,X021,24,static,False -M172,X139,25,static,False -M172,X026,27,static,False -M172,M011,28,static,True -M172,M040,29,static,True -M172,M053,30,static,True -M172,M055,31,static,True -M172,M095,32,static,True -M172,X059,34,static,False -M172,M138,35,static,True -M172,M151,36,static,True -M172,M158,37,static,True -M172,M159,38,static,True -M172,M174,39,static,True -M172,M176,46,static,True -M172,M186,47,static,True -M172,M187,48,static,True -M172,M202,49,static,True -M172,X105,50,static,False -M173,X031,26,static,False -M173,X045,27,static,False -M173,X134,28,static,False -M173,X145,29,static,False -M173,X008,30,static,False -M173,X021,31,static,False -M173,X050,32,static,False -M173,X139,33,static,False -M173,X033,35,static,False -M173,X034,36,static,False -M173,M011,37,static,True -M173,M027,38,static,True -M173,M040,44,static,True -M173,M055,45,static,True -M173,X054,47,static,False -M173,X067,48,static,False -M173,X083,49,static,False -M174,X044,17,static,False -M174,X008,18,static,False -M174,X139,19,static,False -M174,X026,21,static,False -M174,M011,22,static,True -M174,M029,23,static,True -M174,M030,24,static,True -M174,M055,25,static,True -M174,X117,26,static,False -M174,X118,27,static,False -M174,M158,29,static,True -M174,X105,30,static,False -M175,X139,50,static,False -M175,M019,52,static,True -M175,M055,53,static,True -M175,X113,54,static,False -M175,X116,55,static,False -M176,X008,11,static,False -M176,M011,13,static,True -M176,M040,14,static,True -M176,M055,15,static,True -M177,X120,28,static,False -M177,X139,29,static,False -M177,X113,31,static,False -M177,X116,32,static,False -M177,X061,34,static,False -M178,X008,5,static,False -M178,X021,6,static,False -M178,X139,7,static,False -M178,X062,9,static,False -M178,X073,10,static,False -M178,X015,22,static,False -M178,X015,38,static,False -M178,X020,39,static,False -M179,X008,24,static,False -M179,X021,25,static,False -M179,M011,27,static,True -M179,M018,28,static,True -M179,M026,29,static,True -M179,M156,31,static,True -M179,M170,32,static,True -M179,M199,33,static,True -M179,X108,34,static,False -M180,X008,14,static,False -M180,X021,15,static,False -M180,X050,16,static,False -M180,X139,17,static,False -M180,M018,19,static,True -M180,M026,20,static,True -M180,M051,21,static,True -M180,M055,22,static,True -M180,X064,24,static,False -M180,X085,25,static,False -M180,M139,26,static,True -M180,M156,27,static,True -M180,M157,28,static,True -M180,M160,29,static,True -M180,M170,30,static,True -M180,M179,31,static,True -M180,M198,32,static,True -M180,M199,33,static,True -M180,M204,34,static,True -M180,X102,35,static,False -M180,X107,77,static,False -M180,X015,82,static,False -M180,X018,83,static,False -M180,X015,99,static,False -M180,X064,101,static,False -M180,X065,102,static,False -M181,X045,32,static,False -M181,X120,33,static,False -M181,X134,34,static,False -M181,X135,35,static,False -M181,X008,36,static,False -M181,X011,37,static,False -M181,X021,38,static,False -M181,X139,39,static,False -M181,X113,41,static,False -M181,X113,42,static,False -M181,X116,43,static,False -M181,X107,45,static,False -M181,M146,46,static,True -M181,M165,47,static,True -M181,M177,48,static,True -M182,X008,16,static,False -M182,X021,17,static,False -M182,X139,18,static,False -M182,M005,20,static,True -M182,M040,21,static,True -M182,M058,22,static,True -M182,X054,24,static,False -M182,X059,25,static,False -M182,X060,32,static,False -M182,X066,33,static,False -M182,X067,34,static,False -M182,X083,35,static,False -M182,M139,42,static,True -M182,M173,43,static,True -M183,X044,16,static,False -M183,X045,17,static,False -M183,X134,18,static,False -M183,X135,19,static,False -M183,X008,20,static,False -M183,X021,21,static,False -M183,X139,22,static,False -M183,M043,24,static,True -M183,M043,25,static,True -M183,X070,27,static,False -M183,X071,28,static,False -M183,X072,29,static,False -M183,M139,30,static,True -M183,M184,31,static,True -M184,X011,18,static,False -M184,X044,19,static,False -M184,X049,20,static,False -M184,X119,21,static,False -M184,X124,22,static,False -M184,X125,23,static,False -M184,X131,24,static,False -M184,X133,25,static,False -M184,X134,26,static,False -M184,X135,27,static,False -M184,X008,28,static,False -M184,X009,29,static,False -M184,X021,30,static,False -M184,X050,31,static,False -M184,X139,32,static,False -M184,M098,34,static,True -M184,X100,36,static,False -M184,X101,37,static,False -M185,X008,10,static,False -M185,X021,11,static,False -M185,X050,12,static,False -M185,M055,14,static,True -M185,X085,16,static,False -M185,M139,17,static,True -M185,M160,18,static,True -M185,M186,19,static,True -M185,M202,20,static,True -M185,M204,21,static,True -M185,M218,22,static,True -M185,M222,23,static,True -M185,X105,24,static,False -M186,X008,8,static,False -M186,X139,9,static,False -M186,X026,11,static,False -M186,M011,12,static,True -M187,X008,14,static,False -M187,X021,15,static,False -M187,X050,16,static,False -M187,M011,18,static,True -M187,M019,19,static,True -M187,M055,20,static,True -M187,X081,22,static,False -M187,X082,23,static,False -M188,X031,40,static,False -M188,X044,41,static,False -M188,X008,42,static,False -M188,X021,43,static,False -M188,X050,44,static,False -M188,X139,45,static,False -M188,X114,47,static,False -M188,M011,48,static,True -M188,M019,49,static,True -M188,X113,50,static,False -M188,X116,51,static,False -M188,X117,52,static,False -M188,X054,54,static,False -M188,X061,55,static,False -M188,X069,56,static,False -M188,M138,57,static,True -M188,M161,58,static,True -M188,M177,59,static,True -M188,M190,60,static,True -M188,M217,61,static,True -M188,X092,62,static,False -M188,X093,63,static,False -M188,X096,64,static,False -M188,X098,65,static,False -M189,X002,18,static,False -M189,X044,19,static,False -M189,X008,20,static,False -M189,X139,21,static,False -M189,M011,23,static,True -M189,M024,24,static,True -M189,X054,26,static,False -M189,X061,27,static,False -M189,M167,28,static,True -M189,M187,29,static,True -M189,M188,30,static,True -M189,M202,31,static,True -M189,M216,32,static,True -M190,X044,36,static,False -M190,X120,37,static,False -M190,X124,38,static,False -M190,X008,39,static,False -M190,X021,40,static,False -M190,X050,41,static,False -M190,X139,42,static,False -M190,M024,44,static,True -M190,M055,45,static,True -M190,X113,46,static,False -M190,X116,47,static,False -M190,M175,49,static,True -M190,M196,50,static,True -M191,X139,18,static,False -M191,X026,20,static,False -M191,X028,21,static,False -M191,X117,22,static,False -M191,M158,24,static,True -M191,M173,25,static,True -M191,M188,26,static,True -M191,M193,32,static,True -M191,M208,33,static,True -M191,M211,34,static,True -M191,X091,35,static,False -M191,X102,36,static,False -M192,X045,19,static,False -M192,X134,20,static,False -M192,X008,21,static,False -M192,X011,22,static,False -M192,X021,23,static,False -M192,M055,25,static,True -M192,X107,27,static,False -M192,X054,28,static,False -M192,X061,29,static,False -M192,M138,30,static,True -M192,M146,31,static,True -M192,M164,32,static,True -M192,M165,33,static,True -M192,M177,34,static,True -M192,M181,40,static,True -M192,M196,49,static,True -M193,X008,10,static,False -M193,X139,11,static,False -M193,X026,13,static,False -M193,X117,14,static,False -M193,X055,16,static,False -M193,X085,17,static,False -M193,M172,18,static,True -M193,M187,19,static,True -M193,M197,20,static,True -M193,X091,21,static,False -M194,X008,14,static,False -M194,X021,15,static,False -M194,X139,16,static,False -M194,X026,18,static,False -M194,M047,19,static,True -M194,M052,20,static,True -M194,M055,21,static,True -M194,X085,23,static,False -M194,M139,24,static,True -M194,M142,25,static,True -M194,M154,26,static,True -M194,M155,27,static,True -M194,M163,28,static,True -M194,M172,29,static,True -M194,M180,30,static,True -M194,M186,31,static,True -M194,M200,32,static,True -M194,M202,38,static,True -M194,M206,39,static,True -M194,X093,40,static,False -M194,X102,41,static,False -M194,X106,42,static,False -M195,X045,15,static,False -M195,X008,16,static,False -M195,X021,17,static,False -M195,X022,18,static,False -M195,X050,19,static,False -M195,X139,20,static,False -M195,M020,22,static,True -M195,M055,23,static,True -M195,X054,25,static,False -M195,X059,26,static,False -M195,X061,27,static,False -M195,X062,28,static,False -M195,X068,29,static,False -M195,X069,30,static,False -M195,X071,31,static,False -M195,X072,32,static,False -M195,X073,33,static,False -M195,X085,34,static,False -M195,M139,35,static,True -M195,M148,36,static,True -M195,M162,41,static,True -M195,M163,50,static,True -M195,M177,51,static,True -M195,M182,52,static,True -M195,M183,53,static,True -M195,M186,54,static,True -M195,M204,55,static,True -M195,M222,56,static,True -M195,X089,57,static,False -M195,X092,58,static,False -M195,X093,59,static,False -M195,X093,60,static,False -M195,X094,61,static,False -M195,X095,62,static,False -M195,X096,63,static,False -M195,X097,64,static,False -M195,X098,65,static,False -M196,X045,19,static,False -M196,X008,20,static,False -M196,X011,21,static,False -M196,X021,22,static,False -M196,X050,23,static,False -M196,X139,24,static,False -M196,M011,26,static,True -M196,M019,27,static,True -M196,M055,28,static,True -M196,M077,29,static,True -M196,X113,34,static,False -M196,X116,35,static,False -M196,X061,37,static,False -M196,M145,38,static,True -M196,M146,39,static,True -M196,M165,40,static,True -M196,M171,41,static,True -M196,M175,42,static,True -M196,M205,43,static,True -M197,X031,32,static,False -M197,X045,33,static,False -M197,X008,34,static,False -M197,X021,35,static,False -M197,X050,36,static,False -M197,X026,38,static,False -M197,X028,39,static,False -M197,M011,40,static,True -M197,M049,41,static,True -M197,M050,48,static,True -M197,M055,49,static,True -M197,X117,50,static,False -M197,X054,52,static,False -M197,M158,53,static,True -M197,M172,54,static,True -M197,X091,55,static,False -M197,M143,255,static,True -M198,X045,24,static,False -M198,X008,25,static,False -M198,X011,26,static,False -M198,X021,27,static,False -M198,X139,28,static,False -M198,X113,30,static,False -M198,M040,31,static,True -M198,M051,32,static,True -M198,M055,47,static,True -M198,X117,48,static,False -M198,X107,50,static,False -M198,X054,51,static,False -M198,M138,52,static,True -M198,M146,53,static,True -M198,M176,54,static,True -M198,M177,55,static,True -M198,M181,56,static,True -M198,M203,57,static,True -M198,M204,58,static,True -M199,X044,18,static,False -M199,X120,19,static,False -M199,X008,20,static,False -M199,X021,21,static,False -M199,X139,22,static,False -M199,M051,24,static,True -M199,X109,88,static,False -M199,X107,113,static,False -M199,X015,118,static,False -M199,X018,119,static,False -M200,X005,19,static,False -M200,X045,20,static,False -M200,X008,21,static,False -M200,X139,22,static,False -M200,M011,24,static,True -M200,M040,25,static,True -M200,M052,26,static,True -M200,M055,35,static,True -M200,X117,36,static,False -M200,X054,38,static,False -M200,M155,39,static,True -M200,M207,40,static,True -M200,X015,75,static,False -M201,X045,13,static,False -M201,X133,14,static,False -M201,X135,15,static,False -M201,X008,16,static,False -M201,X021,17,static,False -M201,X022,18,static,False -M201,X050,19,static,False -M201,X139,20,static,False -M201,X076,22,static,False -M201,X084,23,static,False -M201,X099,24,static,False -M201,X100,25,static,False -M201,X101,26,static,False -M201,X105,27,static,False -M201,X111,28,static,False -M202,X120,32,static,False -M202,X136,33,static,False -M202,X008,34,static,False -M202,X021,35,static,False -M202,X050,36,static,False -M202,M011,38,static,True -M202,M040,39,static,True -M202,M053,40,static,True -M202,M055,41,static,True -M202,X085,43,static,False -M202,M207,44,static,True -M203,X120,28,static,False -M203,X008,29,static,False -M203,X021,30,static,False -M203,X050,31,static,False -M203,X139,32,static,False -M203,M011,34,static,True -M203,M040,35,static,True -M203,M055,36,static,True -M203,M057,37,static,True -M203,M058,38,static,True -M203,M146,40,static,True -M203,M171,41,static,True -M203,M176,42,static,True -M203,M205,43,static,True -M203,X104,44,static,False -M204,X045,36,static,False -M204,X008,37,static,False -M204,X011,38,static,False -M204,X021,39,static,False -M204,X139,40,static,False -M204,X113,42,static,False -M204,M040,43,static,True -M204,M057,44,static,True -M204,M058,52,static,True -M204,X117,60,static,False -M204,X107,62,static,False -M204,X054,63,static,False -M204,M138,64,static,True -M204,M146,65,static,True -M204,M151,71,static,True -M204,M165,72,static,True -M204,M176,73,static,True -M204,M177,74,static,True -M204,M181,75,static,True -M204,M203,76,static,True -M204,M205,83,static,True -M205,X008,19,static,False -M205,X011,20,static,False -M205,X021,21,static,False -M205,X047,23,static,False -M205,M011,24,static,True -M205,M058,25,static,True -M205,M077,26,static,True -M206,X045,22,static,False -M206,X008,23,static,False -M206,X011,24,static,False -M206,M011,26,static,True -M206,M055,27,static,True -M206,M059,28,static,True -M206,X117,34,static,False -M206,X087,36,static,False -M207,X008,26,static,False -M207,M011,28,static,True -M207,M052,29,static,True -M207,M053,30,static,True -M207,M055,37,static,True -M208,X007,28,static,False -M208,X008,29,static,False -M208,X021,30,static,False -M208,X139,31,static,False -M208,X026,33,static,False -M208,M076,34,static,True -M208,X117,35,static,False -M208,M138,37,static,True -M208,M158,38,static,True -M208,M193,39,static,True -M208,M211,40,static,True -M208,X091,41,static,False -M208,X103,42,static,False -M208,X015,171,static,False -M209,X031,24,static,False -M209,X045,25,static,False -M209,X008,26,static,False -M209,X021,27,static,False -M209,X050,28,static,False -M209,X026,30,static,False -M209,M011,31,static,True -M209,M029,32,static,True -M209,M055,33,static,True -M209,M096,34,static,True -M209,X054,36,static,False -M209,X085,37,static,False -M209,M158,38,static,True -M209,M172,39,static,True -M209,X102,40,static,False -M209,X105,41,static,False -M209,M143,218,static,True -M210,X031,15,static,False -M210,X124,16,static,False -M210,X130,17,static,False -M210,X133,18,static,False -M210,X148,19,static,False -M210,X021,20,static,False -M210,X050,21,static,False -M210,M216,23,static,True -M210,M220,24,static,True -M210,X108,25,static,False -M211,X045,26,static,False -M211,X122,27,static,False -M211,X134,28,static,False -M211,X007,29,static,False -M211,X008,30,static,False -M211,X021,31,static,False -M211,X139,32,static,False -M211,M011,34,static,True -M211,M053,35,static,True -M211,M055,36,static,True -M211,X054,38,static,False -M211,M138,39,static,True -M211,M139,40,static,True -M211,M184,41,static,True -M211,M202,42,static,True -M211,M210,43,static,True -M211,M212,44,static,True -M211,M213,50,static,True -M211,M216,51,static,True -M211,M217,52,static,True -M211,M220,53,static,True -M211,M222,54,static,True -M211,X108,55,static,False -M212,X120,19,static,False -M212,X021,20,static,False -M212,X050,21,static,False -M212,X139,22,static,False -M212,X026,24,static,False -M212,M011,25,static,True -M212,M024,26,static,True -M212,M034,27,static,True -M212,M035,28,static,True -M212,M040,34,static,True -M212,M055,35,static,True -M212,M056,36,static,True -M212,M095,37,static,True -M212,X056,39,static,False -M212,M210,40,static,True -M212,M216,41,static,True -M212,M220,42,static,True -M213,X045,28,static,False -M213,X008,29,static,False -M213,X021,30,static,False -M213,X050,31,static,False -M213,X139,32,static,False -M213,M011,34,static,True -M213,M040,35,static,True -M213,M055,36,static,True -M213,X059,38,static,False -M213,X085,39,static,False -M213,M139,40,static,True -M213,M142,41,static,True -M213,M151,42,static,True -M213,M160,43,static,True -M213,M176,44,static,True -M213,M180,45,static,True -M213,M182,46,static,True -M213,M203,47,static,True -M213,M204,48,static,True -M213,M209,49,static,True -M213,M212,50,static,True -M213,M218,51,static,True -M213,M220,52,static,True -M213,M222,53,static,True -M213,X105,54,static,False -M214,X036,19,static,False -M214,X045,20,static,False -M214,X008,21,static,False -M214,X021,22,static,False -M214,X139,23,static,False -M214,M011,25,static,True -M214,M044,26,static,True -M214,M047,33,static,True -M214,M053,34,static,True -M214,M055,35,static,True -M214,M058,36,static,True -M214,X107,38,static,False -M214,M182,39,static,True -M214,M204,40,static,True -M215,X143,21,static,False -M215,X008,22,static,False -M215,X139,23,static,False -M215,X026,25,static,False -M215,X028,26,static,False -M215,M055,27,static,True -M215,X117,28,static,False -M215,X127,29,static,False -M215,X128,30,static,False -M215,X085,32,static,False -M215,M139,33,static,True -M215,M158,34,static,True -M215,M159,35,static,True -M215,M211,44,static,True -M215,M213,45,static,True -M215,M220,46,static,True -M215,M222,47,static,True -M215,X091,48,static,False -M215,X102,49,static,False -M216,X120,15,static,False -M216,X008,16,static,False -M216,X021,17,static,False -M216,X050,18,static,False -M216,M040,20,static,True -M217,X134,8,static,False -M217,X021,9,static,False -M217,X139,10,static,False -M217,X061,12,static,False -M217,X088,13,static,False -M218,X044,16,static,False -M218,X143,17,static,False -M218,X008,18,static,False -M218,X021,19,static,False -M218,X139,20,static,False -M218,X141,21,static,False -M218,M055,23,static,True -M218,M056,24,static,True -M218,X117,25,static,False -M218,X107,27,static,False -M218,X068,28,static,False -M218,X085,29,static,False -M218,M139,30,static,True -M218,M159,31,static,True -M218,M174,32,static,True -M218,M222,33,static,True -M218,X105,34,static,False -M219,X008,19,static,False -M219,X021,20,static,False -M219,X050,21,static,False -M219,X113,23,static,False -M219,X026,24,static,False -M219,M055,25,static,True -M219,X061,27,static,False -M219,M144,28,static,True -M219,M151,29,static,True -M219,M159,30,static,True -M219,M160,31,static,True -M219,M162,32,static,True -M219,M165,33,static,True -M219,M169,34,static,True -M219,M173,35,static,True -M219,M175,36,static,True -M219,M180,37,static,True -M219,M202,38,static,True -M219,M203,39,static,True -M219,M204,40,static,True -M219,M209,41,static,True -M219,M211,42,static,True -M219,M213,43,static,True -M219,M216,44,static,True -M219,M217,45,static,True -M219,M218,46,static,True -M219,M220,47,static,True -M219,M222,48,static,True -M219,X102,49,static,False -M219,X108,50,static,False -M219,X109,59,static,False -M220,X008,12,static,False -M220,X011,13,static,False -M220,X139,14,static,False -M220,X047,16,static,False -M220,X048,17,static,False -M221,X045,11,static,False -M221,X008,12,static,False -M221,X021,13,static,False -M221,X036,14,static,False -M221,X050,15,static,False -M221,X139,16,static,False -M221,X026,18,static,False -M221,M011,19,static,True -M221,M024,20,static,True -M221,M034,21,static,True -M221,M055,22,static,True -M221,X054,24,static,False -M221,X080,25,static,False -M221,M138,26,static,True -M221,M139,27,static,True -M221,M144,28,static,True -M221,M150,29,static,True -M221,M151,30,static,True -M221,M152,31,static,True -M221,M158,32,static,True -M221,M159,39,static,True -M221,M160,40,static,True -M221,M165,41,static,True -M221,M167,42,static,True -M221,M169,43,static,True -M221,M172,44,static,True -M221,M173,45,static,True -M221,M180,46,static,True -M221,M182,47,static,True -M221,M185,53,static,True -M221,M186,60,static,True -M221,M187,61,static,True -M221,M191,68,static,True -M221,M192,69,static,True -M221,M193,70,static,True -M221,M194,71,static,True -M221,M195,78,static,True -M221,M202,79,static,True -M221,M203,80,static,True -M221,M204,81,static,True -M221,M211,82,static,True -M221,M215,83,static,True -M221,M216,84,static,True -M221,M218,85,static,True -M221,M219,86,static,True -M221,M222,87,static,True -M221,X090,88,static,False -M221,X091,89,static,False -M221,X094,90,static,False -M221,X102,91,static,False -M221,X110,92,static,False -M222,X044,40,static,False -M222,X045,41,static,False -M222,X046,42,static,False -M222,X122,43,static,False -M222,X134,44,static,False -M222,X135,45,static,False -M222,X008,46,static,False -M222,X021,47,static,False -M222,X139,48,static,False -M222,M011,50,static,True -M222,M043,51,static,True -M222,M102,52,static,True -M222,M139,54,static,True -M222,M183,55,static,True -M222,M184,56,static,True -M223,X134,17,static,False -M223,X008,18,static,False -M223,X050,19,static,False -M223,M011,21,static,True -M223,M055,22,static,True -M223,M117,23,static,True -M223,X086,30,static,False -M037,D001,165,dynamic,False -M107,D002,94,dynamic,False -M116,X026,64,dynamic,False -M130,D004,28,discovery,False -M167,D005,147,discovery,False -M167,D006,158,dynamic,False -M214,D007,69,dynamic,False -M221,D008,158,discovery,False diff --git a/docs/helix/00-discover/boundary-audit/modules.csv b/docs/helix/00-discover/boundary-audit/modules.csv deleted file mode 100644 index 6df202e..0000000 --- a/docs/helix/00-discover/boundary-audit/modules.csv +++ /dev/null @@ -1,224 +0,0 @@ -module_id,classification,role,physical_lines -M001,contract,declarations/ports/wire,145 -M002,contract,declarations/ports/wire,79 -M003,packaging/CLI,author tooling,247 -M004,contract,declarations/ports/wire,179 -M005,contract,declarations/ports/wire,154 -M006,contract,declarations/ports/wire,160 -M007,platform adapter (Databricks),job runtime/definition,231 -M008,packaging/CLI,author tooling,272 -M009,packaging/CLI,author tooling,106 -M010,packaging/CLI,author tooling,275 -M011,contract,declarations/ports/wire,180 -M012,contract,declarations/ports/wire,78 -M013,packaging/CLI,author tooling,21 -M014,packaging/CLI,author tooling,40 -M015,packaging/CLI,author tooling,77 -M016,packaging/CLI,author tooling,102 -M017,packaging/CLI,author tooling,34 -M018,contract,declarations/ports/wire,157 -M019,contract,declarations/ports/wire,208 -M020,contract,declarations/ports/wire,295 -M021,contract,declarations/ports/wire,96 -M022,packaging/CLI,author tooling,115 -M023,contract,declarations/ports/wire,128 -M024,contract,declarations/ports/wire,351 -M025,packaging/CLI,author tooling,238 -M026,contract,declarations/ports/wire,201 -M027,contract,declarations/ports/wire,158 -M028,contract,declarations/ports/wire,294 -M029,contract,declarations/ports/wire,183 -M030,contract,declarations/ports/wire,38 -M031,packaging/CLI,author tooling,43 -M032,packaging/CLI,author tooling,117 -M033,packaging/CLI,author tooling,173 -M034,packaging/CLI,author tooling,341 -M035,packaging/CLI,author tooling,124 -M036,packaging/CLI,author tooling,110 -M037,packaging/CLI,author tooling,186 -M038,packaging/CLI,author tooling,352 -M039,packaging/CLI,author tooling,108 -M040,contract,declarations/ports/wire,124 -M041,contract,declarations/ports/wire,41 -M042,contract,declarations/ports/wire,65 -M043,contract,declarations/ports/wire,435 -M044,contract,declarations/ports/wire,164 -M045,platform adapter (Databricks),job runtime/definition,40 -M046,platform adapter (Databricks),job runtime/definition,211 -M047,platform adapter (Databricks),job runtime/definition,122 -M048,contract,declarations/ports/wire,108 -M049,contract,declarations/ports/wire,177 -M050,contract,declarations/ports/wire,254 -M051,contract,declarations/ports/wire,337 -M052,contract,declarations/ports/wire,183 -M053,contract,declarations/ports/wire,265 -M054,packaging/CLI,author tooling,399 -M055,contract,declarations/ports/wire,494 -M056,contract,declarations/ports/wire,479 -M057,contract,declarations/ports/wire,154 -M058,contract,declarations/ports/wire,179 -M059,contract,declarations/ports/wire,352 -M060,testing,offline doubles,112 -M061,testing,offline doubles,92 -M062,testing,offline doubles,70 -M063,testing,offline doubles,124 -M064,testing,offline doubles,262 -M065,testing,offline doubles,175 -M066,testing,offline doubles,47 -M067,testing,offline doubles,182 -M068,testing,offline doubles,106 -M069,testing,offline doubles,193 -M070,testing,offline doubles,333 -M071,testing,offline doubles,176 -M072,testing,offline doubles,40 -M073,testing,offline doubles,146 -M074,testing,offline doubles,276 -M075,testing,offline doubles,123 -M076,contract,declarations/ports/wire,176 -M077,tables (UMF),compiler/planner/containment,104 -M078,tables (UMF),compiler/planner/containment,193 -M079,tables (UMF),compiler/planner/containment,123 -M080,tables (UMF),compiler/planner/containment,185 -M081,tables (UMF),compiler/planner/containment,89 -M082,tables (UMF),compiler/planner/containment,92 -M083,tables (UMF),compiler/planner/containment,395 -M084,tables (UMF),compiler/planner/containment,241 -M085,tables (UMF),compiler/planner/containment,273 -M086,tables (UMF),compiler/planner/containment,134 -M087,tables (UMF),compiler/planner/containment,102 -M088,tables (UMF),compiler/planner/containment,473 -M089,tables (UMF),compiler/planner/containment,338 -M090,tables (UMF),compiler/planner/containment,349 -M091,tables (UMF),compiler/planner/containment,48 -M092,tables (UMF),compiler/planner/containment,434 -M093,tables (UMF),compiler/planner/containment,383 -M094,tables (UMF),compiler/planner/containment,163 -M095,contract,declarations/ports/wire,57 -M096,contract,declarations/ports/wire,101 -M097,packaging/CLI,author tooling,275 -M098,worker/isolation,worker client,38 -M099,worker/isolation,worker client,18 -M100,worker/isolation,worker client,86 -M101,worker/isolation,worker client,189 -M102,worker/isolation,worker client,167 -M103,worker/isolation,worker client,147 -M104,worker/isolation,worker client,72 -M105,worker/isolation,worker client,72 -M106,worker/isolation,worker client,63 -M107,worker/isolation,worker client,119 -M108,worker/isolation,worker client,150 -M109,worker/isolation,worker client,118 -M110,worker/isolation,worker client,193 -M111,worker/isolation,worker client,145 -M112,worker/isolation,worker client,87 -M113,worker/isolation,worker client,148 -M114,worker/isolation,worker client,44 -M115,worker/isolation,worker client,87 -M116,worker/isolation,worker client,164 -M117,contract,declarations/ports/wire,216 -M118,host-dev,composition/lifecycle,13 -M119,host-dev,composition/lifecycle,7 -M120,host-dev,composition/lifecycle,80 -M121,host-dev,composition/lifecycle,134 -M122,host-dev,composition/lifecycle,156 -M123,host-dev,composition/lifecycle,94 -M124,host-dev,composition/lifecycle,104 -M125,host-dev,composition/lifecycle,80 -M126,host-dev,composition/lifecycle,50 -M127,host-dev,composition/lifecycle,146 -M128,host-dev,composition/lifecycle,149 -M129,host-dev,composition/lifecycle,180 -M130,host-dev,composition/lifecycle,62 -M131,host-dev,composition/lifecycle,49 -M132,host-dev,composition/lifecycle,138 -M133,host-dev,composition/lifecycle,89 -M134,host-dev,composition/lifecycle,49 -M135,host-dev,composition/lifecycle,139 -M136,host-dev,composition/lifecycle,348 -M137,host-dev,composition/lifecycle,200 -M138,contract,host contract implementation/orchestration,173 -M139,worker/isolation,host broker/supervisor,484 -M140,worker/isolation,host broker/supervisor,215 -M141,worker/isolation,host broker/supervisor,149 -M142,worker/isolation,host broker/supervisor,160 -M143,contract,host contract implementation/orchestration,430 -M144,contract,host contract implementation/orchestration,152 -M145,platform adapter (Lakebase/Postgres),database execution/state,161 -M146,platform adapter (Lakebase/Postgres),database execution/state,386 -M147,platform adapter (Databricks),platform integration,88 -M148,platform adapter (Databricks),platform integration,331 -M149,platform adapter (Databricks),platform integration,51 -M150,platform adapter (Databricks),platform integration,153 -M151,platform adapter (Lakebase/Postgres),database execution/state,94 -M152,contract,host contract implementation/orchestration,244 -M153,contract,host contract implementation/orchestration,9 -M154,worker/isolation,host broker/supervisor,225 -M155,contract,host contract implementation/orchestration,320 -M156,platform adapter (Databricks),platform integration,271 -M157,platform adapter (Databricks),platform integration,173 -M158,contract,host contract implementation/orchestration,312 -M159,worker/isolation,host broker/supervisor,229 -M160,contract,host contract implementation/orchestration,170 -M161,platform adapter (Lakebase/Postgres),database execution/state,171 -M162,platform adapter (Lakebase/Postgres),database execution/state,276 -M163,platform adapter (Lakebase/Postgres),database execution/state,447 -M164,platform adapter (Lakebase/Postgres),database execution/state,325 -M165,platform adapter (Lakebase/Postgres),database execution/state,265 -M166,platform adapter (Databricks),platform integration,57 -M167,packaging/CLI,admission/artifacts,220 -M168,platform adapter (Databricks),platform integration,278 -M169,platform adapter (Lakebase/Postgres),database execution/state,431 -M170,platform adapter (model gateway),model execution,303 -M171,platform adapter (Lakebase/Postgres),database execution/state,106 -M172,contract,host contract implementation/orchestration,380 -M173,contract,host contract implementation/orchestration,320 -M174,contract,host contract implementation/orchestration,234 -M175,platform adapter (Lakebase/Postgres),database execution/state,216 -M176,contract,host contract implementation/orchestration,66 -M177,platform adapter (Lakebase/Postgres),database execution/state,152 -M178,contract,host contract implementation/orchestration,64 -M179,contract,host contract implementation/orchestration,132 -M180,contract,host contract implementation/orchestration,176 -M181,platform adapter (Lakebase/Postgres),database execution/state,405 -M182,contract,host contract implementation/orchestration,262 -M183,worker/isolation,host broker/supervisor,419 -M184,worker/isolation,host broker/supervisor,389 -M185,worker/isolation,host broker/supervisor,88 -M186,contract,host contract implementation/orchestration,88 -M187,contract,host contract implementation/orchestration,87 -M188,contract,host contract implementation/orchestration,412 -M189,packaging/CLI,admission/artifacts,121 -M190,platform adapter (Lakebase/Postgres),database execution/state,280 -M191,contract,host contract implementation/orchestration,113 -M192,platform adapter (Lakebase/Postgres),database execution/state,235 -M193,contract,host contract implementation/orchestration,146 -M194,contract,host contract implementation/orchestration,221 -M195,contract,host contract implementation/orchestration,375 -M196,platform adapter (Lakebase/Postgres),database execution/state,346 -M197,contract,host contract implementation/orchestration,289 -M198,platform adapter (Lakebase/Postgres),database execution/state,194 -M199,platform adapter (Databricks),platform integration,124 -M200,platform adapter (Databricks),platform integration,190 -M201,platform adapter (Databricks),platform integration,261 -M202,contract,host contract implementation/orchestration,394 -M203,platform adapter (Lakebase/Postgres),database execution/state,264 -M204,platform adapter (Lakebase/Postgres),database execution/state,428 -M205,platform adapter (Lakebase/Postgres),database execution/state,122 -M206,contract,host contract implementation/orchestration,132 -M207,contract,host contract implementation/orchestration,136 -M208,platform adapter (Databricks),platform integration,208 -M209,contract,host contract implementation/orchestration,236 -M210,packaging/CLI,admission/artifacts,148 -M211,contract,host contract implementation/orchestration,500 -M212,packaging/CLI,admission/artifacts,231 -M213,contract,host contract implementation/orchestration,313 -M214,contract,host contract implementation/orchestration,162 -M215,contract,host contract implementation/orchestration,198 -M216,contract,host contract implementation/orchestration,115 -M217,platform adapter (Lakebase/Postgres),database execution/state,108 -M218,contract,host contract implementation/orchestration,191 -M219,contract,host contract implementation/orchestration,245 -M220,packaging/CLI,admission/artifacts,119 -M221,contract,host contract implementation/orchestration,487 -M222,worker/isolation,host broker/supervisor,428 -M223,contract,host contract implementation/orchestration,107 diff --git a/docs/helix/00-discover/boundary-audit/static-cycles.csv b/docs/helix/00-discover/boundary-audit/static-cycles.csv deleted file mode 100644 index e02201f..0000000 --- a/docs/helix/00-discover/boundary-audit/static-cycles.csv +++ /dev/null @@ -1,12 +0,0 @@ -component_id,module_id -SCC-1,M143 -SCC-1,M193 -SCC-1,M197 -SCC-1,M209 -SCC-1,M211 -SCC-1,M213 -SCC-2,M154 -SCC-2,M194 -SCC-3,M003 -SCC-3,M009 -SCC-3,M010 diff --git a/docs/helix/00-discover/boundary-audit/summary.json b/docs/helix/00-discover/boundary-audit/summary.json deleted file mode 100644 index 2864c8b..0000000 --- a/docs/helix/00-discover/boundary-audit/summary.json +++ /dev/null @@ -1,29 +0,0 @@ -{ - "modules": 223, - "import_edges": 2359, - "dynamic_import_candidates": 10, - "direct_reaches": 11, - "categories": { - "contract": 75, - "packaging/CLI": 27, - "platform adapter (Databricks)": 16, - "testing": 16, - "tables (UMF)": 18, - "worker/isolation": 29, - "host-dev": 20, - "platform adapter (Lakebase/Postgres)": 21, - "platform adapter (model gateway)": 1 - }, - "consumer_references": 90, - "dynamic_import_sites": 8, - "non_import_loader_false_positives": 2, - "static_import_edges": 2359, - "graph_edges_including_dynamic_and_discovery": 2367, - "static_strong_components": 3, - "static_strong_component_sizes": [ - 6, - 2, - 3 - ], - "browser_script_resources": 1 -} diff --git a/docs/helix/00-discover/current-state-inventory-boundaries.md b/docs/helix/00-discover/current-state-inventory-boundaries.md deleted file mode 100644 index 5eed3bf..0000000 --- a/docs/helix/00-discover/current-state-inventory-boundaries.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -ddx: - id: batten.boundary-audit - type: current-state-inventory - activity: discover - authoring: - home: repo - links: [] ---- - -# Current-State Inventory: SDK boundaries - -The reference SDK bundles portable declarations, compiler behavior, execution, -tests, and tooling. Its development host relies on application internals. -Structural separation is incomplete even where direct SDK-to-host imports are absent. - -## Scope and Boundary - -- Estate: the owner's read-only reference SDK, development host, and host plugin - modules, inspected 2026-10-29. Source-specific names stay in the separate private - audit packet; Batten owns no dependency on that application. -- Method: Python abstract syntax tree (AST) import census, physical line counts, - module classification, literal dynamic-import/discovery review, and consumer census. -- Evidence: `boundary-audit/modules.csv`, `import-graph.csv`, `external-nodes.csv` - and `summary.json`, generated from that census on 2026-10-29. -- Excluded: executing reference code, private operational data, credentials, - source history, runtime import tracing, and live platform qualification. -- Owner: Erik LaBianca. - -## Evidence Grades - -| Grade | Means | -|-------|-------| -| Evidenced | A dated census demonstrates the structural observation only. | -| Partial | A material structural or behavior fact remains unrecorded. | -| Assumed | A claim has no inspected source. | -| Aspirational | Desired behavior rather than an observed component. | -| Spike-open | An unknown blocks a particular design decision. | - -## Inventory - -Each module has exactly one primary classification in `modules.csv`; mixed -responsibilities retain an explicit role. The table aggregates those assignments. -The contract category includes host contract implementations as well as declarations. - -| Component classification | Modules | Grade | Evidence | -|--------------------------|---------|-------|----------| -| Contract/declaration and host orchestration | 75 | Evidenced | AST census, 2026-10-29 | -| Testing | 16 | Evidenced | AST census, 2026-10-29 | -| Packaging and CLI | 27 | Evidenced | AST census, 2026-10-29 | -| Tables/compiler | 18 | Evidenced | AST census, 2026-10-29 | -| Worker/isolation | 29 | Evidenced | AST census, 2026-10-29 | -| Databricks adapter | 16 | Evidenced | AST census, 2026-10-29 | -| PostgreSQL/Lakebase adapter | 21 | Evidenced | AST census, 2026-10-29 | -| Model-gateway adapter | 1 | Evidenced | AST census, 2026-10-29 | -| Development host | 20 | Evidenced | AST census, 2026-10-29 | - -The census covers 117 SDK modules, 20 development-host modules, and 86 host -plugin modules. Physical line counts, including blanks and docstrings, are -20,487, 2,267, and 19,916 respectively; estimates from intake are not used as measurements. - -There are 2,359 static import edges, including nested and type-only imports. -The graph also represents eight reviewed dynamic-import/discovery sites, using -explicit unresolved-target nodes where runtime observation is required. Three -static strongly connected components contain six, two, and three modules; -`static-cycles.csv` lists their members. Nested/type-only edges do not by themselves -prove a failing runtime circular import. One classic browser-script resource has -no static/dynamic import-pattern matches; it was not executed by this survey. -Ten development-host import sites reach application internals; one additional -site discovers the application dynamically. Checkout-path recognition also couples -installation to the source tree. The SDK has no static application import in this -census. Optional YAML and a lazy web-framework import still need dependency scoping. - -The private packet lists all eleven sites and exact locations, all source module -names, and their crosswalk to the anonymous graph IDs. The public graph retains -external-inventory nodes explicitly. It does not hide an edge because its target -lies outside the selected module set. - -The consumer census finds 90 SDK/development-host/package references in both -installed-plugin and hosted-plugin trees. One tree contains 86 Python files; -the hosted tree contains declarations without Python. These remain distinct -consumer forms for later compatibility assessment. - -## Totals - -| Grade | Classification entries | Modules | -|-------|------------------------|---------| -| Evidenced | 9 | 223 | -| Partial | 0 | 0 | -| Assumed | 0 | 0 | -| Aspirational | 0 | 0 | -| Spike-open | 0 | 0 | - -Zero inventory entries lack structural evidence. None of these counts establishes -runtime behavior, platform support, or completeness of computed imports. - -## Open Questions - -| Question | Blocks | Owner | -|----------|--------|-------| -| Which computed import targets actually load on each execution path? | A complete runtime import claim | Batten implementation owner | -| Which exact platform release cohort preserves all required behaviors? | Compatibility support claim | Erik LaBianca and platform maintainers | -| Which legacy interfaces must the consuming host preserve? | Later consumer transition acceptance | Consuming-host owner | diff --git a/docs/helix/00-discover/intent-and-intake.md b/docs/helix/00-discover/intent-and-intake.md deleted file mode 100644 index 8530cfd..0000000 --- a/docs/helix/00-discover/intent-and-intake.md +++ /dev/null @@ -1,143 +0,0 @@ -# Batten intent and intake - -## Accepted direction - -Source: owner instructions and answers in this conversation, 2026-10-29. - -Batten is the Novirhyza application SDK. It constrains the technology design space -so authors can design data structures, act on them, and deliver UI without -repeating deployment/integration work. It is independently implemented from -behavioral requirements and read-only boundary evidence. It imports no private -host application and carries no private source or history. - -Public platforms are supplied as dependencies: UMF, Weft, Arras, and Tether. -Native UMF documents and typed access are the authoring contract; consuming hosts -own legacy format/API translation. PostgreSQL 18 only; async-first; layered typed -files with environment as last resort and no new environment names. MIT OR -Apache-2.0, copyright Synaptiq. Fabricated data only. Plugins are trusted -first-party code; the sandbox provides permission containment. - -The first reviewed behavioral suite establishes the measured test-count ceiling; -it only decreases afterward. The owner is considering the ontology-provider -module boundary. The proposal places it in a normal Batten platform module and -requires zero ontology-specific core capabilities. - -## Packaged runtime and fleet direction - -Source: owner clarification and authorization to integrate and realign, 2026-10-29. -The complete packaged runtime and deep declarative services are central product -value. Application authors must not need pip/npm installation. The platform owns -qualification of dependency upgrades across applications, enforces telemetry, -assertions and behavioral test coverage, and bounds out-of-scope behavior. - -The scale objective is hundreds of applications sharing infrastructure and -integrating through the graph API and future defined mechanisms. It is an owner -goal, not an observed capacity result. Exact load mix, service budgets, upgrade -policy thresholds and graph integration profiles need design and qualification. -Separate platform-module distributions remain compatible with this direction: -platform assembly resolves a cohort once; applications consume the complete -runtime. This authorizes document alignment, retaining the source/build review gate. - -## Authorized scope - -Deliver the product vision, PRD, concerns, feature registry, boundary audit, -proposed module/distribution/public-host API split, decision records, and ddx -work items. This includes specification of the eventual mechanical checks. - -Wait for owner review before writing a migration plan, executable quality gates, -or product code. Do not edit the read-only reference checkout, copy its history, -push, create a remote repository, or commit without instruction. - -## Decision ownership - -[Decision points](../01-frame/decision-points.md) retain open policy questions -with owners and affected scope. Upstream library maintainers own native semantics -and qualification. Host operators own deployment topology, identity providers, -resource provisioning, policy authority, and legacy behavior compatibility. - -## Next action - -Review the product scope and module boundaries, especially the ontology-neutral -core and generic provider lifecycle. After review, resolve affected policy -questions and prepare the separate two-repository consumer transition plan with -installed and hosted consumer forms and green checks at each slice. - -## Composition and hosting direction - -The owner authorized the next requirements/contracts/ddx packet following the -core-and-extensions discussion. Native UMF is the declarative foundation, UMF -owns saga semantics, and ux-builder supplies the UI design/tooling integration. -Selectable modules, host profiles and execution placement are independent. This -authorization advances design and tracking; it does not authorize source code, -migration, deployment, commits or pushes. The original consumer-transition -requirements remain in scope for their later separately reviewed plan. - -## Interaction composition and extension direction - -Source: owner direction, 2026-10-29. Start with declarative application manifests, -UMF and UMF extensions. Supply high-level semantic controls through ux-builder, -including wizards, grouped/scrollable forms and editable collections. Preserve -composition and detailed application-local control implementations in Python -and/or TypeScript. Local code is an ordinary escape hatch, not a platform exception. - -Adding third-party packages through pip/npm or equivalent dependency mechanisms -is an exceptional platform extension. Using the already selected platform's public -APIs does not add a dependency. Applications cannot expand the installed cohort. -A terminal user interface (TUI) is a design target for the same application -meaning; support must be qualified per control and renderer. This authorizes -requirements/contracts/test allocation, retaining the existing source review gate. - -## Attribution, audit and mutation direction - -Source: owner direction, 2026-10-29. Robust user attribution and audit are core -Batten requirements. Command Query Responsibility Segregation (CQRS) is the default -exposed mutation model: declared commands change state; queries read it. Every -database, messaging, AI gateway and other system interaction carries OpenTelemetry -(OTel) telemetry and the strongest supported user attribution. Preserve initiating -user, delegation and effective service identity across asynchronous boundaries; -report unsupported native attribution explicitly rather than inventing a user. -This authorizes specification evolution; the existing source/build review gate remains. - -## Platform asset direction - -Source: owner direction, 2026-10-29. Applications must be able to carry deployment -packages for tables, pipelines and other platform assets, require assets managed -elsewhere, or combine both. Hide provider details behind a generic platform -wrapper wherever semantics permit. Databricks bundle syntax and Unity Catalog -bindings belong to the provider, outside the core interface. This authorizes -requirements, contracts and test allocation; production applies, secret access, -migrations and product implementation retain their separate authorization gates. - -## Application interoperability direction - -Source: owner discussion and authorization to evolve HELIX specifications, -2026-10-29. Applications share governed ontology types and discover each other's -services/shapes through a small Batten-owned platform ontology. Application, -ServiceInterface, ServiceExport, ServiceRequirement and ServiceBinding express -provider offers, consumer needs and host-approved resolutions. - -UMF owns portable model/action meaning; Arras owns ontology capabilities. Batten -owns its platform definitions and binding rules in the optional provider module; -core remains ontology-neutral. Shared business types have independent ownership -and exact artifact identity. Graph discovery and explicit bindings use the same -contracts. Discoverability, binding and current execution permission are distinct. - -Table, API and messaging access are possible transport profiles, each requiring -an explicit owner export and qualified authority/consistency contract. Raw shared -connections remain prohibited. Read-only governed table exports are the initial -table design assumption; cross-application mutations use owner commands unless a -separate writable profile is explicitly contracted. Exact matches, immutable -bindings and explicit provider selection are design defaults, not live evidence. -This authorizes specs, native model and verification allocation; source code, -migrations, production changes, commits and pushes remain separately gated. - -## Semantic testing and platform migration direction - -Source: owner direction in this conversation, 2026-10-29. Batten must expose -application intent and use-case refinements as testable semantics. Every default -fully declarative construct, including composed UI and declarative hooks, must -expose its complete functionality through the CLI and automatically produce -property-based end-to-end tests. Every fully declarative UI-and-hook implementation -must receive an automatic conformance verdict, reusable to qualify migration to -new platforms. Missing semantics, oracles or execution coverage cannot silently -pass. This direction authorizes specification and integration, not runtime code. diff --git a/docs/helix/00-discover/product-vision.md b/docs/helix/00-discover/product-vision.md index 2d87b91..e75dc19 100644 --- a/docs/helix/00-discover/product-vision.md +++ b/docs/helix/00-discover/product-vision.md @@ -121,7 +121,7 @@ These learning indicators establish no customer-adoption gate. ## Why Now -The [boundary survey](current-state-inventory-boundaries.md) identifies concrete +The boundary survey identifies concrete coupling between an existing development host and its application, alongside compiler, worker, testing, and packaging responsibilities in one SDK. The owner has chosen a cleanroom implementation with native platform dependencies. That diff --git a/docs/helix/00-discover/research/convex.md b/docs/helix/00-discover/research/convex.md deleted file mode 100644 index 4dfcc8a..0000000 --- a/docs/helix/00-discover/research/convex.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -ddx: - id: batten.research.convex - type: resource-summary - activity: discover - authoring: - home: repo - links: [] ---- - -# Convex application composition - -## Source - -- URL: [Convex overview](https://docs.convex.dev/understanding/overview). -- Accessed: 2026-10-29; current documentation, not a pinned software release. - -## Summary - -Convex is a reactive database platform connecting server functions and application -clients. Its documentation describes provisioning and subscriptions that reduce -repeated backend setup for application developers. - -## Relevant Findings - -- Database, server functions, and client libraries form one developer experience. -- Queries and mutations provide distinct read/write surfaces. -- Client subscriptions update when underlying query dependencies change. -- Inference for Batten: reducing assembly work depends on coherent responsibility - boundaries across the developer workflow, beyond individual useful libraries. - -## HELIX Usage - -Informs `batten.product-vision` as adjacent prior art for coordinated data, -behavior, and client tooling. Compare the first Batten workflow against the work -it requires from app authors, without assuming Convex compatibility or feature parity. - -## Authority Boundary - -This source describes Convex. It establishes no Batten runtime, database, -reactivity, transaction, hosting, or service requirement. The owner and subsequent -requirements determine which outcomes matter for Batten. diff --git a/docs/helix/00-discover/research/foundations.md b/docs/helix/00-discover/research/foundations.md deleted file mode 100644 index 686c306..0000000 --- a/docs/helix/00-discover/research/foundations.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -ddx: - id: batten.research.foundations - type: resource-summary - activity: discover - authoring: - home: repo - links: [] ---- - -# Novirhyza foundation survey - -## Source - -- Sources: local UMF product vision and README; Tether, Weft, and Arras READMEs. -- Repository URLs: [UMF](https://github.com/DocumentDrivenDX/umf), - [Tether](https://github.com/DocumentDrivenDX/tether), - [Weft](https://github.com/DocumentDrivenDX/weft), - [Arras](https://github.com/DocumentDrivenDX/arras). -- Accessed: 2026-10-29. Local documentation was inspected; remote parity was not checked. - -## Summary - -The four named foundations cover data meaning, agent execution, query compilation, -and an application interface over typed data and actions. Their documented -surfaces provide composition candidates for Batten. The inspected documentation -qualifies support by version and subset and retains application/host obligations. - -## Relevant Findings - -- UMF is a machine-readable metamodel and schema interchange fabric. Its vision - emphasizes preserving native meaning and reporting translation loss. -- Tether is a Python agent-harness library with typed tools, policy, and durable - sessions. Its inspected README names Pydantic AI Agent integration and scoped - local/PostgreSQL runtime evidence. -- Weft compiles SQL using supplied UMF modules into backend SQL, parameters, - result types, decoding instructions, and diagnostics. Its README identifies - Rust, Python bindings, browser WebAssembly, and selected backend profiles. -- Arras is an interface to an ontology with UMF-defined types/actions, backend - contracts, and a React operator console/Graph Browser. Its host supplies - identity and configuration. -- Inference: these surfaces are relevant to the proposed data/action/UI authoring - experience. A fresh composition must define who handles the retained host duties. - -## HELIX Usage - -Informs `batten.product-vision` and requirements intake. Use the foundation roles -to identify questions and candidate integration boundaries, then inspect the -selected upstream contracts and version evidence before design commitments. - -## Authority Boundary - -This is a bounded documentation survey, not code or contract qualification. -Sibling implementation, languages, licenses, and release claims do not become -Batten requirements. The owner has not yet defined cleanroom reuse boundaries -or required compatibility. Batten requirements and designs own those decisions. diff --git a/docs/helix/00-discover/research/mcp-apps.md b/docs/helix/00-discover/research/mcp-apps.md deleted file mode 100644 index 925c932..0000000 --- a/docs/helix/00-discover/research/mcp-apps.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -ddx: - id: batten.research.mcp-apps - type: resource-summary - activity: discover - authoring: - home: repo - links: [] ---- - -# Tool and UI composition in MCP Apps - -## Source - -- URL: [OpenAI MCP server and UI quickstart](https://developers.openai.com/plugins/build/app-quickstart). -- Accessed: 2026-10-29; current documentation, not a pinned software release. - -## Summary - -The Model Context Protocol (MCP) Apps flow connects tool calls and interactive UI -resources through a host. OpenAI's quickstart illustrates a to-do workflow using -an MCP server and a UI component. - -## Relevant Findings - -- Tools and UI resources can be exposed through one host-facing integration. -- The tutorial still requires a reachable server endpoint for connection. -- Inference for Batten: a tool/UI contract and a deployment experience address - distinct parts of the app author's work. - -## HELIX Usage - -Informs `batten.product-vision` and the question of which delivery/integration -responsibilities Batten handles. This is adjacent prior art; the owner's phrase -“apps SDK” has not been interpreted as requiring ChatGPT or MCP compatibility. - -## Authority Boundary - -This source describes an external application-host model. It establishes no Batten -protocol, provider, embedding, authentication, deployment, or compatibility choice. -The PRD and architecture will own any selected host contract. diff --git a/docs/helix/01-frame/feature-registry.md b/docs/helix/01-frame/feature-registry.md index b4dde50..6f3e909 100644 --- a/docs/helix/01-frame/feature-registry.md +++ b/docs/helix/01-frame/feature-registry.md @@ -47,7 +47,7 @@ follow the owner's scope review rather than empty placeholder files. ## Relevant References -[PRD](prd.md), [concerns](concerns.md), [boundary audit](../00-discover/current-state-inventory-boundaries.md), +[PRD](prd.md), [concerns](concerns.md), boundary audit, [architecture](../02-design/architecture.md), and [open decisions](decision-points.md). Feature dependencies describe capability relationships, not an implementation or migration sequence. diff --git a/docs/helix/01-frame/features/FEAT-002-operations-and-interfaces.md b/docs/helix/01-frame/features/FEAT-002-operations-and-interfaces.md index 92dce94..0e5f8de 100644 --- a/docs/helix/01-frame/features/FEAT-002-operations-and-interfaces.md +++ b/docs/helix/01-frame/features/FEAT-002-operations-and-interfaces.md @@ -116,7 +116,7 @@ Batten owns the optional adapter implementing Lintel's neutral public execution ports; Lintel must not import Batten, and generic Batten core must not import Lintel/GraphQL. Host composition supplies the binding and router explicitly. REST/OpenAPI product API generation is outside this slice. See -[SD-002](../../02-design/solution-designs/SD-002-lintel-graphql-relay.md) and Lintel's +SD-002 and Lintel's [US-004 client](https://github.com/DocumentDrivenDX/lintel/blob/main/docs/helix/01-frame/user-stories/US-004-typescript-clients.md) and [US-005 embedding](https://github.com/DocumentDrivenDX/lintel/blob/main/docs/helix/01-frame/user-stories/US-005-batten-embedding.md) acceptance slices. Batten-specific Technical Designs and contract amendments diff --git a/docs/helix/02-design/adr/ADR-005-sdk-series-and-cohort-compatibility.md b/docs/helix/02-design/adr/ADR-005-sdk-series-and-cohort-compatibility.md deleted file mode 100644 index 79299cc..0000000 --- a/docs/helix/02-design/adr/ADR-005-sdk-series-and-cohort-compatibility.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -ddx: - id: ADR-005 - type: adr - activity: design - authoring: - home: repo - links: - - id: batten.prd - kind: derived_from - - id: ADR-003 - kind: informed_by ---- - -# ADR-005: SDK series is independent of the embedding host release - -## Problem - -A plugin must declare the contract it uses without being rebuilt for every host -release. Separately installed modules also need explicit platform compatibility. - -## Decision - -A plugin declares `sdk` as the Batten contract's `MAJOR.MINOR` series. The host -admits equal major and plugin minor no greater than its supported minor. Required -module capabilities, manifest format, worker protocol, browser protocol, and -installed distribution constraints are checked separately before plugin execution. -Passing the series check alone never establishes complete compatibility. - -The proposed first stable series is `1.0`; this assigns no published release and -claims no compatibility with another SDK's identically numbered series. Development -artifacts use explicit prerelease versions. A common Batten release cohort pins -exact wheel versions; the host reports its tested upstream platform cohort. - -Optional compatible fields/methods can add a minor. Removal, changed meaning, -new required fields, or a narrower accepted input contract require a major. -Patch releases preserve contract semantics. Unknown required components refuse; -unknown optional extension content is retained, not executed or silently dropped. - -Deprecation is announced for a minor before removal and includes a replacement; -removal still requires the major change. Later host-owned legacy compatibility -has its own consumer tests and does not alter Batten's native contract. - -## Fleet upgrade qualification - -PRD FR-42 makes safe dependency evolution a platform responsibility. Before a -candidate cohort qualifies, the platform must inventory affected applications -and declared integrations, run their required assertions and behavior coverage, -and verify required telemetry and protocol compatibility. Evidence must bind -exact candidate runtime, application and policy inputs; changing them invalidates -the result. A series match or a passing platform-only suite is insufficient. - -The operator must be able to withhold a failing candidate and retain a qualified -cohort. Recovery must assess durable-state compatibility and preserve uncertain -external outcomes. There is no implicit schema/data rollback. Exact evidence -formats, required telemetry failure policy and rollout controls need contracts -before source implementation. No fleet upgrade has been qualified in this packet. - -## Why We Chose This - -### Over matching the host product version - -Contract versions track application-facing meaning. A host release that changes -unrelated behavior should not invalidate every plugin. - -### Over checking only SDK major/minor or dependency names - -The selected capability and installed platform release may still be incompatible. -Independent wire/format/dependency checks make that refusal explicit. - -## Consequences - -**Good**: Authors know the contract series and capabilities their artifact needs. - -**Trade-offs**: Release qualification must publish a real compatibility matrix; -cohort combinations outside it carry no support claim. - -**Drift signals to watch**: importing code before metadata checks, name-only -dependency admission, or changing behavior under a patch without contract review. - -## Concern Impact - -Implements artifact admission, native-platform qualification, and cleanroom identity. diff --git a/docs/helix/02-design/adr/ADR-007-quality-and-test-ratchets.md b/docs/helix/02-design/adr/ADR-007-quality-and-test-ratchets.md deleted file mode 100644 index a33169e..0000000 --- a/docs/helix/02-design/adr/ADR-007-quality-and-test-ratchets.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -ddx: - id: ADR-007 - type: adr - activity: design - authoring: - home: repo - links: - - id: batten.prd - kind: derived_from - - id: batten.concerns - kind: informed_by ---- - -# ADR-007: Enforce boundaries, shape, and a decreasing test budget - -## Problem - -Module names do not enforce boundaries. Large units and duplicated tests can -recreate a monolith even with a platform package layout. A greenfield test count -of zero cannot be the permanent ceiling while implementing required behavior. - -## Decision - -Implement CONTRACT-002's actual import/public-surface, cycle, code-shape, and -test-count checks before dependent feature code. One local quality entry point -is used by edit checks, pre-commit, and CI; it fails rather than skipping because -the comparison base or module inventory is missing. - -Use the fewest tests that pin observable behavior, one primary test per behavior, -with parameterized inputs and whole-outcome assertions. Reuse an existing scenario -before adding another. Separate integration/registry/browser outcomes only where -they prove a distinct boundary; preserve authorization, non-disclosure, isolation, -and concurrency invariants exactly once each. - -The owner authorized the first reviewed behavioral suite to establish the measured -test-count ceiling. After that, the ceiling and count only decrease. No automatic -growth exception, renamed helper-test, hidden body, duplicate layer, skipped test, -or count change can evade the rule. New genuinely distinct behavior that cannot -fit requires an owner decision changing this policy, not a silent gate bypass. - -The exact code-shape limits come from the stricter of the observed reference -ceilings and the installed greenfield defaults, as recorded in CONTRACT-002. -No numeric test budget, coverage floor, latency target, or claimed platform -capacity is invented. Numeric policy values and measured outcomes are distinct. - -## Browser tooling - -Use Oxlint's ESLint-compatible complexity, function-line, nesting and class-count -rules with the exact CONTRACT-002 ceilings. TypeScript compilation remains a -separate strict check. This removes the lint parser's TypeScript-version peer -constraint and its legacy dependency tree while preserving the selected gates. -The common quality recipe must prove each rule with passing and failing controls. - -Run browser tooling on the pinned Node 26 LTS interpreter. Browser acceptance -tests use JavaScript Playwright against the installed Python -host. Python Playwright and its pyee dependency leave the development cohort. -The same two canonical scenarios and every authorization, lifecycle, receipt and -telemetry assertion remain visible in their registered test bodies. The Node declaration cohort uses the latest undici-types minor through an -explicit root override, qualified with strict declaration checking and the same -browser scenarios. It introduces no HTTP runtime implementation. Browser test -registrations and assertion-bearing helpers participate in the global census; -a language migration cannot reduce the measured count by hiding test code. - -## Application evidence and upgrade gates - -PRD FR-27/29/42 require host-enforced telemetry, application assertions and test -coverage of declared behavior for admission and candidate runtime qualification. -Required evidence must be current for exact application/cohort inputs and cannot -be replaced by a coverage percentage or a declared list of tests. Missing, failing -or stale evidence refuses the affected admission or upgrade qualification. - -This strengthens behavioral assurance while preserving the decreasing function -budget: consolidate redundant tests without dropping distinct invariants. No -numeric code-coverage floor or automatic test-count exception is introduced. -CONTRACT-002 governs evidence obligations; telemetry schema, runtime failure policy -and evidence exchange remain downstream contract work before implementation. - -## Why We Chose This - -### Over a test-growth trailer as an automatic exception - -The owner requires a ceiling that only moves down. An automatic positive-growth -exception would defeat that stronger requirement. - -### Over one test per function or repeated coverage at every layer - -Tests should detect a distinct failure at a public boundary. A private refactor -should not force rewriting several tests of the same outcome. - -## Consequences - -**Good**: Boundary and quality claims are executable, and suite maintenance has -an explicit budget tied to measured behavior coverage. - -**Trade-offs**: The first suite needs deliberate review. Subsequent changes must -consolidate redundancy without hiding missing behaviors or changing tests to match defects. - -**Drift signals to watch**: undocumented exclusions, raised limits, missing-base -passes, renamed tests, growing parameter tables that mix unrelated behavior, or -claims of mechanical enforcement based only on a document. - -## Concern Impact - -Records stricter branch/test-file limits for code-shape-ceilings and the -owner's stronger testing policy. The checks' implementation follows the review gate. - -## Semantic generation decision - -FR-47 requires automatic property-based end-to-end suites and complete CLI access -for all default fully declarative constructs and UI/hook compositions. Author -intent and effective refinements define the model; qualified adapters exercise -each platform and renderer against its oracle. Reuse those properties for migration. -Shared behavior runners and generated cases must preserve the decreasing function -budget. There is no automatic growth exception. The property-testing framework, -CLI/test-model protocols and evidence format need separate selection/contracts; -this direction authorizes no package installation or runtime implementation. diff --git a/docs/helix/02-design/adr/ADR-014-independent-reference-app-specifications.md b/docs/helix/02-design/adr/ADR-014-independent-reference-app-specifications.md deleted file mode 100644 index 4f76438..0000000 --- a/docs/helix/02-design/adr/ADR-014-independent-reference-app-specifications.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -ddx: - id: ADR-014 - type: adr - activity: design - authoring: - home: repo - links: - - id: batten.prd - kind: informed_by ---- - -# ADR-014: Independently scoped reference applications - -## Problem - -Reference apps must describe business outcomes independently of SDK internals. -One shared spec tree can confuse an app requirement with a platform requirement -and let a passing platform unit test masquerade as a complete app journey. - -## Decision - -Each app has a nested HELIX marker binding only its own `specs/` tree. The SDK -retains its existing root. A shared Batten app workflow specializes the installed -HELIX lifecycle through repository instructions; it does not fork the catalog, -add a second public skill or invent an unsupported methodology resolver. - -Corpus references qualify artifact identity with the application ID and path. -Each scope resolves its own local artifact links. Platform contracts are explicit -file dependencies, not unregistered cross-flow graph edges. Repeated generic -requirements use shared obligations; app-specific business rules remain local. - -## Why We Chose This - -### Over a single shared application PRD - -Independent roots preserve each app's user outcome, owner decisions and evidence. -They can be targeted by opening that app directory and invoking HELIX there. - -### Over a vendored HELIX catalog or new helix-batten skill - -Installed templates and prompts remain authoritative. Batten owns only the -product-specific selection, inputs and exit gates. A future native catalog -extension requires upstream agreement rather than a guessed plugin API. - -## Consequences - -**Good**: Each example is an independent specification and qualification target. -**Trade-offs**: Aggregate tooling must understand nested roots and qualified IDs. -**Drift signals to watch**: Shared root assumptions, copied methodology templates, -or changing an app's expected result merely to match a provider defect. - -## Concern Impact - -Preserves cleanroom boundaries, fewest-tests policy and platform modularity. -The corpus is author/test data, never a portable-core runtime dependency. diff --git a/docs/helix/02-design/architecture.md b/docs/helix/02-design/architecture.md index c5f81b1..aed9188 100644 --- a/docs/helix/02-design/architecture.md +++ b/docs/helix/02-design/architecture.md @@ -21,7 +21,7 @@ ddx: Batten has a platform-neutral application core and independently installed platform modules. This is the proposal for the owner's first review. It covers PRD FR-1–44 and FR-46. The composition/hosting packet elaborates the owner-selected -next design slice; migration and product code still require build authorization. The [boundary audit](../00-discover/current-state-inventory-boundaries.md) +next design slice; migration and product code still require build authorization. The boundary audit precedes this target model. **Pure core has zero ontology-specific capabilities.** Its capabilities are: @@ -206,7 +206,7 @@ Application declarations cannot install or replace a privileged platform provide admission, permissions, or dispatch as a second test-only host. **Boundary Check**: the specified entry point is -`uv run python scripts/check_boundaries.py --base HEAD`, with CONTRACT-002's +`uv run python scripts/check_boundaries.py`, with CONTRACT-002's per-module allowlists, public-export checks, and negative controls. It will be implemented only after this review. Documentation validation is not evidence that an import gate already executes; dependent source work requires that gate. diff --git a/docs/helix/02-design/contracts/CONTRACT-001-public-host-api.md b/docs/helix/02-design/contracts/CONTRACT-001-public-host-api.md index 253ed4b..6e67026 100644 --- a/docs/helix/02-design/contracts/CONTRACT-001-public-host-api.md +++ b/docs/helix/02-design/contracts/CONTRACT-001-public-host-api.md @@ -10,8 +10,6 @@ ddx: kind: derived_from - id: ADR-004 kind: informed_by - - id: ADR-005 - kind: informed_by --- # Public host API contract diff --git a/docs/helix/02-design/contracts/CONTRACT-002-boundaries-and-quality.md b/docs/helix/02-design/contracts/CONTRACT-002-boundaries-and-quality.md deleted file mode 100644 index 391a219..0000000 --- a/docs/helix/02-design/contracts/CONTRACT-002-boundaries-and-quality.md +++ /dev/null @@ -1,320 +0,0 @@ ---- -ddx: - id: CONTRACT-002 - type: contract - activity: design - authoring: - home: repo - links: - - id: batten.architecture - kind: derived_from - - id: ADR-001 - kind: informed_by - - id: ADR-007 - kind: informed_by ---- - -# Module boundary and quality contract - -**Contract ID**: CONTRACT-002 -**Type**: boundary and verification interface -**Version**: proposed v1 - -## Purpose - -Specify mechanical import, public-surface, size/complexity, and test-count gates -for the proposed module split. These are the obligations of the first executable -scaffold after the owner's review, before dependent feature implementation. - -## Scope and Boundaries - -- In scope: every handwritten Python/browser module, tools, tests, adapter import - closures, packaged-artifact checks, local/edit/hook/CI entry points, and ratchets. -- Excluded: dependency environments, lockfiles, generated compiler output, and - build artifacts through explicit generated-path rules. No handwritten source - or test file receives an exception. -- Owner: Batten; Erik LaBianca owns review of the first measured test budget. - -## Normative Surface - -Each row defines an import contract, not merely a suggested folder. Python -standard-library imports are allowed unless another rule forbids an effect. -`C` means `batten.contracts`, `R` means `batten.runtime`. - -| Contract name | Module | Other Batten roots allowed | Third-party roots allowed | -|---------------|--------|----------------------------|---------------------------| -| BND-C | `batten.contracts` | None | None | -| BND-R | `batten.runtime` | C | None | -| BND-P | `batten.packaging` | C | `packaging`; build/test executables through explicit tool boundary | -| BND-T | `batten.testing` | C, R | None in portable doubles; `pytest` only in runner adapter | -| BND-N | `batten.umf` | C | Exact public UMF APIs in the selected cohort; no native engine reimplementation | -| BND-HOST | `batten.hosting` | C, R | `pydantic`, `pydantic_settings`; selected public factories supplied through a closed trusted catalog | -| BND-UX | Optional ux-builder browser adapter | Public browser-client API | Pinned public ux-builder packages; no Python/Bun/Node runtime or private host imports | -| BND-U | `batten.tables` | C | Public `umf_core`, `umf_codegen`, `umf_access`, `weft` surfaces in selected cohort | -| BND-W | `batten.workers` | C, R | None; OS capabilities qualified separately | -| BND-G | `batten.postgres` | C, public `batten.messaging` for the messaging provider | Public `psycopg` surfaces | -| BND-MSG | `batten.messaging` | C | None; codec and provider protocols injected | -| BND-L | `batten.lakebase` | C | Public `databricks.sdk` authority/endpoint/role surfaces | -| BND-ST | `batten.storage` | C; local implementation may import its own public protocol | None | -| BND-PLT | `batten.platform` | C | None; provider-neutral values/protocols only | -| BND-D | `batten.databricks` | C, public `batten.storage`, public `batten.platform` | Public `databricks.sdk` resource surfaces; pinned CLI only through explicit deployment-tool boundary | -| BND-M | `batten.gateway` | C | `httpx` or a cohort-declared injected public gateway client | -| BND-A | `batten.arras` | C | Public `arras`, `umf_core`, `umf_access`; owns CONTRACT-009 platform model interpretation and resolution evidence, never core ontology types | -| BND-H | `batten.tether` | C | Public `tether` surfaces | -| BND-I | `batten.asgi` | C | `fastapi`, `starlette`; ASGI protocol types | -| BND-Q | `batten.mcp` | C | Public `mcp` surfaces | -| BND-V | `batten.dev` | Public APIs of all selected Batten modules | `pydantic_settings`, `pydantic`, `uvicorn`, public PostgreSQL 18 helper, explicit build tools | -| BND-B | Browser client | Own browser-client public modules | Browser APIs; no runtime Node/Bun modules; declared build/test tools only in build/test sources | - -Exact upstream exports and supported versions MUST come from the selected public -cohort manifest. A permitted package root does not permit private submodule imports. -Unlisted third-party and consuming-application roots are forbidden by default. -Sibling platform adapters MUST NOT import one another; composition injects their -public protocol products. Both halves of a bidirectional integration remain owned. - -The checker MUST: - -1. Parse every source module, including nested imports, aliases, relative imports, - optional imports, and type-checking imports. Resolve every Batten module to - exactly one boundary row; unclassified handwritten source fails. -2. Check direct and transitive Batten dependencies, cycles, self-cycles through - re-export barrels, and access to another module's private names. Export inventories - are explicit; a namespace root must not eagerly import optional modules. -3. Inventory dynamic imports, entry points, loader calls, path mutation, and - process module launches. Computed targets require a declared, owned loader - boundary and installed-artifact observation; they are never ignored as safe. -4. Reject undeclared ambient environment reads and configuration/credential reader - effects outside the composition/owning adapter boundaries. -5. Inspect wheel metadata and a clean installed environment for each published - dependency closure. Optional-import fallbacks cannot hide an undeclared dependency. -6. Verify an allowed edge passes and a forbidden edge fails in a temporary - fixture through the actual checker. Cover a cycle and private export breach. - Negative controls are removed from the product tree after the check. - -Core schema/dispatch semantic review MUST additionally prove no ontology-specific -types or branches. An import scanner alone cannot prove this property, runtime -reflection targets, or permission containment. - -Core MUST also contain no native bundle, Unity Catalog, workspace or platform -asset types/branches. `batten.platform` is an optional protocol module, not a new -core dependency. Native source interpreters and CLI launches belong to their -provider/deployment-tool boundary. Installed core and generic wrapper must import -without Databricks packages or a CLI. A bundle's remote code/library closure is -subject to CONTRACT-003 admission; deployment artifacts cannot bypass cohort policy. - -### Gate entry points - -The proposed local command is -`uv run python scripts/check_boundaries.py --base HEAD`. -The complete recipe is `just lint`: boundary check, Ruff check/format, -strict type checking, file-size and ceiling ratchets, and test-count ratchet. -Post-edit checks, pre-commit, and CI call that same recipe or its documented -affected-file front end; the full recipe runs before code-work closeout. - -Missing base, missing module rules, missing public-export inventory, and a -missing ratchet baseline MUST fail. No network remote or upstream branch is -required: a local reviewed base or explicit approved baseline is sufficient. -The recipe and checker files are proposal interfaces to implement after review; -their names in documentation are not an execution result. - -### Shape ceilings - -| Rule | Ceiling | Authority | -|------|---------|-----------| -| Handwritten source physical lines/file | 500 | Installed greenfield default, stricter than observed reference 501 | -| Test physical lines/file | 488 | Observed reference policy, stricter than installed default 800 | -| Python cyclomatic complexity/function | 10 | Observed reference and installed greenfield default | -| Python statements/function | 40 | Observed reference and installed greenfield default | -| Python returns/function | 6 | Observed reference and installed greenfield default | -| Python branches/function | 9 | Observed reference, stricter than installed default 12 | -| Python public methods/class | 15 | Installed greenfield default, stricter than observed reference 18 | -| Browser JavaScript/TypeScript complexity/function | 10 | Installed greenfield ESLint default | -| Browser function nonblank/noncomment lines | 60 | Installed greenfield ESLint default | -| Browser nesting depth | 4 | Installed greenfield ESLint default | -| Browser classes/file | 1 | Installed greenfield ESLint default | - -Ruff rules MUST select the actual complexity/statement/branch/return/public-method -checks; browser lint MUST enforce the listed shape rules. Parameter counts receive -cohesion review, not wrappers introduced solely to satisfy an argument count. -Numbers above are policy choices with sources, not measurements of Batten code. -Every ceiling only decreases. Rule suppression, per-file exceptions, renamed -exclusions, and changing the counter to hide growth fail the ratchet. - -### Test-count policy - -The first reviewed behavioral suite establishes the measured ceiling. Thereafter -each accepted change MUST satisfy both actual function count no greater than -the prior accepted count and configured ceiling no greater than its prior value. -The ceiling is lowered to reflect accepted reductions. - -Count all test functions/registrations across root tests, module tests, shipped -application tests, and browser tests. Parameterized cases count once per behavior -test. Renamed former tests, hidden helper bodies, delegated test wrappers, and -dynamic registrations do not remove a behavior's code from the census. Review -tables to ensure they vary inputs rather than bundle unrelated outcomes. - -One public-boundary test asserts a behavior's whole outcome. Another layer earns -a test only for a distinct observable property. Prefer extending an existing -table before adding a function. Keep each distinct authorization, disclosure, -isolation, ordering, and concurrency invariant exactly once. Do not assert the -type checker, language defaults, private helper structure, or incidental wording. - -Database-process tests MUST be integration tests. Registry-inventory checks are -marked as such. Browser races fail and are fixed at their synchronization, without -blind retries. Tests await observable state, events, or controlled clocks rather -than sleeping. The behavior-to-acceptance mapping follows any consolidation. -No positive-growth trailer automatically authorizes exceeding the ceiling. - -### Application and cohort evidence obligations - -For PRD FR-27/29/42, admission and upgrade qualification MUST require assertions -and test evidence for declared application behavior. Evidence MUST bind exact -application artifact, runtime cohort, required interfaces and effective evidence -policy. Missing, failing, stale or mismatched required evidence MUST refuse the -affected admission or qualification; metadata presence alone MUST NOT count as a -passing assertion. A changed runtime dependency MUST invalidate its prior evidence. - -Candidate-cohort qualification MUST identify affected applications and declared -integration dependents, exercise their required behavior against the candidate, -and verify required telemetry capture and compatibility. It MUST preserve separate -installed/native/browser/deployed evidence scopes. Runtime telemetry enforcement -MUST remain host-owned; an application MUST NOT opt out of required capture. -Capture loss MUST be visible and MUST NOT be reported as a successful observation. - -The behavior-to-assertion mapping MUST survive test consolidation. Behavioral -coverage and the decreasing function-count ceiling MUST both hold; this contract -sets no percentage threshold or growth exception. Evidence wire format, telemetry -catalog, bounded sink-failure policy and upgrade control API remain unselected -and MUST be contracted before their implementation. These obligations do not -add fields to CONTRACT-003's structural composition schema. - -## Precedence and Compatibility - -The owner's review gate postpones executable scaffold changes until review; -it does not waive the gate before dependent feature work. ADR-007 governs policy. -The first reviewed measured baseline is the sole initial-budget exception. -Thereafter a change to the policy itself requires an explicit owner ruling. - -Static analysis and installed-artifact observations are separate evidence layers. -Neither proves arbitrary runtime code isolation. Support claims identify the -versions, operating system, subset, and native/browser/deployed observations used. - -## Error Semantics - -| Condition | Error / Outcome | Retry | Recovery Expectation | -|-----------|------------------|-------|----------------------| -| Forbidden import/transitive edge | Nonzero; source, line, target and violated contract | After fix | Move behavior to its owner or inject a public service. | -| Private export, cycle, unclassified source | Nonzero; exact module/path and rule | After fix | Repair boundary; no blanket baseline exception. | -| Dynamic target lacks evidence | Nonzero readiness result for affected loader path | After qualification | Record owned target policy and installed-artifact observations. | -| Shape limit or suppression | Nonzero; measured unit and allowed ceiling | After split | Split by responsibility; never raise ceiling. | -| Test count grows or baseline increases | Nonzero; before/after counts and scoped sources | After consolidation | Preserve behavior coverage; owner resolves genuine policy conflicts. | -| Missing baseline/rules/base | Nonzero; missing input named | After setup | Supply local approved baseline; do not skip or fabricate. | - -## Application control dependency boundary - -CONTRACT-003/005 govern local Python/TypeScript controls. Closure checks MUST -cover their source imports and generated bundles, including dynamic/remote loads -and vendored libraries. Local code may import language standard facilities and -explicitly supplied public platform APIs; mere transitive installation does not -expose a supported application API. Unapproved additions MUST fail admission -without fetching or executing code. Approved exceptional platform extensions -retain isolated dependency ownership and the same global quality ceilings. - - -## Examples - -```text -Allowed: batten.arras -> batten.contracts -Allowed: batten.arras -> public Arras API in the selected cohort -Forbidden: batten.runtime -> batten.arras -Forbidden: batten.dev -> private consuming-host factory -Forbidden: batten.lakebase -> batten.postgres private connection helper -Allowed: composition injects Lakebase authority into public PostgresServices -``` - -## Non-Normative Notes - -An AST-based project checker is the proposed import-linter equivalent. Its -scaffold must prove real positive and negative controls before it can be called -enforced. The reference audit script is an analysis aid outside the product, -not Batten's future checker or a reusable implementation imported from the reference. - -### Semantic conformance obligations - -FR-47 qualification MUST cover every default fully declarative construct and -every required behavior in a fully declarative UI-and-hook composition, after -use-case refinements. Complete functionality MUST be exposed through CLI adapters. -Tooling MUST generate property-based end-to-end suites automatically without -per-application handwritten scenarios. Required semantic coverage MUST include -transitions, validation, authorization, confirmation, cancellation, effects, -uncertainty and recovery wherever declared. Real renderer behavior MUST be tested -through its actual client; CLI operation parity alone MUST NOT qualify a UI. - -The expected semantic model MUST remain distinct from the implementation under -test. Negative controls MUST demonstrate that a wrong transition, lost refinement -or changed hook effect fails. Invalid declarations or missing semantic oracles, -CLI mappings, generator support or required coverage MUST refuse qualification; -unsupported cases MUST NOT be skipped into a passing result. Every default -construct remains required scope even if its adapter is not yet implemented. - -Evidence MUST bind application, refinements, upstream semantic definitions, -generator/oracle version, platform cohort and evidence policy, and retain replay -seeds, execution traces, minimized failing examples, coverage and exploration -bounds. A passing bounded run MUST NOT be described as proof for every unbounded -execution. The same semantic properties MUST qualify a new platform; an adapter -MUST NOT weaken the oracle to make migration pass. Generated cases MUST share -behavior runners under the existing function-count ceiling. Hook code outside -qualified declarative semantics MUST supply explicit contracts/oracles before -claiming automatic conformance. Wire formats, CLI commands and generator APIs -remain downstream contracts; no schema field or testing library is selected here. - -## Precedence and Compatibility - -The owner's review gate postpones executable scaffold changes until review; -it does not waive the gate before dependent feature work. ADR-007 governs policy. -The first reviewed measured baseline is the sole initial-budget exception. -Thereafter a change to the policy itself requires an explicit owner ruling. - -Static analysis and installed-artifact observations are separate evidence layers. -Neither proves arbitrary runtime code isolation. Support claims identify the -versions, operating system, subset, and native/browser/deployed observations used. - -## Error Semantics - -| Condition | Error / Outcome | Retry | Recovery Expectation | -|-----------|------------------|-------|----------------------| -| Forbidden import/transitive edge | Nonzero; source, line, target and violated contract | After fix | Move behavior to its owner or inject a public service. | -| Private export, cycle, unclassified source | Nonzero; exact module/path and rule | After fix | Repair boundary; no blanket baseline exception. | -| Dynamic target lacks evidence | Nonzero readiness result for affected loader path | After qualification | Record owned target policy and installed-artifact observations. | -| Shape limit or suppression | Nonzero; measured unit and allowed ceiling | After split | Split by responsibility; never raise ceiling. | -| Test count grows or baseline increases | Nonzero; before/after counts and scoped sources | After consolidation | Preserve behavior coverage; owner resolves genuine policy conflicts. | -| Missing baseline/rules/base | Nonzero; missing input named | After setup | Supply local approved baseline; do not skip or fabricate. | - -## Application control dependency boundary - -CONTRACT-003/005 govern local Python/TypeScript controls. Closure checks MUST -cover their source imports and generated bundles, including dynamic/remote loads -and vendored libraries. Local code may import language standard facilities and -explicitly supplied public platform APIs; mere transitive installation does not -expose a supported application API. Unapproved additions MUST fail admission -without fetching or executing code. Approved exceptional platform extensions -retain isolated dependency ownership and the same global quality ceilings. - - -## Examples - -```text -Allowed: batten.arras -> batten.contracts -Allowed: batten.arras -> public Arras API in the selected cohort -Forbidden: batten.runtime -> batten.arras -Forbidden: batten.dev -> private consuming-host factory -Forbidden: batten.lakebase -> batten.postgres private connection helper -Allowed: composition injects Lakebase authority into public PostgresServices -``` - -## Non-Normative Notes - -An AST-based project checker is the proposed import-linter equivalent. Its -scaffold must prove real positive and negative controls before it can be called -enforced. The reference audit script is an analysis aid outside the product, -not Batten's future checker or a reusable implementation imported from the reference. diff --git a/docs/helix/02-design/contracts/CONTRACT-011-micro-app-conformance.md b/docs/helix/02-design/contracts/CONTRACT-011-micro-app-conformance.md deleted file mode 100644 index f643e29..0000000 --- a/docs/helix/02-design/contracts/CONTRACT-011-micro-app-conformance.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -ddx: - id: CONTRACT-011 - type: contract - activity: design - authoring: - home: repo - links: - - id: batten.prd - kind: informed_by - - id: ADR-014 - kind: informed_by - - id: ADR-015 - kind: informed_by ---- - -# CONTRACT-011: Reference-app conformance and workflow binding - -**Contract ID**: CONTRACT-011 -**Type**: authoring and qualification boundary -**Version**: 0.1.0 - -## Purpose - -Keep reference apps independently governed while sharing platform conformance. -Make specification integrity, component evidence and complete application -execution distinguishable and prevent missing runtime support from passing. - -## Scope and Boundaries - -Batten owns the corpus, workflow specialization and shared test allocation. -Each app owns its requirements and business expectations. UMF owns models, -actions, typed access and saga semantics; Truss owns graph execution; ux-builder -owns its design tooling. App UI delivery follows ADR-015. No runtime DSL, -frontend framework, second ORM or generator is introduced by this contract. - -## Normative Surface - -`docs/helix/reference-apps/catalog.json` is the corpus inventory. Its JSON objects -have only the following fields; unknown fields MUST fail the inventory checker. - -| Element | Type / Shape | Required | Rules | -| --- | --- | --- | --- | -| catalog.version | integer | yes | Exactly 1; inventory format, not SDK series | -| catalog.workflow | relative file path | yes | Shared Batten implementation-plan workflow | -| catalog.apps | nonempty array | yes | Stable unique app IDs and roots; removal requires owner review | -| app.id | string | yes | `MA-` followed by three digits; identity survives renaming | -| app.slug | string | yes | Unique lowercase kebab-case directory name | -| app.ui | string | yes | `typescript` or `headless`; not a renderer qualification claim | -| app.modules | nonempty array of unique strings | yes | Integration requirement tags, not import names, install instructions or grants | -| app.root | relative directory path | yes | Exactly the app directory under `docs/helix/reference-apps/` | -| app.story | string | yes | Stable local story ID; corpus lookup is qualified by app ID | -| app.obligations | array of unique strings | yes | Contains every shared obligation below | - -Each app directory MUST have its own `.helix.yml`, `AGENTS.md`, `fixtures.json` -and `specs/` tree. The marker MUST bind exactly `id: helix`, `root: specs/`. -Generated markers use JSON, a YAML subset, so the stdlib inventory checker needs -no YAML dependency. The `x-batten-app` marker metadata MUST identify the matching app and workflow; -it is a repository convention interpreted through the app instructions, not a -new HELIX resolver API. The installed HELIX catalog supplies templates/prompts. -The app PRD, feature, story and test plan MUST exist with explicit acceptance criteria. - -Fixtures MUST be fabricated JSON data, not executable models or role grants. -Their `application` matches the app ID, `record` supplies a fabricated local ID, -owner and starting state, and `actors` distinguishes permitted and foreign users. -Fixtures add no real customer/user identities or service credentials. - -| Shared obligation | Required observable proof | -| --- | --- | -| AUTH | Server binds current actor; foreign/anonymous/revoked access discloses no private result | -| IDENTITY | App/model/resource/profile revisions and effective identity remain attributable | -| COMMANDS | Query has no business mutation; stale, duplicate and uncertain commands preserve declared outcomes | -| LIFECYCLE | Cancellation, restart and dependency failure retain actual effects and resource ownership | -| LIMITS | Bounded pages, payloads, work and model budgets; no implicit privilege escalation | -| PARITY | Same business operation across supported surfaces and candidate cohorts; unsupported surfaces refuse | -| OBSERVABILITY | Durable safe audit and required telemetry; capture failure is visible | - -App-specific story criteria supplement these obligations. Shared policy scenarios -may be parameterized; domain expectations MUST come from independent app intent, -not from capturing whatever the runtime returns. Browser apps require actual -TypeScript client journeys, including pending/invalid/denied/success/uncertain -states, keyboard/focus/navigation and authorized downloads where applicable. - -### Commands and qualification levels - -`python scripts/check_micro_apps.py` MUST verify inventory, roots, artifacts, -fixture identity and obligation completeness without importing apps or providers. -It prints `inventory only`; success establishes no application execution. -`--require-execution` MUST additionally fail whenever complete app qualification -is unavailable. It MUST NOT invent receipts, treat refusal of a required positive -case as a pass, or silently skip missing app/provider/UI implementations. - -Complete qualification requires exact source/model/action/refinement/UI/cohort and -host-profile inputs, native table/graph policies, independent expected outcomes, -real CLI/client/host/provider results, replay seeds/traces and exploration bounds, -original uncertain invocation identity, required telemetry and negative controls. -Evidence must be verified by a trusted runner; application-authored success flags -or static fixtures cannot confer execution support. There is no accepted evidence -ingestion API selected by this version; strict mode refuses until that contract -and runner are qualified. Local storage evidence remains component-only evidence. - -## Precedence and Compatibility - -Native UMF and provider semantics remain authoritative. Platform contracts govern -bindings; app specs govern business outcomes. A conflict refuses qualification -rather than changing an app's oracle. Inventory format evolution requires a -contract change. A fixture change invalidates dependent execution evidence. -SDK/cohort compatibility remains governed by ADR-005, independently of format 1. - -## Error Semantics - -| Condition | Error / Outcome | Retry | Recovery Expectation | -| --- | --- | --- | --- | -| Invalid inventory, escaped path or mismatched marker | Inventory failure, nonzero exit | After correction | No code or service effects | -| Missing required app execution | Qualification unavailable, nonzero exit | After runner/integration qualification | Never a skip or green support claim | -| Foreign/anonymous/revoked request | Safe denial | After legitimate policy change | No existence or hidden count disclosure | -| Unknown write outcome | Retain original uncertainty | Observe original attempt | No fresh blind command retry | - -## Examples - -Open `docs/helix/reference-apps/approval-desk/`, read its marker and `AGENTS.md`, -then ask HELIX to evolve the app's approval requirement. Its `specs/` artifacts -use installed catalog templates; the SDK's PRD is not edited as that app's PRD. -Run the inventory command from the Batten repository root. Requesting execution -qualification with no trusted complete-app runner produces a nonzero result. - -## Schema Basis - -The inspected UMF source receipt is `schemas/upstream-schema-basis.json`, UMF -core 0.10.0/actions 0.1.0 at its recorded source digest. Its native document, -action and artifact identities remain app-model authorities. Corpus inventory, -local paths and fabricated input data are test bookkeeping; they are deliberately -not UMF model declarations or a portable business-rule language. Native models -and UI artifacts require fresh exact upstream inspection in each app build. diff --git a/docs/helix/02-design/solution-designs/SD-002-lintel-graphql-relay.md b/docs/helix/02-design/solution-designs/SD-002-lintel-graphql-relay.md deleted file mode 100644 index 5fd8206..0000000 --- a/docs/helix/02-design/solution-designs/SD-002-lintel-graphql-relay.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -ddx: - id: SD-002 - type: solution-design - activity: design - authoring: - home: repo - links: - - id: FEAT-002 - kind: informed_by - - id: batten.architecture - kind: informed_by - - id: CONTRACT-001 - kind: informed_by - - id: ADR-015 - kind: informed_by ---- - -# SD-002-lintel-graphql-relay: Embed Lintel GraphQL and Relay access - -**Feature**: [FEAT-002](../../01-frame/features/FEAT-002-operations-and-interfaces.md). -Owner direction on 2026-11-02 selects a separate Python/FastAPI Lintel runtime, -GraphQL + Relay rather than dual OpenAPI/GraphQL, and TypeScript client builds. -Lintel's packet lives in [DocumentDrivenDX/lintel](https://github.com/DocumentDrivenDX/lintel/blob/main/docs/helix/README.md). -The project name is provisional. This is integration design, not product code. - -## Scope - -Include Lintel in Batten's qualified platform runtime. Mount its GraphQL API -through public ASGI/host boundaries; build TypeScript Relay operations/fragments -from the same schema. UMF owns model meaning, Weft compilation, existing providers -native execution and Batten authority/resource custody. No private application -source is required. This refines FR-8/9 and ADR-015's public browser-client path. - -## Requirements Mapping - -| Requirement | Technical Capability | Component | Priority | -| --- | --- | --- | --- | -| FR-8/9 | Same declared command/query and gates through GraphQL | Lintel plus public Batten host | P0 | -| FR-32/33 | Async lifecycle and independent packaged dependency | Optional Batten integration | P0 | -| FR-42 | Qualified client/schema/runtime cohort | Platform build and acceptance | P0 | -| ADR-015 | Authored TypeScript app over public access | Relay artifacts/network adapter | P0 | - -## Solution Approaches - -Select a public Lintel adapter mounted at Batten composition. Pure Batten core -stays neutral; a module-owned adapter translates host capabilities and outcomes. -Putting GraphQL in core would couple every host to the framework. A standalone -Lintel service that bypasses Batten would lose admission/confirmation/attribution. -A Python API boundary avoids a separate TypeScript-to-Python gateway/sidecar. - -## Domain Model - -Reuse approved UMF model/operation identities, Batten actor/application context -and the provider's exact outcomes. Lintel projects GraphQL Node/connection/scalar -shapes and explicit exposure selection. Those are transport/client concepts, not -a competing UMF metamodel, authorization model or SQL language. - -## System Decomposition - -- Lintel owns projection, GraphQL/Relay adaptation and schema/client export. -- Batten host composition constructs the optional adapter and injects the Lintel - router into the ASGI host. Generic core/ASGI modules do not discover or import it. -- Batten owns the proposed optional `batten.lintel` binding in this repository. - It implements Lintel's neutral public execution ports through public Batten - host invocation. Lintel imports no Batten package; generic Batten core imports - neither Lintel nor GraphQL. This is one-way consumer integration, not mutual - package coupling. Its exact API requires a contract and real import checks. -- Batten table/graph providers retain runtime execution; resolvers must not call - raw providers around admission, permissions, confirmation or audit. -- Platform builds carry Python GraphQL dependencies and Relay client/build assets. - Applications perform no pip/npm installation and no runtime dependency discovery. - -## Technology Rationale - -Python/FastAPI follows owner direction and the Databricks Apps embedding goal. -Strawberry is a reversible candidate for GraphQL/Relay schema construction; -Relay's compiler emits TypeScript operation/fragment artifacts. Pin and exercise -the actual interpreter/framework/compiler cohort before adopting it. - -## Traceability - -Lintel FR-1–12 and US-001–006 govern its component. Batten's existing public host -and feature gates remain authoritative when embedded. Acceptance must run one -installed Batten app from compiled Relay TypeScript in Chromium through GraphQL -to PostgreSQL 18, including refetch, arbitrary-edge continuation, batched expansion, -denial, exact values, uncertain write recovery and borrowed-resource shutdown. - -## Concern Alignment - -Public async I/O, neutral core, typed file settings, no new environment variables, -source/quality boundaries, minimal behavioral tests and host-enforced diagnostics -remain intact. A new framework is supplied by the optional platform dependency, -not installed by an application. No browser UI framework is selected here. - -## Constraints & Assumptions - -The local TablePort carries operation/inputs/phase/key/mutation but no explicit -connection/batch/selection metadata. The UMF adapter currently constructs a person -SessionIdentity; this does not establish service/batch authority. Required public -extensions must preserve true actor kinds and per-request native custody. - -The published UMF 0.5.2 cohort references Weft 0.4.48; Batten's local candidate -pins 0.4.51. These versions must not be mixed into an invented qualified cohort. -No package/version/API name is frozen merely by appearing in this design. - -## Risks - -| Risk | Prob | Impact | Mitigation | -| --- | --- | --- | --- | -| Current paging does not supply Relay edge positions | Present gap | High | Upstream runtime capability; no offset fallback | -| Host invocation loses confirmation or identity | Unmeasured | High | Real public-boundary negative cases | -| Shared Relay cache mixes apps/actors | Unmeasured | High | Stable namespaces and scoped/cleared stores | -| Databricks app identity mistaken for caller identity | Unmeasured | High | Explicit host mapping and separately qualified deployment | - -## Diagnostic Flow - -Batten owns authoritative invocation/audit context. Lintel adds GraphQL operation, -projection/cohort and safe outcome context without logging variables or tokens. -Real OpenTelemetry receiver/correlation/privacy evidence is required at execution. -Exact telemetry surfaces and GraphQL/host mappings need contracts before source work. - -## Schema Basis - -Reuse current UMF 0.10 Records/Fields/Keys/Relationships and understood declared -commands/actions, plus the existing public Batten host/provider contracts. Lintel -must consume a supported neutral Python description rather than parse private -code or copy executable schema rules. Its pinned source inventory identifies the -inspected inputs. No new normative schema is introduced by this integration note. - -## Gaps - -Complete the Lintel projection/dynamic-schema, Relay native-read, host/outcome and -TypeScript build spikes before exact public contracts and source handoff. The -current Batten review gate remains for implementation/migration; this owner-directed -planning amendment does not assert source, installed, native or deployed acceptance. diff --git a/docs/helix/03-test/.gitkeep b/docs/helix/03-test/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/docs/helix/03-test/test-plan.md b/docs/helix/03-test/test-plan.md deleted file mode 100644 index 9ad5104..0000000 --- a/docs/helix/03-test/test-plan.md +++ /dev/null @@ -1,389 +0,0 @@ ---- -ddx: - id: TP-001 - type: test-plan - activity: test - authoring: - home: repo - links: - - id: FEAT-009 - kind: derived_from - - id: FEAT-002 - kind: informed_by - - id: CONTRACT-002 - kind: informed_by ---- - -# Batten test strategy: composition and first-host slice - -## Enterprise reference-app corpus - -FR-48 and FEAT-007 add the independently scoped corpus in -`../reference-apps/catalog.json`, governed by CONTRACT-011 and ADR-014/015. -Each app owns its PRD, feature, story, fabricated fixtures and project test plan. -The app build handoff adds exact native models, technical design and per-criterion -story test plans before executable app work. The SDK does not duplicate their -business acceptance matrices here. - -| Criterion class | Primary evidence | Required distinction | -| --- | --- | --- | -| US-007 scope/inventory integrity | Shared inventory gate and catalog artifact validation | Metadata integrity only, no app execution | -| US-007 corrupt roots/identity/obligations | Existing quality-gate negative controls | Actual checker rejects bad input | -| US-007 unavailable execution qualification | Existing quality-gate strict-mode observation | Nonzero refusal; no passing skip | -| App domain outcomes and current authority | Public client/host/native provider journey | Independent expectations, real PostgreSQL 18/Truss where selected | -| Native model/action behavior | Existing UMF/provider conformance plus Batten binding proof | No new ORM, graph engine or action language | -| Authored TypeScript UI | Actual browser journey | Explicit accessibility/state/outcome tests; not automatic declarative UI coverage | -| Agent/model behavior | Scripted repeatable API and separate exact model API evidence | Fixtures cannot establish live model integration or accuracy | -| Candidate host/cohort | Replay original app intent and native recovery constraints | No global portability or cross-service transaction inference | - -`scripts/check_micro_apps.py` runs in the common quality recipe, hook path and CI. -The existing `test_import_cycle_private_and_inventory_controls` behavior exercises -duplicate identity, escaped root and missing obligation cases plus strict-mode -refusal, without increasing the measured function ceiling. Root and app-local -artifact validation use the installed HELIX catalog. Other lifecycle, authority, -observation and platform tests remain required; a catalog pass cannot replace them. - -The integration queue is `../04-build/integration-gaps.md`. Complete-app execution -remains unqualified until its trusted runner and public integration closure exist. -Missing required positive paths fail qualification; they are not accepted skips. - -## Strategy - -Prove the first P0 composition/hosting/UI boundary through public behavior before -claiming installed, native, browser or deployed support. FEAT-009 and the initial -FEAT-002 ux-builder story define this packet's scope. The rest of PRD FR-1–33 -remains required product scope and needs its own story/test allocation before -its implementation. Fleet allocation below adds FR-42–44 and the strengthened -FR-23/27/29. US-005 and the service discovery allocation below cover the expanded -FR-44; this plan does not assert complete product coverage. - -## Framework Selection & Cost - -| Layer | Framework | Justification | CI Time Impact | Maintenance Burden | -| --- | --- | --- | --- | --- | -| Schema/contract | Existing JSON Schema validator in author tooling, then pinned UMF validators | One authoritative payload source and upstream semantics | Unmeasured; measure first gate | Retain semantic checks distinct from shape. | -| Portable behavior | pytest, ADR-001 | Installed Python public API with whole-outcome tables | Unmeasured; no invented timing | Fewest behavior tests; review consolidation. | -| Native/installed | uv wheel installs and PostgreSQL18 integration, ADR-001 | Prove real closure/lifecycle/effects beyond doubles | Unmeasured | Isolated resources, explicit ownership. | -| Browser E2E | Playwright/Chromium, ADR-001 | Same real client/server journey under both hosts | Unmeasured | Stable observable waits; no blind retries. | -| UX quality | Pinned ux-builder lint/audit | Upstream presentation/interaction checks | Unmeasured | Keep cohort and reports independent of authorization proof. | - -No dependencies are installed by this packet. Runtime/timing/count baselines -must be measured from the first reviewed behavioral suite; its ceiling thereafter -only decreases under ADR-007. Scenario names do not allocate new test functions. - -## Critical Paths (P0) - -1. Effect-free resolution and headless installed closure (US-001). -2. Same application across profiles, drift refusal and owned/borrowed cleanup (US-002). -3. A ux-builder review screen, server authorization and uncertain-write recovery (US-003). -4. Upstream saga support refusal or exact qualified binding without a fallback (US-004). -5. Actual import/shape/test gates before all dependent source features (CONTRACT-002). -6. Shared semantic identity, filtered discovery and exact revocable service bindings (US-005). - -## Acceptance Criteria Layer Allocation - -| Criterion class / source | Planned primary layer | Why | -| --- | --- | --- | -| US-001 resolution/unknowns/inert handlers | Portable contract | No effects are allowed during assessment. | -| US-001 headless closure | Installed artifact | Source imports cannot prove wheel independence. | -| US-002 profile comparison/drift/identity/unsupported placement | Portable contract | Deterministic refusal precedes effects. | -| US-002 lifecycle cleanup/uncertainty | Lifecycle integration | Observe actual public start/close behavior with controlled services. | -| US-003 review states, confirmation, revocation and original-outcome recovery | Whole-stack browser | Observe UI and server/effect outcome together across local/embedded profiles. | -| US-003 binding integrity | Contract | Tampered/undeclared targets refuse before rendering. | -| US-003 upstream starter/cohort | Upstream integration | Public tool outputs and exact package closure require direct observation. | -| US-004 absent support and passthrough | Contract, then upstream native conformance for support claims | Doubles prove only Batten translation; upstream qualifies saga execution. | - -Story Test Scenarios name the planned observable assertions. Per-story test plans -and technical designs must bind those scenarios to actual files/commands before -source implementation. No planned test is represented as passing evidence. - -### Local development evidence - -US-002 adds the required stub-auth/shared-pgserver/Tether profile. Its actor-gate -and no-fallback outcomes use public-boundary tests; shared-server identity, -separate ownership, borrower lifetime and reload preservation require native -PostgreSQL 18 observations through Truss and the public UMF table binding. -Tether adapter behavior uses a deterministic scripted model-API fixture; a -separately configured real endpoint supplies live integration evidence. Neither -replaces the other. Test configuration contains no real credential or firm data. - -## Semantic controls and extension allocation - -US-003-AC8–14 expand the same fabricated review journey under FR-40/41. -Allocation is planned evidence, not additional test functions or passing results. - -| Behavior | Primary layer | Observable evidence | -| --- | --- | --- | -| Composed wizard/form/collection state and commit policy (AC8/9) | Real renderer/client/server journey | Back/forward, invalid fields, stable row IDs, explicit cell/row/batch commit; conflicts and partial outcomes preserve native meaning. | -| Detailed local code without added packages (AC9) | Installed/built artifact | Python and TypeScript cases exercise supplied APIs; closure evidence includes generated bundles. | -| Web/terminal semantic equivalence (AC10) | Surface conformance against same server | Same declared edits, validation, cancellation/confirmation, denial and original uncertain invocation; independently exercise keyboard/focus/navigation. | -| Missing renderer/control (AC11) | Contract assessment | Required browser-only editor refuses terminal before imports/effects; explicit qualified alternative is a separate case. | -| Unapproved package closure (AC12) | Artifact build/admission | Table covers direct/transitive imports, bundled/vendor/remote/dynamic loads and installer attempts; no package fetch/import/install occurs during assessment. | -| Approved exceptional extension (AC13) | Installed extension integration | Exact reviewed closure admitted; changed closure refuses; platform code still denied undeclared access. | -| Instance cleanup and scope (AC14) | Renderer lifecycle integration | Teardown disposes observers and prevents actor/resource/revision state leakage. | - -Extend the existing review-state/recovery scenarios for custom controls rather -than duplicate their authorization assertions. Terminal tooling and exact commands -require a separately qualified runtime; browser evidence cannot substitute for it. -The metadata schema validates reference shape only. Upstream semantic definitions, -slot bindings, renderer coverage, cycles and closure provenance need semantic tests. - - -## Test Data Strategy - -Use a fabricated review queue with Review records, approve action, deterministic -recommendation double and a separate optional saga reference. Keep the same -application bytes across local/embedded profiles. Native PostgreSQL18 fixtures, -identities and UI records are fabricated; no production snapshots or credentials. - -## Fleet and runtime evolution allocation - -PRD FR-23/27/29/42–44 add fleet assurance to the first-host plan. These rows are -planned qualification, not passing evidence or new test-function allocations. -Extend existing public-boundary scenarios for invariants they already own. - -| Acceptance ID / source | Primary evidence layer | Required observable outcome | -| --- | --- | --- | -| FLT-01 / FR-23 | Installed runtime/application delivery | Build/admit/start fabricated applications using only the supplied runtime with registry access unavailable; attempted pip/npm fetch/install refuses. | -| FLT-02 / FR-29/42 | Admission and cohort qualification integration | Missing, failing, stale or mismatched app assertions/behavior coverage refuses; current exact evidence qualifies. Changing the app/cohort/policy invalidates it. | -| FLT-03 / FR-27/42 | Host diagnostics integration | Application opt-out cannot disable required capture; calls/refusals carry safe app/artifact/cohort attribution. Sink loss is visible and cannot produce passing evidence. | -| FLT-04 / FR-42 | Candidate/accepted cohort comparison | Breaking dependency/interface changes identify affected apps and integration dependents; required behavior executes before eligibility and incompatible candidates are withheld. | -| FLT-05 / FR-43, CMP-16 | Native shared-host load qualification | A fabricated fleet targeting hundreds of apps runs the declared mix; excess use, failures, cancellation and revocation preserve scope, configured fairness and allocations. Measure capacity and failure domains. | -| FLT-06 / FR-44, CMP-17 | Public graph-provider authorization integration | Authorized declared interaction works; foreign target, missing authority, revoked grant and undeclared private access refuse. Graph links confer no grants. | -| FLT-07 / FR-42 | Runtime recovery and durable-state integration | Retained qualified cohort remains usable when state-compatible; incompatible schema/state refuses rollback and uncertain external effects stay visible. | - -Platform-only tests or schema validation cannot qualify an application fleet. -Owners must specify workload, concurrency, per-app/owner budgets, telemetry loss -policy, evidence policy and pass thresholds before tests can claim capacity or -upgrade safety. Pin runtime/application digests, provider versions, platform and -policy in each result. Use fabricated data; no live fleet operations are authorized. -The function-count ratchet remains in force; consolidation must preserve every -required outcome. No capacity, percentage-coverage or latency measurement exists -in this packet. Exact evidence/telemetry/graph and rollout contracts are required -before dependent source work. - -## Known Gaps - -No source tests, first measured ceiling or native cohort exist in this packet. -UMF saga executor, ux-builder public integration surface, frame transport and -remote-worker custody require separate evidence. These gaps block their support -claims, not effect-free composition design or independent headless applications. - -## Build Commands - -Planned commands, not executable/passing claims: - -```text -uv run python scripts/check_boundaries.py --base HEAD -uv run pytest tests/composition tests/hosting -uv run pytest -m integration tests/installed -bunx playwright test tests/browser/review.spec.ts -``` - -The first scaffold must implement the actual gate and positive/negative import, -cycle, private-access, shape and test-count controls, then wire the same command -locally, in hooks and CI. Missing checkers/tests fail readiness rather than skip. -UI lint/audit commands must come from the verified pinned ux-builder outputs. - -## Platform asset acceptance allocation - -FR-46, FEAT-009 CMP-18–22 and CONTRACT-010 extend US-002 without changing the -source review gate. Reuse existing graph, source identity, authorization and -lifecycle matrices for the same observable behaviors. Rows allocate evidence, -not new test functions or a larger ceiling. Use fabricated data only. - -| Acceptance ID | Required outcome | Primary evidence layer | -| --- | --- | --- | -| PLT-01 / US-002-AC13 | Managed, external and mixed manifests retain exact sources/contracts; duplicate owners, cycles, missing bytes, altered pins and relevant unknown semantics refuse without native effects. | Existing portable composition matrix | -| PLT-02 / US-002-AC13 | Installed core and generic wrapper import without SDK/CLI; core contains no native types; undeclared local/remote dependencies refuse without fetching. | Installed boundary/admission gate | -| PLT-03 / US-002-AC14 | Planning executes no native build hooks; altered source, bindings, dependency receipts, state or approval prevents apply. | Deployment provider conformance | -| PLT-04 / US-002-AC14 | Concurrent deployment/request-ID reuse preserve one owned operation; timeout, cancellation and lost acknowledgement retain partial/unknown effects and reconcile before mutation. | Durable deployment integration, restart and competing deployers | -| PLT-05 / US-002-AC15 | Managed/external bindings require exact trusted receipts, schema/contract compatibility, current permissions and readiness; definition-only deployment refuses until authorized initialization succeeds. | Native provider admission integration | -| PLT-06 / US-002-AC16 | Ordinary lifecycle preserves assets/borrowers; destruction and transfer require explicit approval and dependency checks. | Existing lifecycle plus deployment retention matrix | -| PLT-07 / US-002-AC15 | Producer changes identify affected consumers; consumers cannot deploy/adopt/grant external resources or discover hidden assets through failures. | Existing authorization/fleet matrices | -| PLT-08 / US-002-AC14 | Adapter maps native outputs/external assets to opaque bindings while retaining actor, effective deployer, operation and attribution gaps. | Native integration; existing audit allocation | - -Databricks qualification MUST pin CLI/SDK/API, bundle format, feature profile, -workspace/target and principals. Observe resource creation, pipeline initialization -and output readiness, separately reviewed ordinary-table creation/migration, -permissions, drift, partial apply and reconciliation. Test App resource attachments -separately from creation. Doubles, lookups and deployed definitions cannot prove -native behavior. Live runs require separate namespace/operation authorization and -finite budgets. No implementation or native deployment suite is run by this evolution. - -## Exit Criteria - -Each required behavior has exercising, cited evidence, with canonical `@covers` -IDs in eventual tests. Installed/native/browser observations retain separate -cohort/scope. Shape/import/test ratchets run; unknown semantics remain explicit. -This strategy allocates verification and makes no implementation completion claim. - -## Object storage acceptance allocation - -CONTRACT-006 derives FR-26's first local/Volumes pair. Use one conformance matrix -per observable behavior across providers; extend existing lifecycle/authorization -scenarios where they already own the same invariant. The first reviewed suite -still establishes the measured function ceiling; these rows allocate no counts. - -| Acceptance ID | Required outcome | Primary evidence layer | -| --- | --- | --- | -| STO-01 | The same resource/key reads, writes, stats, lists and deletes fabricated bytes across both providers; no native paths escape. | Native local/Volumes conformance | -| STO-02 | Missing actor, scope escalation and revocation refuse without existence disclosure, including active streams and continuation. | Public host authorization integration | -| STO-03 | Traversal, encoding, symlink/ancestor races, special files and key aliases cannot escape or overwrite another logical object. | Native local filesystem conformance; Volumes path translation matrix | -| STO-04 | Conditional create/replace/delete preserve the winner or refuse; content/revision tokens and managed/native concurrency stay distinct. | Native competing-writer conformance, including a non-Batten writer | -| STO-05 | Large/empty objects, early close, chunk/source failure, timeout and cancellation obey bounds, close streams and retain possible effects. | Native transfer lifecycle integration | -| STO-06 | Shallow/recursive listing, projection and prefix pushdown avoid per-object HEAD and repeat scans; budgets, empty progress pages, authority and cursor scope/expiry hold. | Public provider conformance | -| STO-07 | Startup/reload preserves bytes; closing a borrower leaves shared clients usable; private staging never lists as content. | Native lifecycle integration | -| STO-08 | Metadata row failure after byte completion retains a partial workflow outcome; no cross-resource transaction or automatic retry is claimed. | Existing declared-action outcome integration | -| STO-09 | Storage-free installed core has no storage/vendor import; local storage imports without Databricks installed. | Installed artifact boundary gate | - -Provider qualification pins SDK/API, workspace feature profile, native authority, -OS/filesystem and actual configured bounds. Documentation or doubles cannot prove -create-only, filesystem race containment, Unity Catalog enforcement or native -cancellation. Use fabricated records and a dedicated approved test namespace; -live grants, infrastructure changes and production data are outside this work. -Schema validation proves shapes only. No native conformance has been run here. - -## Messaging acceptance allocation - -CONTRACT-007 and ADR-011 derive FR-45 and extend FR-19/20/22. Extend the existing -host authorization/lifecycle matrices where they own the same invariant. These -acceptance IDs allocate observable outcomes, not new test-function counts or an -implementation sequence. PostgreSQL is the first native provider under test. - -| Acceptance ID | Required outcome | Primary evidence layer | -| --- | --- | --- | -| MSG-01 | Effect-free assessment checks topology, limits, exact codec/profile closure and required features; missing support refuses before provider I/O. | Portable admission contract | -| MSG-02 | Queue consumers compete; each topic subscription receives its own logical delivery; acknowledgement affects only its subscription. | Native PostgreSQL public-provider conformance | -| MSG-03 | Publish/delivery/dedup commit together; concurrent same-ID retries enqueue once, changed content conflicts, response loss reconciles within retained windows. | Native PostgreSQL competing-transaction conformance | -| MSG-04 | Crash after claim, expired lease, stale receipt, response loss and retry/reject/ack conflicts retain correct outcomes; handlers execute outside claim transactions. | Native PostgreSQL fault/recovery conformance | -| MSG-05 | Missing/foreign/revoked authority refuses without payload, receipt or existence disclosure; background identity cannot impersonate a producer; permission checks cover lookup and settlement. | Existing public host authorization matrix | -| MSG-06 | Delay, visibility extension, bounded polling/batches, capacity, fairness, expiration and attempt exhaustion preserve configured budgets and retained terminal outcomes. | Native PostgreSQL scheduling/capacity conformance with controlled clock/faults | -| MSG-07 | Encode/publish/decode preserve exact writer profile and bytes; invalid/unsupported native payloads refuse; unknown metadata, numeric/presence/union semantics do not silently change. | Exact UMF/native-codec conformance; JSON first, Protobuf/Avro separately | -| MSG-08 | Same-store stage remains invisible before commit, rollback leaves no effects, wrong/closed/foreign context refuses, unknown commit preserves uncertainty. Without a qualified issuer, assessment refuses the feature. | Admission negative matrix; then exact executor/PostgreSQL integration | -| MSG-09 | Restart, missed notifications, reconnect and borrower shutdown preserve durable messages and shared services; interrupted receive does not acknowledge. | Native lifecycle/restart conformance | -| MSG-10 | An external effect followed by worker crash can redeliver; client idempotency prevents duplicate effect without claiming universal exactly-once behavior. | Public consumer/effect fault integration | -| MSG-11 | Core/messaging import without native drivers or codecs; Postgres messaging extra imports only the selected closure; all source observes CONTRACT-002 ceilings. | Installed artifact boundary gate | -| MSG-12 | Schema examples and boundary-negative values match authoritative definitions; semantic checks reject duplicate profile IDs, bad topology, bad base64, incompatible retention and changed profile meaning. | Schema validation plus portable settings contract | - -Future provider qualification reuses applicable rows and records every refusal, -auxiliary durable store and semantic limitation. Kafka must prove safe settlement -across partition commit frontiers/rebalances; SQS must tolerate duplicate active -deliveries and qualify fan-out routing; NATS must qualify durable JetStream -consumers and settlement confirmation. No broker equivalence follows from matching -method names. Lakebase additionally needs direct-session, scale-to-zero/reconnect -and restart evidence on its exact cohort. - -Use fabricated payloads and isolated approved databases. No production migration, -role grant or service deployment is authorized by this allocation. Schema checks -are separate from the unrun native provider and instance-codec qualification. - -| Acceptance ID | Required outcome | Primary evidence layer | -| --- | --- | --- | -| STO-10 | Ranges validate offset/count, EOF, native range responses and the same validator across resumed reads; changed content refuses rather than mixes bytes. | Native range conformance | -| STO-11 | Multipart condition is checked at completion; stale/foreign manifests, duplicate part races, part replacement, complete/abort races and lost acknowledgments preserve original state. | Native upload-session integration | -| STO-12 | Qualified reattachment rechecks authority and exact profile; expiry/revocation/restart and staging cleanup never expose partial uploads or delete a completed destination. | Native durable-resume lifecycle integration | -| STO-13 | Source/delivered/stored checksum evidence stays distinct; mismatch, early close and composite native checksums never yield false whole-object verification. | Transfer integrity conformance | -| STO-14 | Prefetch/cache/retry/parallelism obey shared budgets; cached state cannot satisfy a failed current precondition or survive authority loss. | Public provider performance/correctness matrix | -| STO-15 | A provider advertising atomic publication shows old-or-new whole bytes to competing readers; other profiles do not inherit that guarantee. | Native competing-reader/writer integration | - -Listing benchmarks observe native request counts, scan continuation and bounded -memory for shallow, recursive and filtered pages. They allocate no invented -throughput or timing target. Reuse STO-02/05/06/07 for the same invariants rather -than adding duplicate tests; scenario IDs do not allocate test functions. - -## CQRS, attribution and audit acceptance allocation - -FR-9/13/26/27 and CONTRACT-001/004/006 govern these outcomes. Command Query -Responsibility Segregation (CQRS) separates business commands from queries; -OpenTelemetry (OTel) supplies system instrumentation. Extend existing public -boundary scenarios where they own an invariant; these IDs allocate no test counts. - -| Acceptance ID / source | Required observable outcome | Primary evidence layer | -| --- | --- | --- | -| ATT-01 / FR-9 | Route/tool/UI/event/hook projections preserve command/query intent and gates; concealed query mutations and raw-client bypass refuse before effects. Read audit/cache bookkeeping remains permitted. | Public operation/provider integration | -| ATT-02 / FR-13/27 | Human, delegated, approved-model and autonomous calls retain origin, approver, effective authority and application separately; forged identity/baggage, expired delegation and revoked grants confer no authority. | Existing host authorization integration | -| ATT-03 / FR-27 | Context survives publish/delivery/redelivery, schedules, workers, agent tools and graph calls; logical command/run remains stable, attempts differ and changed retry intent refuses. Unknown effect remains uncertain. | Durable messaging/worker/provider integration | -| ATT-04 / FR-13/27 | Concurrent users, pooled sessions and reused workers retain distinct principals and causal context after failure/cancellation; no identity leaks into the next call. | Native database and worker integration | -| ATT-05 / FR-26/27 | Every selected system boundary emits correlated OTel evidence; native request/principal and available model usage stay distinct from Batten user attribution. Missing native support is explicit; required unavailable capability refuses. | Native provider conformance matrix | -| ATT-06 / FR-27 | Sampling or absent trace context preserves required durable audit. Capture outage/overflow before effects blocks required capture; failure after possible effects retains uncertainty, loss and reconciliation without false success. | Audit persistence/fault integration | -| ATT-07 / FR-27 | Current scope gates audit query/export; applications cannot alter/delete records. Redaction precedes export, metrics remain bounded and baggage cannot leak user credentials, private payloads or cross-user identity. | Existing non-disclosure/access integration | -| ATT-08 / FR-9/27 | Command outcome, delayed projection and actual audit persistence remain distinct; retries and partial multi-service effects cannot claim exactly-once or cross-resource atomicity without evidence. | Existing action/receipt integration | - -ATT-05 extends FLT-03 and storage conformance rather than duplicating their -outcomes. Qualify the actual logger/ingestion/export path through a real OTel -receiver, with no duplicate ingestion, and separately prove audit persistence and -access. Pin SDK/semantic-convention/provider versions and application/cohort policy. -Provider matrix covers database, messaging, AI gateway, storage/search, secrets, -workers, graph and host lifecycle interactions, including traced and untraced cases. -Operators must contract audit retention/integrity, query/export, loss policy, -identity-disclosure bounds and required native attribution before dependent source -work. This is verification allocation; no native/runtime tests were run. - -## Service discovery and binding allocation - -PRD FR-44, CMP-17/CMP-23–29 and US-005 govern CONTRACT-009's five-type native -platform model. These rows allocate evidence; they add no test functions or -passing claims. Extend the existing resolution, FLT-06 authorization, headless, -upgrade and recovery scenarios for their owned invariants. - -| Acceptance ID / criteria | Primary layer | Required observable outcome | -| --- | --- | --- | -| SVC-01 / US-005-AC1/4/5 | Native declaration structure plus composition semantic validation | All five record shapes and references resolve; exact shared identity and digests hold. Same-name types, changed artifacts, conflicting joins, ambiguous providers and unknown required meaning refuse without losing bytes. | -| SVC-02 / US-005-AC2/6 | Extend FLT-06 public Arras/provider integration | Actor-filtered metadata, paging/counts, target lookup and dependency paths disclose no hidden objects. Separate discovery grants from invocation grants; forged app/delegation/header identities and revoked grants yield no effects. | -| SVC-03 / US-005-AC3/4 | Extend US-001 effect-free resolution | Separate host evidence pins the unchanged consumer; its digest enters the plan without a self-reference cycle. Resolution performs no network/import/start; absent/ambiguous/incompatible/cyclic required dependencies refuse; optional absence remains inactive. | -| SVC-04 / US-005-AC5/9 | Registry publication/bootstrap integration and installed closure | Only verified app exports and authorized host commands create eligible bindings. Explicit root registry binding avoids self-resolution. Core-only hosts import no ontology engine and consume equivalent explicit evidence. | -| SVC-05 / US-005-AC7/10 | Extend binding drift, FLT-04/07 upgrade/recovery | Cached bindings and continuation cannot outlive current authority/revisions. Relocation retains semantic interface identity; dependency impact is exact and permission-filtered. No fallback/replay; retirement/revocation preserves uncertainty and active-dependent policy. | -| SVC-06 / US-005-AC8 | Native transport conformance per selected profile | Graph, owner-published table/view, API and messaging independently prove native authority, semantic mapping and their declared consistency/recovery. No raw connection, arbitrary cross-app write, implicit subscription creation or assumed cross-resource transaction. | - -Fixtures use fabricated customer-owner/review-queue applications, a shared native -Customer artifact, a same-name incompatible type, two competing exports, hidden -providers and expired/revoked bindings. Exercise user and explicit background or -delegated authority. Reuse CONTRACT-007 MSG delivery/codec cases and existing -attribution/audit scenarios rather than duplicating their invariants here. - -Native observations MUST pin original ontology/interface/application artifacts, -Arras/UMF and transport cohort, registry revision/visibility profile, trusted -resolution evidence, policy and finite limits. Structural validation proves only -UMF declaration shape. Native record joins, coherent snapshot/continuation, -principal-scoped reads, async adaptation, provider identity and concurrent -revocation require public integration evidence. A local graph double cannot -qualify Unity Catalog, Lakebase, API or messaging behavior. No live registry, -transport, capacity or operational change is authorized by this allocation. - -## Semantic application conformance allocation - -FR-47 is P0. Automatic conformance for every fully declarative UI-and-hook -composition is required; default-construct support gaps cannot be treated as -optional test exclusions. Use generated cases through shared public behavior -runners; these rows allocate outcomes, not additional test functions. - -| Acceptance ID | Primary layer | Observable outcome | -| --- | --- | --- | -| SEM-01 | Semantic generator conformance | Every default construct and allowed refinement produces a complete behavior/CLI/property inventory; a missing definition, hook oracle or CLI mapping prevents qualification. | -| SEM-02 | CLI/host end-to-end | Generated commands exercise every declared behavior, including UI navigation/state, hook effects, validation, denial, confirmation, cancellation and original-call recovery; no private-host bypass. | -| SEM-03 | Real renderer/host/provider end-to-end | Automatically generated legal/illegal state sequences check semantic invariants and actual UI/hook outcomes, including focus/accessibility where relevant; no handwritten per-app cases are required. | -| SEM-04 | Generator/oracle negative controls | Deliberately wrong transitions, ignored refinements and altered declarative hook effects produce reproducible minimized failures; implementation self-comparison cannot pass. | -| SEM-05 | Cross-platform migration conformance | Exact app/refinements and properties run on accepted/candidate bindings; semantic drift, absent UI/hook behavior or missing required coverage blocks migration qualification. | -| SEM-06 | Reproducibility/evidence integration | Replay pinned seeds/traces and shrunk counterexamples against exact artifacts/cohorts; changed semantics invalidate prior evidence and exploration limits remain explicit. | - -Generate from desired semantics after use-case refinement, preserving original -UMF/ux-builder meaning and testing implementation through public execution paths. -The default declarative hook set must supply deterministic contracts/oracles for -observed effects; external nondeterminism requires controlled fixtures or qualified -properties, never guessed exact outputs. Arbitrary procedural hooks need explicit -test contracts and cannot silently inherit declarative completeness. - -Conclusive qualification means all required declared behaviors have adequate -oracles, CLI mappings and real end-to-end coverage, with a decisive pass/fail -verdict for the stated domain and exploration policy. Property-based sampling is -not an exhaustive proof of unbounded behavior; finite modeled state spaces may -also be explored exhaustively. Report coverage and bounds, never turn a missing -case into success. Generation must preserve configured authority/resource limits, -use fabricated inputs and controlled clocks, and retain uncertain effects without -blind replay. No live platform migration or external effect is authorized here. - -Exact semantic model/refinement, generator/oracle, CLI and execution-report -contracts, qualified renderer/platform adapters and the testing framework remain -implementation prerequisites. No generated runtime suite has executed in this -specification packet. Existing first-host and native evidence requirements remain. diff --git a/docs/helix/04-build/.gitkeep b/docs/helix/04-build/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/docs/helix/04-build/batten-app-workflow.md b/docs/helix/04-build/batten-app-workflow.md deleted file mode 100644 index 4c8c7f5..0000000 --- a/docs/helix/04-build/batten-app-workflow.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -ddx: - id: batten.app-workflow - type: implementation-plan - activity: build - authoring: - home: repo - links: - - id: CONTRACT-011 - kind: informed_by - - id: ADR-014 - kind: informed_by - - id: ADR-015 - kind: informed_by ---- - -# Batten application workflow - -## Scope - -Specialize the installed HELIX workflow for a single Batten app, from business -intent to independently qualified behavior. This is a repository-owned workflow, -not a forked methodology catalog or an installed `helix-batten` plugin. -Governing artifacts: CONTRACT-003/004/005/011, ADR-005/014/015, the selected app's -PRD/story/test plan, and the SDK's test plan and selected concerns. - -## Shared Constraints - -Read the nearest `.helix.yml` and scope all governed app artifacts to its `specs/` -root. Read the shared workflow path in the app instructions. Use the installed -HELIX catalog for every artifact template, prompt and metadata file. Local links -resolve inside that app scope; explicit platform file dependencies do not change -app identity. Fabricated data only. User policy and source/deployment authority -remain separate. Do not install dependencies or grant access during startup. - -Use UMF + PostgreSQL 18 for tables and UMF + Truss for graph access. Prefer the -existing platform capabilities over a new ORM, query compiler, saga engine or -agent runtime. Initial UI delivery is a TypeScript app with a public host client; -ux-builder integration must preserve its original design assets and public APIs. - -## Implementation Slices - -| Slice | Story / Area | Governing Artifacts | Depends On | Validation Gate | -| --- | --- | --- | --- | --- | -| APP-01 | Discover/frame the chosen business outcome | App PRD and story | Scoped marker | Personas, rules, denied/uncertain outcomes and explicit owner assumptions | -| APP-02 | Select integration closure | CONTRACT-003/004, upstream source evidence | APP-01 | Exact UMF/provider packages and admitted subset; no private imports or guessed capability | -| APP-03 | Author native models/actions and host contracts | App design/contracts, original UMF | APP-02 | Upstream validation; exact table/graph access, transaction/policy limits and model references | -| APP-04 | Specify TypeScript UI or headless surface | ADR-015, CONTRACT-005, ux-builder sources | APP-03 | User journeys, client boundaries and accessibility allocation; no declarative renderer claim | -| APP-05 | Allocate conformance and independent oracle | App test plan and story test plans | APP-03/04 | Every acceptance criterion mapped; known-broken controls; bounded replay and cohort matrix | -| APP-06 | Implement integration and app slice | App technical design and build plan | APP-05 and owner build authorization | Boundary checks first; installed artifacts; real pgserver/Truss/host and browser paths | -| APP-07 | Qualify and package | CONTRACT-011 and app evidence | APP-06 | Complete positive/negative journeys, exact revisions, native policies and safe diagnostics | -| APP-08 | Evolve or move to another host | ADR-005, app baseline and candidate binding | APP-07 | Same app semantics requalified; migrations/applies separately authorized | - -## Execution Contract - -The owner authorizes the corpus, gap queue and this workflow. It does not authorize -all reference app runtimes, production applies, secret access or migrations. -Later app implementation requires a bounded app build instruction and a qualified -platform integration closure. Specs remain useful when that closure is unavailable; -qualification must refuse rather than invent a local replacement or scripted host. -Token usage, spending and duration budgets are unknown; Erik supplies any ceiling. -Available task tooling supplies no reliable billing meter. Verification is part -of each authorized implementation slice. - -## Continuation Evidence - -Use the app-specific plan, diff and test evidence to resume an app, with its own -artifact identities. Use the SDK integration queue for upstream dependencies. -Never propagate one app's green result to another app or new cohort. Run -`python scripts/check_micro_apps.py` from the SDK root for inventory integrity; -strict qualification remains a separate fail-closed check. - -## Validation Plan - -Validate governed artifacts against the installed catalog. Validate the aggregate -corpus through the common quality command. For runtime work, require independent -business expectations and real public client/host/provider observations. CLI -properties cover native declarative actions; authored TypeScript UI has explicit -browser journeys. Model fixtures do not prove a live model API integration. -Do not raise the current test-function ceiling; parameterize shared scenarios -while preserving each app's distinct invariants and their traceability. - -## Risks and Rollbacks - -| Risk | Impact | Response | Rollback | -| --- | --- | --- | --- | -| Wrong scope selected | Edits another product | Resolve nearest marker and state app identity | Revert only affected app changes | -| Upstream schema/access gap | False portability | Bind exact subset or explicit refusal | Preserve original native artifacts | -| UI ahead of host security | Client-derived authority | Qualify server authorization before app journey completion | Disable affected binding | -| Candidate changes durable semantics | Unsafe migration | Re-run independent app properties and native recovery | Use only a qualified recovery route | - -## Exit Criteria - -A scoped app specification has complete business expectations and test allocation. -A qualified app additionally has an admitted integration closure, installed/native -and actual browser/CLI evidence, complete required coverage and safe telemetry. -No inventory check or component-only receipt substitutes for the latter gates. diff --git a/docs/helix/04-build/dependency-upgrade/implementation-plan.md b/docs/helix/04-build/dependency-upgrade/implementation-plan.md deleted file mode 100644 index db7c819..0000000 --- a/docs/helix/04-build/dependency-upgrade/implementation-plan.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -ddx: - id: batten.dependency-upgrade-20261103 - type: implementation-plan - activity: build - authoring: - home: repo - links: - - id: ADR-005 - kind: informed_by - - id: ADR-007 - kind: informed_by - - id: ADR-016 - kind: informed_by - - id: CONTRACT-002 - kind: informed_by - - id: CONTRACT-012 - kind: informed_by ---- - -# Published dependency upgrade - -## Scope - -The owner requests upgrading every dependency after the runtime-v0.1.0a1 audit. -Preserve the public local approval workflow and qualify the exact replacement -cohort under ADR-005/007/016 and CONTRACT-002/012. The release target is -runtime-v0.1.0a2; the independent storage package remains unchanged. - -## Shared Constraints - -Use original published UMF Core/Codegen 0.10.8, access dev8, umf-weft 0.4.57, -Psycopg 3.3.7 and PostgreSQL 18. Fetch each upstream artifact from its actual -release with original hashes. No native engine is copied or replaced. Python -3.13 is the new local test cohort; library consumer floors remain explicit. -Replace compiler-coupled linting with Oxlint and move browser tests to JavaScript -Playwright as selected by the owner. Do not apply unqualified major or peer overrides. The single type-only -undici-types 8.12.3 minor override requires strict TypeScript declaration checking -and the real browser scenarios; it replaces Node types’ older nested pin. Do not weaken shape rules, hide assertions or increase the 17-function budget. -Use dedicated fabricated data, never implicitly migrate an existing workspace. - -## Implementation Slices - -| Slice | Area | Depends on | Validation gate | -| --- | --- | --- | --- | -| D-001 | Published native dependency pins and per-artifact compiler assembly | None | Normal resolver, pip check, compiler entry points and installed-wheel closure | -| D-002 | TypeScript 7 and Oxlint | D-001 | Exact four shape gates with positive/negative controls; no older lint dependency tree | -| D-003 | JavaScript Playwright scenarios and cross-language census | D-002 | Same two scenarios and invariants; 17 total registered behaviors; strict typing | -| D-004 | Qualification, documentation and release | D-003 | Fast/native/browser/CI gates, wheel hashes, reviewed site, immutable prerelease assets | - -## Execution Contract - -The owner's instruction authorizes implementation and follows the existing -release/publishing request. Reuse the clean release checkout on -codex/dependencies-20261103 and preserve the other chat's app expansion. -Token usage estimate and spending ceiling are unknown; no monetary budget was -supplied and the runtime exposes no reliable task cost meter. Verification and -independent review are included. Do not claim an unsupported package combination -as qualified or change unrelated app behavior to make an upgrade pass. - -## Continuation Evidence - -D-001 resolves and installs the published compiler/Core pair, current access, -Weft and Psycopg through normal dependency metadata; both installed environments -pass pip check. D-002 passes the four real shape controls with Oxlint 1.91.0 and -TypeScript 7.0.2. D-003 ports both canonical scenarios and preserves the combined -17-function census, including alias, namespace, hidden-helper and skip controls. -The final upgraded browser run passes both scenarios with zero retries, adds -fresh registry viewport captures and records nine exact controller/cohort hashes. -A readiness overlap found during capture was fixed before the passing run. -All 18 Python cases pass. The final registry audit checks 110 locked entries and -finds zero older published versions. Independent review has passed; D-004 CI and -publication remain open at this local qualification checkpoint. - -## Validation Plan - -Run the common quality recipe, preserve its actual negative controls and validate -registered browser counts. Run the existing approval and registry scenarios from -installed wheels against real PostgreSQL 18 and Chromium. Verify dependency -metadata with the normal resolver and pip check. Record exact artifacts, -interpreter, original source and observed results; independently review the -changed code and reader pages before merging and publishing. - -## Risks and Rollbacks - -| Risk | Response | Rollback | -| --- | --- | --- | -| Native compiler protocol or output drift | Qualify original bundles, migration, RLS and receipts | Retain the old release with its matching workspace | -| Browser migration loses an assertion | Compare the complete old/new scenario mapping and census | Keep the old qualified test/release snapshot | -| Lint replacement weakens a gate | Exercise each exact threshold with real controls | Restore the previous tool cohort | - -## Exit Criteria - -All selected direct and transitive dependencies are current published versions, -the new cohort passes its required gates, all prior distinct invariants remain -covered, and the 17-function ceiling holds. Updated qualification receipts, -source-stamped site content and immutable runtime-v0.1.0a2 assets are published. diff --git a/docs/helix/04-build/dependency-upgrade/verification.json b/docs/helix/04-build/dependency-upgrade/verification.json deleted file mode 100644 index b8c5813..0000000 --- a/docs/helix/04-build/dependency-upgrade/verification.json +++ /dev/null @@ -1,801 +0,0 @@ -{ - "checks": { - "consumer_install": { - "location": "outside source checkout", - "packages": 36, - "result": "passed", - "validation": "normal resolver, pip check and python -I installed CLI help" - }, - "dependency_audit": { - "locked_entries": 110, - "older_published_versions": 0 - }, - "dependency_metadata": { - "development": "pip check passed", - "installed_runtime": "pip check passed" - }, - "fast_quality": { - "command": "uv run --frozen python scripts/quality.py", - "passed": 18, - "warnings": "Two Python 3.13 multiprocessing fork deprecation warnings in storage concurrency checks; all 18 cases pass." - }, - "independent_reader": { - "identity": "microsite_dependency_reader", - "result": "passed; final controller/cohort hashes, evidence and four changed guide pages reviewed" - }, - "native_browser": { - "command": "bun run test:native", - "passed": 2, - "prior_failure": "Final capture first exposed an initial identity-load overlap in the migrated fixture. Waiting for #actor:enabled after identity selection resolves readiness before the scenario refresh. No retry or business assertion change was used.", - "runner_stats": { - "duration": 392065.85699999996, - "expected": 2, - "flaky": 0, - "skipped": 0, - "startTime": "2026-11-04T04:34:35.874Z", - "unexpected": 0 - }, - "source_hashes": { - ".cache/approval-cohort.json": "4d73fff69136bae575f4dd5f6ab3520053029fda7a2c148a5ca96eb268d069ac", - "bun.lock": "56403d4919f1e81ad31c45880f6c0eed818564cbf119b108e14dc64560bc315b", - "package.json": "1330e7c176fabc9d108151a8592e4388db1013ba43dd8bd8efa2621e8a38a1a3", - "playwright.config.ts": "a1a8a7cc7a6ec71842239dc18e9efd5f0b84f2ff7a5204a0615ea8f92fa46f58", - "tests/apps/approval.spec.ts": "af62c7c788ee425ec1f5fd46e184c54612405f7bb29ca366c2594460d63691c7", - "tests/apps/fixtures.ts": "eb2bd93ed38077b1bfbaddc364d7e775d92bd7b6e57befbf7c0d547f8fc17729", - "tests/apps/host.ts": "02cad565752c7ec9c6ade51321755f7f087277bd3c082ea42ae99ac5acfffb34", - "tests/apps/native_probe.py": "686b8c64bd8186d0fb8248f009a0e1f94c8c5f6a5c053b3350515144d6d4a900", - "uv.lock": "bc0af722f98bffbfccfb8add02cddfa6009c6a35ee3acff62630b1dcbdf1b41e" - } - }, - "test_census": { - "ceiling": 17, - "javascript": 2, - "python": 15 - } - }, - "cohort": { - "model_sha256": "8c13d687fa44837aee3137c33b3a3a61966a002bd69ab2ea4f2a59f21857749f", - "packages": { - "annotated-types": "0.8.0", - "anyio": "4.16.0", - "click": "8.5.0", - "fasteners": "0.20", - "h11": "0.16.0", - "idna": "3.20", - "novirhyza-batten-approval-desk": "0.1.0a2", - "novirhyza-batten-asgi": "0.1.0a2", - "novirhyza-batten-contracts": "0.1.0a2", - "novirhyza-batten-local": "0.1.0a2", - "novirhyza-batten-runtime": "0.1.0a2", - "novirhyza-batten-tables": "0.1.0a2", - "novirhyza-batten-umf-postgres": "0.1.0a2", - "opentelemetry-api": "1.45.2", - "opentelemetry-instrumentation": "0.66b2", - "opentelemetry-instrumentation-dbapi": "0.66b2", - "opentelemetry-instrumentation-psycopg": "0.66b2", - "opentelemetry-sdk": "1.45.2", - "opentelemetry-semantic-conventions": "0.66b2", - "packaging": "26.3", - "pgserver-pg18": "18.6.1", - "platformdirs": "4.14.3", - "psutil": "7.2.2", - "psycopg": "3.3.7", - "psycopg-binary": "3.3.7", - "pydantic": "2.14.2", - "pydantic_core": "2.50.2", - "starlette": "1.10.0", - "typing-inspection": "0.4.4", - "typing_extensions": "4.16.0", - "umf-codegen": "0.10.8", - "umf-core": "0.10.8", - "umf-weft": "0.4.57", - "umf_access": "0.1.0.dev8", - "uvicorn": "0.54.0", - "wrapt": "2.5.2" - }, - "python": "3.13.16", - "umf_artifacts": { - "umf_access-0.1.0.dev8-py3-none-any.whl": { - "release": "umf-v0.5.8", - "sha256": "1a21c1ddd59f6b23e9f0b33228280564af0e96bb4d13699b89616d5143e4fd23" - }, - "umf_codegen-0.10.8-py3-none-any.whl": { - "release": "umf-v0.10.8", - "sha256": "0d21acef3171442b818a4ad1dfdbaf99cc0f0f5557e5c670d5ce56243235dbc5" - } - }, - "wheels": { - "novirhyza_batten_approval_desk-0.1.0a2-py3-none-any.whl": "bf5185d5dd51ecf9d843afe027f9e6cc257cdb3aab8febb10260a1a31a9da46b", - "novirhyza_batten_asgi-0.1.0a2-py3-none-any.whl": "895e4760f55bba1858ab2301e1782bfda799d42b7772521f9d78fcef26eb69d4", - "novirhyza_batten_contracts-0.1.0a2-py3-none-any.whl": "cf20c473161a0a7bc3a30b7dcffe8727ce0460b9c574dd71539f18ed51911cc3", - "novirhyza_batten_local-0.1.0a2-py3-none-any.whl": "3f180b774d0342cfcd0961df5695f45965ee2c2bac2f8c6cb5bd4d29e76806cd", - "novirhyza_batten_runtime-0.1.0a2-py3-none-any.whl": "500c7f0f4465b21a6a95924f9fa5379f44e827bcc315fef8d4a3a887716bb27d", - "novirhyza_batten_tables-0.1.0a2-py3-none-any.whl": "45598cd5dda3c1ad7deb8039d66b42c9ddd78b08b90bc7614d3ac35f941d9bee", - "novirhyza_batten_umf_postgres-0.1.0a2-py3-none-any.whl": "5a96922b7c1d6898af4d3eef87a5e6904dad70c77cc7b2816f1fefbb71c629b9", - "umf_access-0.1.0.dev8-py3-none-any.whl": "1a21c1ddd59f6b23e9f0b33228280564af0e96bb4d13699b89616d5143e4fd23", - "umf_codegen-0.10.8-py3-none-any.whl": "0d21acef3171442b818a4ad1dfdbaf99cc0f0f5557e5c670d5ce56243235dbc5" - } - }, - "date": "2026-11-03", - "kind": "dependency-upgrade-evidence", - "limits": [ - "Local PostgreSQL18 approval-desk profile only.", - "The complete reference-app conformance gate remains separate.", - "No production identity, hostile-code, or OTLP receiver qualification." - ], - "platform": "macOS-27.0.1-arm64-arm-64bit-Mach-O", - "registry_audit": [ - { - "current": "0.157.0", - "ecosystem": "npm", - "latest": "0.157.0", - "name": "@oxc-parser/binding-android-arm-eabi" - }, - { - "current": "0.157.0", - "ecosystem": "npm", - "latest": "0.157.0", - "name": "@oxc-parser/binding-android-arm64" - }, - { - "current": "0.157.0", - "ecosystem": "npm", - "latest": "0.157.0", - "name": "@oxc-parser/binding-darwin-arm64" - }, - { - "current": "0.157.0", - "ecosystem": "npm", - "latest": "0.157.0", - "name": "@oxc-parser/binding-darwin-x64" - }, - { - "current": "0.157.0", - "ecosystem": "npm", - "latest": "0.157.0", - "name": "@oxc-parser/binding-freebsd-x64" - }, - { - "current": "0.157.0", - "ecosystem": "npm", - "latest": "0.157.0", - "name": "@oxc-parser/binding-linux-arm-gnueabihf" - }, - { - "current": "0.157.0", - "ecosystem": "npm", - "latest": "0.157.0", - "name": "@oxc-parser/binding-linux-arm-musleabihf" - }, - { - "current": "0.157.0", - "ecosystem": "npm", - "latest": "0.157.0", - "name": "@oxc-parser/binding-linux-arm64-gnu" - }, - { - "current": "0.157.0", - "ecosystem": "npm", - "latest": "0.157.0", - "name": "@oxc-parser/binding-linux-arm64-musl" - }, - { - "current": "0.157.0", - "ecosystem": "npm", - "latest": "0.157.0", - "name": "@oxc-parser/binding-linux-ppc64-gnu" - }, - { - "current": "0.157.0", - "ecosystem": "npm", - "latest": "0.157.0", - "name": "@oxc-parser/binding-linux-riscv64-gnu" - }, - { - "current": "0.157.0", - "ecosystem": "npm", - "latest": "0.157.0", - "name": "@oxc-parser/binding-linux-riscv64-musl" - }, - { - "current": "0.157.0", - "ecosystem": "npm", - "latest": "0.157.0", - "name": "@oxc-parser/binding-linux-s390x-gnu" - }, - { - "current": "0.157.0", - "ecosystem": "npm", - "latest": "0.157.0", - "name": "@oxc-parser/binding-linux-x64-gnu" - }, - { - "current": "0.157.0", - "ecosystem": "npm", - "latest": "0.157.0", - "name": "@oxc-parser/binding-linux-x64-musl" - }, - { - "current": "0.157.0", - "ecosystem": "npm", - "latest": "0.157.0", - "name": "@oxc-parser/binding-openharmony-arm64" - }, - { - "current": "0.157.0", - "ecosystem": "npm", - "latest": "0.157.0", - "name": "@oxc-parser/binding-win32-arm64-msvc" - }, - { - "current": "0.157.0", - "ecosystem": "npm", - "latest": "0.157.0", - "name": "@oxc-parser/binding-win32-ia32-msvc" - }, - { - "current": "0.157.0", - "ecosystem": "npm", - "latest": "0.157.0", - "name": "@oxc-parser/binding-win32-x64-msvc" - }, - { - "current": "0.157.0", - "ecosystem": "npm", - "latest": "0.157.0", - "name": "@oxc-project/types" - }, - { - "current": "1.91.0", - "ecosystem": "npm", - "latest": "1.91.0", - "name": "@oxlint/binding-android-arm-eabi" - }, - { - "current": "1.91.0", - "ecosystem": "npm", - "latest": "1.91.0", - "name": "@oxlint/binding-android-arm64" - }, - { - "current": "1.91.0", - "ecosystem": "npm", - "latest": "1.91.0", - "name": "@oxlint/binding-darwin-arm64" - }, - { - "current": "1.91.0", - "ecosystem": "npm", - "latest": "1.91.0", - "name": "@oxlint/binding-darwin-x64" - }, - { - "current": "1.91.0", - "ecosystem": "npm", - "latest": "1.91.0", - "name": "@oxlint/binding-freebsd-x64" - }, - { - "current": "1.91.0", - "ecosystem": "npm", - "latest": "1.91.0", - "name": "@oxlint/binding-linux-arm-gnueabihf" - }, - { - "current": "1.91.0", - "ecosystem": "npm", - "latest": "1.91.0", - "name": "@oxlint/binding-linux-arm-musleabihf" - }, - { - "current": "1.91.0", - "ecosystem": "npm", - "latest": "1.91.0", - "name": "@oxlint/binding-linux-arm64-gnu" - }, - { - "current": "1.91.0", - "ecosystem": "npm", - "latest": "1.91.0", - "name": "@oxlint/binding-linux-arm64-musl" - }, - { - "current": "1.91.0", - "ecosystem": "npm", - "latest": "1.91.0", - "name": "@oxlint/binding-linux-ppc64-gnu" - }, - { - "current": "1.91.0", - "ecosystem": "npm", - "latest": "1.91.0", - "name": "@oxlint/binding-linux-riscv64-gnu" - }, - { - "current": "1.91.0", - "ecosystem": "npm", - "latest": "1.91.0", - "name": "@oxlint/binding-linux-riscv64-musl" - }, - { - "current": "1.91.0", - "ecosystem": "npm", - "latest": "1.91.0", - "name": "@oxlint/binding-linux-s390x-gnu" - }, - { - "current": "1.91.0", - "ecosystem": "npm", - "latest": "1.91.0", - "name": "@oxlint/binding-linux-x64-gnu" - }, - { - "current": "1.91.0", - "ecosystem": "npm", - "latest": "1.91.0", - "name": "@oxlint/binding-linux-x64-musl" - }, - { - "current": "1.91.0", - "ecosystem": "npm", - "latest": "1.91.0", - "name": "@oxlint/binding-openharmony-arm64" - }, - { - "current": "1.91.0", - "ecosystem": "npm", - "latest": "1.91.0", - "name": "@oxlint/binding-win32-arm64-msvc" - }, - { - "current": "1.91.0", - "ecosystem": "npm", - "latest": "1.91.0", - "name": "@oxlint/binding-win32-ia32-msvc" - }, - { - "current": "1.91.0", - "ecosystem": "npm", - "latest": "1.91.0", - "name": "@oxlint/binding-win32-x64-msvc" - }, - { - "current": "1.64.1", - "ecosystem": "npm", - "latest": "1.64.1", - "name": "@playwright/test" - }, - { - "current": "26.6.6", - "ecosystem": "npm", - "latest": "26.6.6", - "name": "@types/node" - }, - { - "current": "7.0.2", - "ecosystem": "npm", - "latest": "7.0.2", - "name": "@typescript/typescript-aix-ppc64" - }, - { - "current": "7.0.2", - "ecosystem": "npm", - "latest": "7.0.2", - "name": "@typescript/typescript-darwin-arm64" - }, - { - "current": "7.0.2", - "ecosystem": "npm", - "latest": "7.0.2", - "name": "@typescript/typescript-darwin-x64" - }, - { - "current": "7.0.2", - "ecosystem": "npm", - "latest": "7.0.2", - "name": "@typescript/typescript-freebsd-arm64" - }, - { - "current": "7.0.2", - "ecosystem": "npm", - "latest": "7.0.2", - "name": "@typescript/typescript-freebsd-x64" - }, - { - "current": "7.0.2", - "ecosystem": "npm", - "latest": "7.0.2", - "name": "@typescript/typescript-linux-arm" - }, - { - "current": "7.0.2", - "ecosystem": "npm", - "latest": "7.0.2", - "name": "@typescript/typescript-linux-arm64" - }, - { - "current": "7.0.2", - "ecosystem": "npm", - "latest": "7.0.2", - "name": "@typescript/typescript-linux-loong64" - }, - { - "current": "7.0.2", - "ecosystem": "npm", - "latest": "7.0.2", - "name": "@typescript/typescript-linux-mips64el" - }, - { - "current": "7.0.2", - "ecosystem": "npm", - "latest": "7.0.2", - "name": "@typescript/typescript-linux-ppc64" - }, - { - "current": "7.0.2", - "ecosystem": "npm", - "latest": "7.0.2", - "name": "@typescript/typescript-linux-riscv64" - }, - { - "current": "7.0.2", - "ecosystem": "npm", - "latest": "7.0.2", - "name": "@typescript/typescript-linux-s390x" - }, - { - "current": "7.0.2", - "ecosystem": "npm", - "latest": "7.0.2", - "name": "@typescript/typescript-linux-x64" - }, - { - "current": "7.0.2", - "ecosystem": "npm", - "latest": "7.0.2", - "name": "@typescript/typescript-netbsd-arm64" - }, - { - "current": "7.0.2", - "ecosystem": "npm", - "latest": "7.0.2", - "name": "@typescript/typescript-netbsd-x64" - }, - { - "current": "7.0.2", - "ecosystem": "npm", - "latest": "7.0.2", - "name": "@typescript/typescript-openbsd-arm64" - }, - { - "current": "7.0.2", - "ecosystem": "npm", - "latest": "7.0.2", - "name": "@typescript/typescript-openbsd-x64" - }, - { - "current": "7.0.2", - "ecosystem": "npm", - "latest": "7.0.2", - "name": "@typescript/typescript-sunos-x64" - }, - { - "current": "7.0.2", - "ecosystem": "npm", - "latest": "7.0.2", - "name": "@typescript/typescript-win32-arm64" - }, - { - "current": "7.0.2", - "ecosystem": "npm", - "latest": "7.0.2", - "name": "@typescript/typescript-win32-x64" - }, - { - "current": "0.157.0", - "ecosystem": "npm", - "latest": "0.157.0", - "name": "oxc-parser" - }, - { - "current": "1.91.0", - "ecosystem": "npm", - "latest": "1.91.0", - "name": "oxlint" - }, - { - "current": "1.64.1", - "ecosystem": "npm", - "latest": "1.64.1", - "name": "playwright" - }, - { - "current": "1.64.1", - "ecosystem": "npm", - "latest": "1.64.1", - "name": "playwright-core" - }, - { - "current": "7.0.2", - "ecosystem": "npm", - "latest": "7.0.2", - "name": "typescript" - }, - { - "current": "8.12.3", - "ecosystem": "npm", - "latest": "8.12.3", - "name": "undici-types" - }, - { - "current": "0.8.0", - "ecosystem": "python", - "latest": "0.8.0", - "name": "annotated-types" - }, - { - "current": "4.16.0", - "ecosystem": "python", - "latest": "4.16.0", - "name": "anyio" - }, - { - "current": "1.6.1", - "ecosystem": "python", - "latest": "1.6.1", - "name": "build" - }, - { - "current": "8.5.0", - "ecosystem": "python", - "latest": "8.5.0", - "name": "click" - }, - { - "current": "0.4.6", - "ecosystem": "python", - "latest": "0.4.6", - "name": "colorama" - }, - { - "current": "0.20", - "ecosystem": "python", - "latest": "0.20", - "name": "fasteners" - }, - { - "current": "0.16.0", - "ecosystem": "python", - "latest": "0.16.0", - "name": "h11" - }, - { - "current": "1.33.0", - "ecosystem": "python", - "latest": "1.33.0", - "name": "hatchling" - }, - { - "current": "3.20", - "ecosystem": "python", - "latest": "3.20", - "name": "idna" - }, - { - "current": "2.3.1", - "ecosystem": "python", - "latest": "2.3.1", - "name": "iniconfig" - }, - { - "current": "1.12.0", - "ecosystem": "python", - "latest": "1.12.0", - "name": "nodeenv" - }, - { - "current": "1.45.2", - "ecosystem": "python", - "latest": "1.45.2", - "name": "opentelemetry-api" - }, - { - "current": "0.66b2", - "ecosystem": "python", - "latest": "0.66b2", - "name": "opentelemetry-instrumentation" - }, - { - "current": "0.66b2", - "ecosystem": "python", - "latest": "0.66b2", - "name": "opentelemetry-instrumentation-dbapi" - }, - { - "current": "0.66b2", - "ecosystem": "python", - "latest": "0.66b2", - "name": "opentelemetry-instrumentation-psycopg" - }, - { - "current": "1.45.2", - "ecosystem": "python", - "latest": "1.45.2", - "name": "opentelemetry-sdk" - }, - { - "current": "0.66b2", - "ecosystem": "python", - "latest": "0.66b2", - "name": "opentelemetry-semantic-conventions" - }, - { - "current": "26.3", - "ecosystem": "python", - "latest": "26.3", - "name": "packaging" - }, - { - "current": "1.1.1", - "ecosystem": "python", - "latest": "1.1.1", - "name": "pathspec" - }, - { - "current": "18.6.1", - "ecosystem": "python", - "latest": "18.6.1", - "name": "pgserver-pg18", - "source": "https://github.com/DocumentDrivenDX/pgserver/releases/tag/pg18.6-pgv0.8.6-r2" - }, - { - "current": "4.14.3", - "ecosystem": "python", - "latest": "4.14.3", - "name": "platformdirs" - }, - { - "current": "1.7.0", - "ecosystem": "python", - "latest": "1.7.0", - "name": "pluggy" - }, - { - "current": "7.2.2", - "ecosystem": "python", - "latest": "7.2.2", - "name": "psutil" - }, - { - "current": "3.3.7", - "ecosystem": "python", - "latest": "3.3.7", - "name": "psycopg" - }, - { - "current": "3.3.7", - "ecosystem": "python", - "latest": "3.3.7", - "name": "psycopg-binary" - }, - { - "current": "2.14.2", - "ecosystem": "python", - "latest": "2.14.2", - "name": "pydantic" - }, - { - "current": "2.50.2", - "ecosystem": "python", - "latest": "2.50.2", - "name": "pydantic-core" - }, - { - "current": "2.21.0", - "ecosystem": "python", - "latest": "2.21.0", - "name": "pygments" - }, - { - "current": "1.3.3", - "ecosystem": "python", - "latest": "1.3.3", - "name": "pyproject-hooks" - }, - { - "current": "1.1.414", - "ecosystem": "python", - "latest": "1.1.414", - "name": "pyright" - }, - { - "current": "9.2.0", - "ecosystem": "python", - "latest": "9.2.0", - "name": "pytest" - }, - { - "current": "1.4.1.post1", - "ecosystem": "python", - "latest": "1.4.1.post1", - "name": "pytest-asyncio" - }, - { - "current": "0.17.3", - "ecosystem": "python", - "latest": "0.17.3", - "name": "ruff" - }, - { - "current": "1.10.0", - "ecosystem": "python", - "latest": "1.10.0", - "name": "starlette" - }, - { - "current": "0.15.2", - "ecosystem": "python", - "latest": "0.15.2", - "name": "tomlkit" - }, - { - "current": "2026.9.21.13", - "ecosystem": "python", - "latest": "2026.9.21.13", - "name": "trove-classifiers" - }, - { - "current": "4.16.0", - "ecosystem": "python", - "latest": "4.16.0", - "name": "typing-extensions" - }, - { - "current": "0.4.4", - "ecosystem": "python", - "latest": "0.4.4", - "name": "typing-inspection" - }, - { - "current": "2026.6", - "ecosystem": "python", - "latest": "2026.6", - "name": "tzdata" - }, - { - "current": "0.10.8", - "ecosystem": "python", - "latest": "0.10.8", - "name": "umf-core" - }, - { - "current": "0.4.57", - "ecosystem": "python", - "latest": "0.4.57", - "name": "umf-weft" - }, - { - "current": "0.54.0", - "ecosystem": "python", - "latest": "0.54.0", - "name": "uvicorn" - }, - { - "current": "2.5.2", - "ecosystem": "python", - "latest": "2.5.2", - "name": "wrapt" - } - ], - "release": "runtime-v0.1.0a2", - "state": "local qualification and independent review passed; GitHub CI and publication pending", - "tools": { - "bun": "1.4.4", - "node": "26.13.0", - "oxlint": "1.91.0", - "playwright": "1.64.1", - "python": "3.13.16", - "typescript": "7.0.2", - "uv": "0.13.7" - } -} diff --git a/docs/helix/04-build/implementation-plan.md b/docs/helix/04-build/implementation-plan.md deleted file mode 100644 index 7eebe3d..0000000 --- a/docs/helix/04-build/implementation-plan.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -ddx: - id: implementation-plan - type: implementation-plan - activity: build - authoring: - home: repo - links: - - id: TD-006 - kind: derived_from - - id: CONTRACT-002 - kind: informed_by ---- - -# Local storage implementation plan - -## Scope - -Governing artifacts: PRD FR-26, ADR-007/010, CONTRACT-002/006/008, TD-006 and -TP-001 STO-01–15. The owner authorizes merging the evolved specifications into -main, then implementing the local filesystem backend with platform modularity. - -## Shared Constraints - -Async-first; stdlib product boundary; explicit typed configuration; no new -application environment variables; no credentials/private source. Preserve -platform-neutral core, optional distributions and downward quality ratchets. - -## Implementation Slices - -| Slice | Area | Depends on | Validation gate | -| --- | --- | --- | --- | -| B-001 | Validate and integrate evolved specifications on main | None | Artifact/schema/guide/static checks; source-control confirmation | -| B-002 | Executable quality scaffold | B-001 | Real import/cycle/private/shape/export/census positive and negative controls; common just lint recipe | -| B-003 | Portable storage and local POSIX provider | B-002 | Native STO conformance and explicit host authority/outcome injection | -| B-004 | Streams, bounded listing, conditions/ranges and upload lifecycle | B-003 | Concurrency, denial, lifetime, recovery and integrity observations | -| B-005 | Installed artifact, documentation and final review | B-004 | Build/install in clean environment; zero cloud dependencies; full common gate | - -## Execution Contract - -The owner's current instruction authorizes these slices. Specification integration -is committed and pushed to main before source implementation. Source work remains -reviewable on a codex branch. No remote repository creation, infrastructure change -or upstream implementation is required. Token usage estimate and monetary cost -are unknown; no spending ceiling was supplied. Available tools expose no reliable -per-task billing meter. Verification and review are included in the authorized work. - -## Continuation Evidence - -Resume from git diff, this plan and actual gate/test output. Record safe evidence -in local-storage-verification.json; tracker status stays in project ddx beads when -updated. B-001 completed with specification integration pushed to main at -61f4ae1efedb393e339cac99f182bc9b57085907. B-002 through B-005 are implemented -on codex/local-object-storage. The common recipe passed on the local macOS POSIX -profile: 17 behavior functions, 20 collected cases, strict typing, shape/import -checks and a clean wheel-only import observation. This reviewed initial suite -establishes the measured ceiling of 17 functions; parameter cases do not increase -that ceiling. Negative controls cover module/vendor/private/loader access, cycles, -export drift, missing accepted baseline and increased test ceilings. - -Published data survived handle/provider restart. Separate OS processes competed -on the same validator with one successful publication, while an existing reader -retained its original generation. Feature revocation, partial reads, expiry, -cancellation, active-part abort and post-publication observation loss were exercised. -The implementation and evidence remain reviewable source; no product package -registry publication or Databricks/native runtime integration is claimed. - -## Validation Plan - -Validate governed documents and schemas; independently evaluate changed guide -pages. Test concrete native filesystem behavior and installed package closure. -Review typed APIs, import ownership, authorization, concurrency and possible effects. -Apply the same quality recipe locally, in hooks and CI; missing checks fail. - -## Risks and Rollbacks - -| Risk | Response | Rollback | -| --- | --- | --- | -| Unsupported filesystem semantics | Refuse profile before effects | Retain data and select qualified host | -| Defective source slice | Keep source branch reviewable | Revert reviewed source; immutable data remains untouched | -| Concurrent documentation edits | Preserve and revalidate current sources | Never overwrite unrelated owner work | - -## Exit Criteria - -Specifications are integrated into main. Local storage implements its qualified -profile with explicit unsupported refusals for other profiles. Required native, -installed and quality checks pass; evidence and remaining platform qualification -limits are accurate. No full-runtime or Databricks implementation claim is made. diff --git a/docs/helix/04-build/integration-gaps.md b/docs/helix/04-build/integration-gaps.md deleted file mode 100644 index 5777957..0000000 --- a/docs/helix/04-build/integration-gaps.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -ddx: - id: batten.integration-queue - type: implementation-plan - activity: build - authoring: - home: repo - links: - - id: batten.prd - kind: informed_by - - id: CONTRACT-011 - kind: informed_by - - id: ADR-015 - kind: informed_by ---- - -# Integration gaps for enterprise applications - -## Scope - -Close Batten assembly gaps by integrating the existing platform, then qualify -the reference apps through their public boundaries. Reuse the existing -composition, host, saga and ux-builder work items rather than create competing -engines. Governing scope: FR-29–31/47/48, CONTRACT-001/003/004/005/006/007/009/011, -ADR-001/002/005/009/014/015 and each selected reference app's test plan. - -## Shared Constraints - -UMF + PostgreSQL provides table ORM/typed access. UMF + Truss provides graph -ORM/typed access. Batten supplies capability binding, current authority, -attribution, lifecycle and cross-surface delivery. It must not reimplement these -ORMs, Weft's compiler, UMF actions/sagas, Arras ontology or Tether's agent loop. -PostgreSQL 18 only; an explicit local pgserver instance may serve table and -Truss bindings with separate scoped authority. Shared server does not establish -shared transactions or identity. Native schema changes remain separately authorized. - -Initial UI delivery means a TypeScript app. Do not block useful app delivery on -building a declarative UI compiler. Keep ux-builder assets/tooling integration -available through qualified public APIs and isolate it from headless modules. -All browser calls pass through the public host client, never native providers. - -Source inspection of UMF's typed-persistence integration evidence and Truss's -public Python documentation supports this integration direction; neither proves -Batten's installed/native cohort. UMF's source is b12a489844f29947ee52115b90f4ccc5c8bc5032; -Truss's inspected source is 14e16ce852381fd376da1d2187fc941683903ab2. -Their published/versioned compatibility sets must intersect explicitly; combining -the latest sources by name is not a qualified cohort. - -## Implementation Slices - -| Slice | Integration owner / approach | Work item | Depends On | Validation Gate | -| --- | --- | --- | --- | --- | -| INT-01 | Batten inert admission and metadata closure | batten-916449b0; cohort batten-9a5d7122 | Existing composition contracts | Effect-free assessment, native schema evidence and no private imports | -| INT-02 | Public host, scoped services and lifecycle | batten-2b9e6014 | INT-01 | Authenticated/local-stub distinction, current authority, safe audit/telemetry and ownership | -| INT-03 | UMF/PostgreSQL table ORM binding | batten-a77dd24d | INT-02 | Native PostgreSQL 18 actions/reads/bulk, row policy, stale writes and exact installed artifacts | -| INT-04 | UMF/Truss graph ORM binding | batten-e7af34e7 | INT-02 | Hidden graph endpoints/counts, native policy and original model identities | -| INT-05 | Public TypeScript client and local host | batten-39cb6fe0 | INT-02 | Same operation identity, server authority, navigation/download boundary and local pgserver configuration | -| INT-06 | Authored TypeScript app and ux-builder tooling | Existing batten-6e684a3f | INT-03/05 | Approval-desk browser journey, keyboard/focus and denied/uncertain results; no generated UI claim | -| INT-07 | Existing local storage binding; separate Volumes adapter | batten-8dd09b19 | INT-02/03 | Evidence-library row/blob reconciliation; exact local versus remote feature qualification | -| INT-08 | Native UMF action/saga binding | Existing batten-0b5cad5d | INT-01/02 | Original executor/profile/receipt semantics, uncertainty and unsupported refusal | -| INT-09 | Existing platform workers/jobs and schedules | batten-edc84420 | INT-02/08 | Scheduled-digest occurrence identity, concurrency, cancellation and attribution | -| INT-10 | PostgreSQL durable messages and consumer scopes | batten-e3665458 | INT-02/03 | Intake/triage delivery/retry/recovery without duplicate business effect | -| INT-11 | Tether, model API and scoped retrieval | batten-341346a4 | INT-02/03/05 | Document-review and knowledge provenance, budgets, human decisions and unavailable API | -| INT-12 | Arras/UMF service discovery and binding | batten-e50731a9 | INT-04/10 | Service-handoff exact interfaces, receiver authority and revocation/drift | -| INT-13 | Native action/CLI and app/browser evidence runner | batten-5fa3e526 | INT-01/02/03/05 | Independent oracle, broken-adapter controls, real client-host-provider observations and exact evidence | - -INT-13 begins with the first vertical slice and grows through data-driven cases; -it must not wait until every adapter is implemented. Additional native source -gaps stay with the owning project and block only affected profiles. Diagnose the -specific missing public capability before proposing any replacement machinery. - -## Execution Contract - -The owner requested this queue and the reference-app workflow. These future -integration tasks have execution authorization off until a bounded build is -selected; source inspection and tracking are not platform delivery. Earlier local -storage authorization and implementation remain intact. No production apply, -secret access, schema migration, remote repository creation or commit is implied. -Token, time, staffing and spending budgets are unknown; Erik supplies them. -No reliable task billing meter is available. Include verification in each build. - -## Continuation Evidence - -Use ddx as the live tracker and `01-frame/work-items.jsonl` as its review export. -Corpus/workflow task batten-4192222e is committed and pushed as 27f0876. -The owner selected the first app build; batten-b6c932f2 implements the bounded -local approval desk (INT-01/02/03/05/06/13) under ADR-016 and CONTRACT-012. -The complete integration tasks remain open beyond that exercised subset. -Follow with entity-directory for the graph path and evidence-library for row/blob recovery. -These are planning defaults, not fabricated production priorities or deadlines. - -## Validation Plan - -The common gate checks corpus integrity and existing source behavior. Missing -complete execution evidence fails strict qualification. For each integration, -reuse upstream behavioral evidence and test only the distinct Batten binding, -authority/lifecycle/attribution outcomes. Extend the measured suite through -parameterized cases without increasing the test-function ceiling. App domains -need independent expected results; storage unit tests cannot stand in for them. - -## Risks and Rollbacks - -| Risk | Impact | Response | Rollback | -| --- | --- | --- | --- | -| Upstream native feature is incomplete | Blocks a profile | Pin exact supported subset and queue upstream owner gap | Refuse the affected required app capability | -| Procedural UI becomes privileged integration glue | Policy bypass | Use public client/host, typed actions and server authority | Disable affected operation binding | -| Stateful upgrade changes meaning | Data/recovery risk | Requalify original app semantics and migration route | Use only verified native recovery | -| Duplicate test engines and hidden skips | False coverage | Reuse platform tooling and require independent negative controls | Withdraw affected qualification | - -## Exit Criteria - -An integration gap closes only with exact installed/native evidence and its -affected app's required client-host-provider journey. Complete-app qualification -requires all active obligations, safe required telemetry and candidate-cohort -replay. Inventory integrity, source inspection and component evidence remain -separate results, never substitutes for a required positive app execution. diff --git a/docs/helix/04-build/local-storage-verification.json b/docs/helix/04-build/local-storage-verification.json deleted file mode 100644 index 131bfa2..0000000 --- a/docs/helix/04-build/local-storage-verification.json +++ /dev/null @@ -1,69 +0,0 @@ -{ - "scope": "Local object-storage source slice; no complete runtime, Databricks, OpenTelemetry receiver or deployment qualification", - "date": "2026-10-29", - "specification_main": "61f4ae1efedb393e339cac99f182bc9b57085907", - "source_branch": "codex/local-object-storage", - "source_state": "Implementation included with this evidence; use the enclosing Git revision for source identity", - "command": "uv run python scripts/quality.py", - "observed_platform": { - "system": "Darwin", - "release": "27.0.0", - "machine": "arm64", - "python": "3.11.17" - }, - "suite": { - "behavior_functions": 17, - "collected_cases": 20, - "result": "passed" - }, - "checks": [ - "import ownership, cycles, private imports and public export inventory", - "missing baseline and raised ceiling negative controls", - "Ruff shape/format and strict Pyright", - "ESLint browser source shape", - "native local async object/range/condition/list/upload behaviors", - "competing conditional writers across OS processes", - "clean installed-wheel imports without platform dependencies" - ], - "limitations": [ - "Managed local POSIX namespace and cooperating writers only; no network-filesystem qualification", - "Atomic visibility does not establish power-loss durability", - "No performance target or throughput result supplied; owner Erik supplies workload and budgets", - "No package-registry publication, full Batten host, cloud backend or live telemetry receiver tested" - ], - "source_sha256": { - "bun.lock": "7f4213c5d88b97e730bf1c279c669e27931bf8d00c6c7d6dc60e5667e6bac8c6", - "packages/batten-storage/src/batten/storage/__init__.py": "10288d1ecf8afc9bf8e3dfa7514bc99adbbc179b46209677aab875ab23daa342", - "packages/batten-storage/src/batten/storage/_protocols.py": "09cb78e5eb8162d8b1b673e9e48630094c9289787357e4c0b3191e31c44383b1", - "packages/batten-storage/src/batten/storage/_values.py": "7ce140f4ae7c799ce42d29322a3f016079cf40f59484fd5c67db9a66edcb0849", - "packages/batten-storage/src/batten/storage/local/__init__.py": "87ba41bf18f959bdd99da89f7a96a0afbac2065ced106cf3a8abb409b179b3a3", - "packages/batten-storage/src/batten/storage/local/_budget.py": "588fbf8d3bfbec3adbc5e28cb9a17865248e5498ff191e3f8abcf47681caea0d", - "packages/batten-storage/src/batten/storage/local/_features.py": "4cae6bbc8e6e51bd7a72892c537cc65bf3c239c09d617045cd23b5715c821791", - "packages/batten-storage/src/batten/storage/local/_filesystem.py": "6ba91af8bb1f91fa2821e2898fa379b7275b0ee86bfbb65253c88b095262ece8", - "packages/batten-storage/src/batten/storage/local/_listing.py": "9edf013c61517100ef832c6c7c37856339ecd6f4dc2110baec200227a5977444", - "packages/batten-storage/src/batten/storage/local/_observations.py": "ceee394e77535f7a8cfbb93f2a88d504ccee978766baa461d7b2145215a009ca", - "packages/batten-storage/src/batten/storage/local/_pages.py": "b59b061277783568dc74305b0d390b29d8c537f4f62e503a12c2e14ea18ff683", - "packages/batten-storage/src/batten/storage/local/_part_pages.py": "df5e42777a961b81f22c06f38930a1f2d3e5b50749107ac978f9b5325e4d23ac", - "packages/batten-storage/src/batten/storage/local/_provider.py": "d00f4b27584e837a964402405fcd110b62b6c7c05fdaf7290e5bb1317971b1ca", - "packages/batten-storage/src/batten/storage/local/_reads.py": "a44ec31e188c46645f558a21f35c34267ed954b81e62a88cebb4b321d87811eb", - "packages/batten-storage/src/batten/storage/local/_scope.py": "9131d757ef863834f0799f02cb7d15cc2ac5576c9dd69535add8a09c001d7bfd", - "packages/batten-storage/src/batten/storage/local/_transfers.py": "a84011202f409de114cdfbf1e5ff3d104baa2b22e0cfe9c898c31ac0a322e7a7", - "packages/batten-storage/src/batten/storage/local/_upload_state.py": "8db68b695870143efe3536b072d1bcc1f93729eff4dced5d00ffaffd911ea787", - "packages/batten-storage/src/batten/storage/local/_uploads.py": "04cccf4360555e15cd37034bf983f48dcbca2ea73ef3a2e5fc8651c4e2867f97", - "pyproject.toml": "bfeec13918f7fe0b4e64da73abece31050f67eeec23d526b174729d6804b1680", - "scripts/boundary_checks.py": "13816ef34f8c6beef06f98007e6e9b99808b69e777bc75893370e12e3965c44d", - "scripts/boundary_model.py": "bdd4c17a23b8debd5dfe0df5ce10042bd770b1b28aa6d3b80503ec8c3104281c", - "scripts/check_boundaries.py": "65de7b940c407f99786353120b6d4685f4bb8dc18c97aca17b3b99e8116520f1", - "scripts/check_policy.py": "75744c463f0ee180c506a4fbe17a71fb5e7ded726b6454337c91f9786cdebf01", - "scripts/quality.py": "78317a67d8da640ebef0ab6d349b85715b9560c7f46f2026c7d6996745971a4b", - "tests/quality/test_gate.py": "24c3b7b90b490d2c9d94664183992a5cdfd45fbef351bc1c49f9649f60317431", - "tests/storage/conftest.py": "3419a2c2a1158f5a9bca2128f5cc561d7b2c9e884e054ca0a021e1bc34f29505", - "tests/storage/test_distribution.py": "9142c6c773b427683426a05b8cb48e982cde09f11b1b3589db6b66595c8bccad", - "tests/storage/test_expiry_cancellation.py": "17d7baf8e41aa2e440f2b7fef011b247e9778a5b342238ec94cf896954a8f838", - "tests/storage/test_listing_uploads.py": "2285a021b0d8e1a73407fff05daf8a4b7a19497f1f10afd52248453504a05a72", - "tests/storage/test_objects.py": "57223d3d256bfff4f6d921cf9440c5317dda74529d6a5f7759725becab0fe0a8", - "uv.lock": "1987b04f020fc144f677753f72417866cf3200a13e13dc497e87f0cfd20df1a9" - }, - "quality_exit_code": 0, - "latest_verified_date": "2026-10-30" -} diff --git a/docs/helix/04-build/micro-app-corpus-verification.json b/docs/helix/04-build/micro-app-corpus-verification.json deleted file mode 100644 index b0bbfd7..0000000 --- a/docs/helix/04-build/micro-app-corpus-verification.json +++ /dev/null @@ -1,25 +0,0 @@ -{ - "date": "2026-11-02", - "scope": "Enterprise reference-app specifications, HELIX bindings, gap queue and inventory gate; no app runtime implementation", - "base_revision": "266be79770b297743cbb0421f142bc88686f6f1d", - "corpus_sha256": "f3d416d3080febbbdbcb224f9d16269bad9b9869e905bf34fdfe9b7de2363ca6", - "reference_app_count": 12, - "common_command": "uv run python scripts/quality.py", - "common_exit_code": 0, - "behavior_functions": 17, - "collected_cases": 20, - "test_outcome": "passed", - "artifact_validation": "60 changed/new governed artifacts pass installed HELIX validator", - "guide_validation": "6 independently evaluated pages, 0 blocking findings, 3 existing unmapped-source warnings; static build/link checks pass", - "strict_qualification": { - "command": "python scripts/check_micro_apps.py --require-execution", - "exit_code": 1, - "outcome": "Complete app execution is unqualified; expected fail-closed refusal" - }, - "code_sha256": { - "scripts/check_micro_apps.py": "bd4f34966473347fff4f21749249ffdece813180692f0bbd4e5cc3abcbc34b1b", - "scripts/quality.py": "b0a837148a7f8f4cde492028a66ebb2f8c5f54fce650537869ccce5e0b547c59", - "tests/quality/test_gate.py": "3bb7d55d560c31c5f21fdb0364bc851b1313a468bc3059568220fded44ecc5d2" - }, - "integration_policy": "Reuse UMF/PostgreSQL table ORM and UMF/Truss graph ORM; initial UI is authored TypeScript using public host/client; no additional engine selected" -} diff --git a/docs/helix/05-deploy/.gitkeep b/docs/helix/05-deploy/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/docs/helix/05-deploy/release-notes.md b/docs/helix/05-deploy/release-notes.md deleted file mode 100644 index e7e61b9..0000000 --- a/docs/helix/05-deploy/release-notes.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -ddx: - id: batten.release.0.1.0-alpha.1 - type: release-notes - activity: deploy - authoring: - home: repo - links: - - id: batten.product-vision - kind: informed_by - - id: batten.feature-registry - kind: informed_by ---- - -# Batten 0.1.0-alpha.1 - -## Release Scope - -Batten's first design-preview release includes the public requirements, proposed -contracts and documentation microsite. The SDK runtime and installable packages -are not implemented. - -- Version: `v0.1.0-alpha.1`, a prerelease. -- Release date: 2026-10-29. -- Publication: GitHub Releases and the repository's GitHub Pages site. -- Release owner: Batten maintainers. - -## Audience and Channels - -| Audience | What is available | Channel | -| --- | --- | --- | -| Application authors | Vision, composition examples and platform boundaries | Microsite and design records | -| Host integrators | Proposed module, hosting and lifecycle contracts | Repository and release | -| Contributors | Source-stamped guide and reproducible static build | Repository and site archive | - -## Highlights - -- Explore selectable capabilities, hosting environments and execution placement. -- Read the UMF, Weft, Arras, Tether and ux-builder ownership boundaries. -- Browse the design guide on desktop or phone, in light or dark mode. - -## Required Actions Summary - -Readers need no installation or account to browse the site. This release -requires no application migration or database changes. - -## Changes and Fixes - -### New or Improved - -The microsite has six source-backed explanations, an interactive architecture -explorer, design-source links and a guide-provenance page. The explorer changes -an illustration; it does not execute or assess an application. - -The repository includes requirements, acceptance stories, proposed contracts, -module boundaries and work items. The release archive contains the built static -site with local assets and a checksum file. - -The Pages workflow builds and checks the site before deployment. Pull requests -build without publishing; successful pushes to `main` publish the site. - -## Breaking Changes and Required Actions - -This is the first release. There is no prior public runtime to migrate and no -breaking runtime change. No user action is required. - -## Migration or Rollback Guidance - -### Upgrade or Migration - -Browse the site or download the static site archive. No SDK installation is -provided by this release. - -### Rollback or Hold Guidance - -Maintainers can redeploy a previously reviewed site revision through the Pages -workflow. Pause publication if the build or link checks fail. Release archives -retain the versioned site independently of later changes on `main`. - -## Known Issues and Support - -The site describes proposed SDK behavior. Native platform support, live hosting, -UMF saga executors and ux-builder runtime integration require separate qualification. -Remote-worker selection illustrates a design option and grants no execution support. - -Use the repository's contribution workflow for feedback. Implementation work -remains governed by project-scoped ddx items. - -## References - -- [Microsite](https://documentdrivendx.github.io/batten/). -- [Design guide](../guide/developer/index.md). -- [Site build and publishing](../site/README.md). -- [Release](https://github.com/DocumentDrivenDX/batten/releases/tag/v0.1.0-alpha.1). diff --git a/docs/helix/05-deploy/runtime-release-0.1.0a1.md b/docs/helix/05-deploy/runtime-release-0.1.0a1.md deleted file mode 100644 index 45b3f98..0000000 --- a/docs/helix/05-deploy/runtime-release-0.1.0a1.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -ddx: - id: batten.runtime.release.0.1.0a1 - type: release-notes - activity: deploy - authoring: - home: repo - links: - - id: ADR-016 - kind: informed_by - - id: CONTRACT-012 - kind: informed_by - - id: US-101 - kind: informed_by ---- - -# Batten local runtime 0.1.0a1 - -## Release Scope - -`runtime-v0.1.0a1` is the first runnable local application prerelease: an approval -desk, a visual application registry and independently packaged runtime modules. -Release date: November 2, 2026. Batten maintainers own this GitHub release. -The existing design/site and storage releases retain their own tags. - -## Audience and Channels - -| Audience | Available capability | Channel | -| --- | --- | --- | -| App authors | Working native-table approval app and authored TypeScript UI | Source checkout and installed app wheel | -| Host integrators | Portable contracts/runtime/table port, optional native adapter, HTTP transport and local composition | Separate wheels on GitHub Releases | -| Contributors | Exact original platform cohort, qualification receipt and repeatable tests | Repository and release assets | - -## Highlights - -- Open the local registry to choose an app with a description and visual preview. - The Batten brand returns to the registry. -- Submit and edit requests, inspect their revisions, and independently approve - or reject them through original UMF/Weft on PostgreSQL 18. -- Recover a lost mutation response using its original native receipt. Restarting - retains requests and receipts; local sessions require a new login. - -## Required Actions Summary - -Use Python 3.11 and the recorded dependency cohort for this preview. Source -assembly also uses Bun 1.4.4 and uv. Explicitly initialize a new dedicated -fabricated database before serving. Run with loopback-only stub identities; -this is a local development profile. - -Dependency audit: CI pins uv 0.13.6, Bun 1.4.4 and current compatible Python -tools. UMF access 0.1.0.dev8 and codegen 0.1.0a5 are the newest published -compatible original wheels; UMF 0.10.1 publishes `umf-core` but no replacement -access/codegen pair. `weft-sql` 0.4.54 is the newest published distribution; -Weft 0.4.56 publishes a separate `umf-weft` package. TypeScript 7.0.2 is the -newest compiler, but `@typescript-eslint/parser` 8.72.1 explicitly rejects it; -Batten uses the latest compatible TypeScript 6.0.3. - -## Changes and Fixes - -### New or Improved - -The release adds `novirhyza-batten-contracts`, `novirhyza-batten-runtime`, -`novirhyza-batten-tables`, `novirhyza-batten-umf-postgres`, -`novirhyza-batten-asgi`, `novirhyza-batten-local` and -`novirhyza-batten-approval-desk`, all at `0.1.0a1`. -Core contracts, runtime and the portable table port remain independent of native -providers. Original UMF SDK wheels accompany the cohort as upstream dependencies; -Batten does not carry a replacement ORM or compiler. - -The registry uses explicit host-owned app metadata and packaged fabricated -thumbnails. Apps use distinct URL prefixes and API cookie paths. Host/origin -checks protect both the registry and app routes. Safe local audit and linked -OpenTelemetry spans preserve operation identity without logging request text, -SQL or connection details. - -### Fixes - -Identity selection waits for app initialization, preventing fast registry -navigation from selecting an identity before its handlers are ready. -A separate app-only rebuild command speeds UI and hook iteration against the -already prepared platform cohort. - -## Breaking Changes and Required Actions - -This is the first public local-runtime package release. For anyone using the -unreleased root-page demo, `/` is now the registry and the app is at -`/apps/approval-desk/`. Refresh the browser and establish a local session again. -The app's API routes and cookie path follow its URL prefix. - -No database migration accompanies this release. Startup verifies the installed -model and schema head and refuses drift; it never creates roles or migrates tables. - -## Migration or Rollback Guidance - -### Upgrade or Migration - -From the release source checkout: - -```sh -uv sync --frozen --all-packages -bun install --frozen-lockfile -just approval-prepare -just approval-init -just approval -``` - -Open `http://127.0.0.1:8820/`. Initialization refuses an existing data directory; -retain an existing matching demo workspace and run `just approval` to reopen it. -Use `just approval-refresh` after app-only edits, then restart the host. -Model changes require an explicitly initialized matching workspace. - -The release includes separate wheels, the qualified cohort and constraints, -checksums, original upstream SDK dependencies and installation instructions. -Package assembly happens before runtime startup; serving does not install packages. - -### Rollback or Hold Guidance - -Retain the release assets and matching application data/model together. Stop the -host before changing its installed environment. Restore the previous matching -cohort and app artifacts, then reopen the retained workspace. Hold an upgrade -when model/head verification or an affected native/browser assertion fails. - -## Known Issues and Support - -Native execution is qualified for the recorded macOS arm64, Python 3.11 and -PostgreSQL 18 local cohort. Linux CI supplies its own exact result. Platform-neutral -wheel tags alone do not establish other native profiles. Local stub identity and -local span capture do not establish production login or OTLP receiver qualification. - -The strict full-corpus conformance gate retains its separate requirements. Use -project-scoped ddx work items for integration work and the recorded app evidence -to assess this release's bounded claims. No PyPI publication is included. - -## References - -- [Run and iterate on the approval desk](../../../examples/approval-desk/README.md) -- [Local execution evidence](../reference-apps/approval-desk/specs/03-test/local-execution.json) -- [Local HTTP and registry contract](../02-design/contracts/CONTRACT-012-local-operation-host.md) -- [Platform assembly decision](../02-design/adr/ADR-016-local-approval-stack.md) diff --git a/docs/helix/05-deploy/runtime-release-0.1.0a2.md b/docs/helix/05-deploy/runtime-release-0.1.0a2.md deleted file mode 100644 index 00acee1..0000000 --- a/docs/helix/05-deploy/runtime-release-0.1.0a2.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -ddx: - id: batten.runtime.release.0.1.0a2 - type: release-notes - activity: deploy - authoring: - home: repo - links: - - id: ADR-005 - kind: informed_by - - id: ADR-007 - kind: informed_by - - id: ADR-016 - kind: informed_by - - id: CONTRACT-012 - kind: informed_by ---- - -# Batten local runtime 0.1.0a2 - -## Release Scope - -`runtime-v0.1.0a2` updates the local approval desk's dependency cohort and its -qualification tooling. Batten maintainers own this GitHub prerelease, dated -November 3, 2026. The independent storage release remains `storage-v0.1.0a1`. - -## Audience and Channels - -| Audience | Available material | Channel | -| --- | --- | --- | -| App authors | Approval desk, local registry and updated run instructions | Source and seven Batten wheels | -| Platform integrators | Original UMF companion wheels, exact cohort and constraints | GitHub release assets | -| Contributors | TypeScript 7, Oxlint and JavaScript Playwright qualification | Source, lockfiles and evidence | - -## Highlights - -- UMF Codegen and matching native Core move to 0.10.8; access remains dev8. -- The SQL compiler moves from `weft-sql` 0.4.54 to `umf-weft` 0.4.57. - The Python import remains `weft`. -- Psycopg moves to 3.3.7. Development uses Python 3.13, Node 26.13.0 LTS, - Bun 1.4.4 and uv 0.13.7. -- TypeScript 7.0.2 and Oxlint 1.91.0 replace the compiler-coupled ESLint parser. - JavaScript Playwright retains the same two browser scenarios. - -## Required Actions Summary - -Prepare the recorded toolchain and install from the exact release cohort. The -new local qualification profile uses Python 3.13. Portable library metadata -retains its Python 3.11 floor; profile support follows actual recorded evidence. - -Use a new dedicated fabricated workspace for initial qualification. Existing -installations require their matching verified model/head and cohort; startup -never performs an implicit migration. - -## Changes and Fixes - -### New or Improved - -The original Codegen 0.10.8 wheel requires exactly Core 0.10.8. Compilation uses -the native Rust compiler supplied by Core. The assembler pins access and Codegen -artifacts independently to their original releases and hashes, then resolves -Core through normal dependency resolution. No replacement compiler is carried. - -The obsolete Python Playwright, pyee, greenlet and V8 compiler dependencies leave -the cohort. Browser tests use `@playwright/test` 1.64.1. All prior authority, -stale-revision, receipt recovery, restart, installation-head, telemetry and -registry assertions remain in their registered scenarios. - -Oxlint preserves the complexity 10, function-line 60, nesting 4 and one-class -limits. Positive and negative controls exercise each real rule. The common gate -counts Python and JavaScript test registrations together, including import aliases, -namespaces and assertion-bearing helpers; the ceiling remains 17 behaviors. - -The latest Node declarations select an older Undici type package by default. -An explicit type-only override selects `undici-types` 8.12.3, checked by strict -TypeScript declaration validation and the same browser scenarios. This adds no -HTTP runtime implementation. The version audit records all locked packages. - -### Fixes - -Browser setup waits for enabled identity controls. The migrated tests retain -actual lost-response recovery and live native grant revocation; no scripted -substitute supplies database or browser results. App-only refresh selects the -exact declared wheel version even when the cache retains an older release. - -## Breaking Changes and Required Actions - -Contributor tooling changes to the recorded Python 3.13 and Node LTS profile. -Run `just approval-test` for the JavaScript browser suite. `just test` includes -both Python and browser scenarios; `just check` remains independent of database -processes. Application routes and operation envelopes retain their prior shape. - -## Migration or Rollback Guidance - -### Upgrade or Migration - -From this release's source checkout, install the locked tools, run -`just approval-prepare`, explicitly initialize a dedicated fabricated workspace, -and start the host with `just approval`. Install the selected Chromium revision -with `node node_modules/playwright/cli.js install chromium` before browser tests. -The package installer never runs during application startup. - -### Rollback or Hold Guidance - -Retain the prior release assets and their matching workspace together. Stop the -host before changing its installed environment. Hold an upgrade if model/head, -current authority, receipt or required telemetry checks refuse. Reverting package -versions does not reverse database changes or completed business effects. - -## Known Issues and Support - -Qualification remains the recorded local approval-desk subset on PostgreSQL 18. -The microsite's twelve walkthroughs distinguish this runnable app from the other -specification journeys. This release does not establish complete fleet operation, -production authentication, hostile-code containment or an OTLP receiver profile. -No PyPI publication of Batten is included. - -## References - -- [Run the approval desk](../../../examples/approval-desk/README.md) -- [Local execution evidence](../reference-apps/approval-desk/specs/03-test/local-execution.json) -- [Dependency upgrade evidence](../04-build/dependency-upgrade/verification.json) -- [Quality and test policy](../02-design/adr/ADR-007-quality-and-test-ratchets.md) diff --git a/docs/helix/05-deploy/storage-release-0.1.0a1.md b/docs/helix/05-deploy/storage-release-0.1.0a1.md deleted file mode 100644 index 7cad34a..0000000 --- a/docs/helix/05-deploy/storage-release-0.1.0a1.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -ddx: - id: batten.storage.release.0.1.0a1 - type: release-notes - activity: deploy - authoring: - home: repo - links: - - id: CONTRACT-006 - kind: informed_by - - id: ADR-010 - kind: informed_by - - id: implementation-plan - kind: informed_by ---- - -# Batten storage 0.1.0a1 - -## Release Scope - -`storage-v0.1.0a1` delivers the `novirhyza-batten-storage==0.1.0a1` wheel and -source distribution as a GitHub prerelease. It packages the already-merged -portable async storage protocols and managed local POSIX provider. The existing -`v0.1.0-alpha.1` design/site preview remains unchanged. - -## Audience and Channels - -Python host authors can download the package archives, checksum manifest and -source/qualification receipt from GitHub Releases. No PyPI publication or -complete Batten application runtime is claimed. - -## Highlights - -The storage module provides scoped object writes, pinned reads and ranges, -conditional replacement, bounded listing and multipart upload lifetimes. -Importing the portable protocol does not import the local adapter or any cloud -or platform dependency. Trusted host code supplies resolved limits, identity, -authorization and outcome observation. - -## Changes and Fixes - -This is the first package delivery of the storage slice already on main. The -common quality recipe passes 20 cases in 17 behavior functions on macOS arm64 -with Python 3.11.17, including competing OS processes, native filesystem behavior, -cleanup and wheel-only import closure. Strict typing, format/lint and boundary -positive/negative controls pass. The Linux source CI retains its own exact -workflow evidence; local qualification does not broaden that record. - -## Breaking Changes and Required Actions - -There is no earlier public storage package to upgrade. Verify `SHA256SUMS` and -install the downloaded wheel in a clean environment. Read the package README -before binding a dedicated owner-only managed directory. All writers must use -the provider and host authorization must be supplied explicitly. - -## Migration or Rollback Guidance - -The release performs no database, cloud or existing-directory migration. Keep -published object data and its ownership/configuration separate from the package -environment. Retain the archive and receipt for repeatable environment rollback. - -## Known Issues and Support - -Qualification covers the recorded managed local POSIX profile and cooperating -writers. Network filesystems, Databricks Volumes, hostile plugin containment, -power-loss durability and performance targets remain unqualified. Atomic -visibility is not a power-loss guarantee. This prerelease does not deliver the -rest of the specified Batten host, worker or platform modules. - -## References - -- [Storage package and host requirements](../../../packages/batten-storage/README.md) -- [Implementation and native evidence](../04-build/local-storage-verification.json) -- [Storage contract](../02-design/contracts/CONTRACT-006-object-storage.md) diff --git a/docs/helix/06-iterate/.gitkeep b/docs/helix/06-iterate/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/docs/helix/README.md b/docs/helix/README.md index 6017e06..424169a 100644 --- a/docs/helix/README.md +++ b/docs/helix/README.md @@ -1,180 +1,19 @@ -# Batten review packet - -## First local reference application - -The owner authorized building the approval desk after the enterprise app packet -was pushed as `27f0876`. Its [run instructions](../../examples/approval-desk/README.md) -use original UMF/Weft tables on PostgreSQL 18 and an authored TypeScript UI. -[ADR-016](02-design/adr/ADR-016-local-approval-stack.md), -[CONTRACT-012](02-design/contracts/CONTRACT-012-local-operation-host.md), and -[TD-101](reference-apps/approval-desk/specs/02-design/technical-designs/TD-101-approval-desk.md) -bound this authorized implementation. Historical review holds below concern -other slices; this app does not qualify the complete fleet or reference corpus. - -## Enterprise micro-apps and authoring workflow - -The [scope evaluation](01-frame/feasibility-study.md) distinguishes design fit, -current component evidence and capabilities needing another qualified platform. -The [reference-app library](reference-apps/README.md) supplies independent HELIX -specification roots, fabricated data and business invariants for twelve patterns. -Use the [Batten app workflow](04-build/batten-app-workflow.md) within a selected -app directory. Installed HELIX owns templates and prompts; no catalog is vendored. - -The [integration queue](04-build/integration-gaps.md) prioritizes existing platform -projects: UMF/PostgreSQL tables, UMF/Truss graphs and the other public capabilities. -Initial UI delivery is an authored TypeScript app, with room for ux-builder, -under [ADR-015](02-design/adr/ADR-015-typescript-app-ui-delivery.md). -Inventory checks are included in the quality gate; complete app execution is a -separate qualification obligation under CONTRACT-011. - -## Lintel GraphQL and Relay integration - -Owner direction selects a separate Python/FastAPI [Lintel runtime](https://github.com/DocumentDrivenDX/lintel/blob/main/docs/helix/README.md) -for inclusion in Batten, with GraphQL + Relay and TypeScript operation/fragment -builds from the same API. REST/OpenAPI product API generation is outside its MVP. -[SD-002](02-design/solution-designs/SD-002-lintel-graphql-relay.md) records public -host composition, authority/custody boundaries and required upstream changes. -This is a planning addition; no Lintel implementation or cohort acceptance is claimed. - -## Fleet operating goal - -Batten targets hundreds of integrated applications sharing a complete qualified -runtime and deep declarative services. Platform-owned dependency upgrades use -required application assertions, behavioral coverage and host-enforced telemetry. -Applications need no pip/npm installation and integrate through governed graph -API capabilities and future defined mechanisms. See the [vision](00-discover/product-vision.md), -[PRD fleet requirements](01-frame/prd.md), [cohort decision](02-design/adr/ADR-005-sdk-series-and-cohort-compatibility.md) -and [verification allocation](03-test/test-plan.md). Capacity and upgrade safety -require qualification; this alignment does not authorize product code or rollout. - -## Composition and hosting packet - -The owner-selected next design slice treats Batten as a core-and-extensions SDK -for declarative AI applications. UMF owns saga semantics; ux-builder owns UX -artifacts and design tooling. This packet prepares source work without authorizing -implementation, migration or deployment. - -1. [FEAT-009: composition and hosting](01-frame/features/FEAT-009-composition-and-hosting.md). -2. [FEAT-002: operations and ux-builder](01-frame/features/FEAT-002-operations-and-interfaces.md). -3. [CONTRACT-003: module/application composition](02-design/contracts/CONTRACT-003-composition.md). -4. [CONTRACT-004: host profiles](02-design/contracts/CONTRACT-004-host-profiles.md). -5. [CONTRACT-005: semantic controls, local implementations and renderer binding](02-design/contracts/CONTRACT-005-ux-builder-binding.md). -6. [ADR-008: independent axes](02-design/adr/ADR-008-independent-composition-axes.md) and - [ADR-009: UX ownership](02-design/adr/ADR-009-ux-builder-ownership.md). -7. [Verification allocation](03-test/test-plan.md) and [work items](01-frame/work-items.jsonl). - -US-001 through US-004 in `01-frame/user-stories/` define the fabricated review -queue across local and embedded hosts. The structural payload schema is an -authoring artifact; registered UMF packages, runtime validators and real service -behavior require implementation and qualification. - - -Batten is an independently implemented application SDK with native platform -dependencies and a public host API. This packet is ready for scope and boundary -review; the owner review gate precedes migration planning and product code. - -## Read in this order - -1. [Product vision](00-discover/product-vision.md) and - [intent](00-discover/intent-and-intake.md). -2. [PRD](01-frame/prd.md): complete specified scope, grouped into stable requirements. -3. [Boundary audit](00-discover/current-state-inventory-boundaries.md): classifications, - import graph, observed coupling, and evidence limits. -4. [Proposed architecture and module split](02-design/architecture.md): purpose, - public API, platform dependencies, and permitted/forbidden imports for each module. -5. [Feature registry](01-frame/feature-registry.md) and [concerns](01-frame/concerns.md). -6. [Decision points](01-frame/decision-points.md): questions needing the owner's judgment. - -## Public contracts - -- [CONTRACT-001: host API](02-design/contracts/CONTRACT-001-public-host-api.md). -- [CONTRACT-002: boundary and quality gates](02-design/contracts/CONTRACT-002-boundaries-and-quality.md). - -## Decisions - -- [ADR-001: platform modules and neutral core](02-design/adr/ADR-001-platform-modules-and-neutral-core.md). -- [ADR-002: native UMF](02-design/adr/ADR-002-native-umf-platform-dependency.md). -- [ADR-003: distributions](02-design/adr/ADR-003-platform-wheel-distribution.md). -- [ADR-004: public asynchronous host](02-design/adr/ADR-004-public-async-host-api.md). -- [ADR-005: SDK series/cohorts](02-design/adr/ADR-005-sdk-series-and-cohort-compatibility.md). -- [ADR-006: typed files](02-design/adr/ADR-006-typed-file-configuration.md). -- [ADR-007: quality/test ratchets](02-design/adr/ADR-007-quality-and-test-ratchets.md). - -## Audit and provenance - -The public census contains anonymous module IDs. The source-specific graph, -line locations, read-only source receipt, consumer census, and requirement -crosswalk are delivered separately as a private local audit packet. They are -excluded from this repository; public Batten documents carry their own identities -and no dependency on the reference application. - -Prior-art research remains in `00-discover/research/`. It informs direction; -the current owner rulings and PRD govern scope. The installed HELIX plugin owns -the methodology catalog; `.helix.yml` scopes artifacts to `docs/helix/`. - -## Work and review - -Work items are project-scoped ddx beads; the installed CLI keeps its canonical -store outside Git. The [review export](01-frame/work-items.jsonl) contains the -owner review gate, original scope epics and the composition/hosting work items, -all with execution authorization off. Feature scope is recorded without an implementation sequence; dependent -implementation work requires the owner review. -The current owner instruction authorizes the composition/hosting specification -packet and tracking. Migration remains separate. Before source work, review the -contracts and dependency proofs, establish the real quality scaffold, then build -the assessor, host binding and UX slice. No existing open policy is silently settled. - -## Platform assets - -[CONTRACT-010](02-design/contracts/CONTRACT-010-platform-assets.md) and -[ADR-012](02-design/adr/ADR-012-generic-platform-assets.md) define a generic optional -platform wrapper for app-managed native packages and externally managed resource -contracts. Databricks bundle syntax and Unity Catalog bindings stay in the provider. -Deployment planning/apply is separate from runtime startup; current contract, -grant and output readiness checks gate use. Persistent assets survive shutdown. -[Verification allocation](03-test/test-plan.md#platform-asset-acceptance-allocation) -covers partial effects, drift, ownership and native qualification. This evolves -the specification without authorizing implementation or live applies. - -## Storage interface - -[CONTRACT-006](02-design/contracts/CONTRACT-006-object-storage.md) defines scoped -object storage, initially local filesystem and Databricks Volumes. -[ADR-010](02-design/adr/ADR-010-scoped-object-storage.md) records the optional module -boundary. The interface and value schema do not authorize runtime implementation. - -## Messaging interface - -[CONTRACT-007](02-design/contracts/CONTRACT-007-messaging.md) defines channels, -durable subscriptions, payload profiles, settlement and recovery. -[ADR-011](02-design/adr/ADR-011-postgres-first-messaging.md) selects PostgreSQL 18 -first, with explicitly qualified future broker adapters. Existing UMF schemas -define business payloads; no new UMF messaging vocabulary is selected. TP-001's -MSG allocation covers the design without claiming runtime or codec qualification. - -## Application service discovery - -[ADR-013](02-design/adr/ADR-013-platform-ontology-for-service-discovery.md) and -[CONTRACT-009](02-design/contracts/CONTRACT-009-service-discovery-and-binding.md) -define Batten's native five-type platform ontology, shared semantic identities, -permission-filtered discovery and exact host-approved service bindings. -[US-005](01-frame/user-stories/US-005-discover-and-bind-services.md) and -[verification allocation](03-test/test-plan.md#service-discovery-and-binding-allocation) -cover graph, governed table/view, API and messaging profiles. The core remains -ontology-neutral. Native registry/transport behavior requires cohort qualification. - -## Authorized local storage build - -The owner approved main integration of the evolved specifications and the local -filesystem implementation under [TD-006](02-design/technical-designs/TD-006-local-object-storage.md), -[CONTRACT-100](02-design/contracts/CONTRACT-100-storage-provider-host.md) and the -[implementation plan](04-build/implementation-plan.md). Earlier review holds -continue to apply to unrelated migration and platform implementations. - -## Automatic semantic testing - -Author intent and explicit refinements must drive complete CLI functionality and -automatically generated property-based end-to-end suites for every fully declarative -UI-and-hook composition. [FR-47](01-frame/prd.md) and the [SEM allocation](03-test/test-plan.md) -make a decisive semantic conformance result a prerequisite for platform migration. -Unsupported required meaning or missing coverage cannot pass qualification. +# Batten design documents + +Design records for the Batten application SDK. For what ships today read the +[README](../../README.md); for what is not built read the [roadmap](../../ROADMAP.md). + +- [Product vision](00-discover/product-vision.md), [PRD](01-frame/prd.md), + [concerns](01-frame/concerns.md), [feature specs](01-frame/features/) and + [user stories](01-frame/user-stories/). +- [Architecture](02-design/architecture.md), [ADRs](02-design/adr/), + [contracts](02-design/contracts/), [schemas](02-design/schemas/) and + [technical designs](02-design/technical-designs/). +- [Developer guide](guide/developer/index.md) (source of the microsite) and the + [microsite build](site/README.md). + +The contracts and the PRD describe the intended design and are broader than the +shipped packages. Some prose cites ADR-005, ADR-007, ADR-014, CONTRACT-002 and +CONTRACT-011, which were removed with the 0.1.0a3 reset; they remain in git +history. The approval desk model lives with the example at +`examples/approval-desk/model/approval.umf.json`. diff --git a/docs/helix/guide/developer/about.md b/docs/helix/guide/developer/about.md index eaed2da..2034225 100644 --- a/docs/helix/guide/developer/about.md +++ b/docs/helix/guide/developer/about.md @@ -8,9 +8,7 @@ The microsite explains Batten’s intended application model and architecture. I ## Source-backed explanations -Written guide pages translate the design into explanations for application authors and host integrators. Their source headers retain content digests for the artifacts they use. - -The builder checks those digests before generating HTML. A changed source requires the affected explanation to be reconciled and stamped again. +Written guide pages translate the design into explanations for application authors and host integrators. Each page lists the design sources it draws on, and the build fails if a cited source no longer exists. ## A standalone site @@ -18,12 +16,6 @@ A Python standard-library builder renders the guide and copies local CSS, JavaSc The architecture explorer changes an illustration of selected capabilities, hosting and execution placement. It does not assess compatibility, execute operations or deploy resources. -## Reader and browser checks - -An independent reader evaluates written pages against their tasks and cited sources. HELIX’s documentor checks source freshness, links and prose; the review stamp records the evaluated body. - -Browser verification separately checks rendered navigation, interactions and responsive layout. These checks concern the microsite and establish no SDK runtime or platform qualification. - ## Read the authoritative design Source links accompany each explanation. The design records retain exact interface proposals, requirements and unresolved integration dependencies. diff --git a/docs/helix/guide/developer/architecture.md b/docs/helix/guide/developer/architecture.md index ae20a28..5729204 100644 --- a/docs/helix/guide/developer/architecture.md +++ b/docs/helix/guide/developer/architecture.md @@ -3,9 +3,6 @@ - - - @@ -73,7 +70,7 @@ An admitted operation arrives through a route, tool or UI binding. The host reso The provider retains its native result or safe refusal. The host records the authorized outcome; an uncertain effect remains uncertain until its owner resolves it. -[Read the architecture record](https://github.com/DocumentDrivenDX/batten/blob/main/docs/helix/02-design/architecture.md) or inspect the [quality contract](https://github.com/DocumentDrivenDX/batten/blob/main/docs/helix/02-design/contracts/CONTRACT-002-boundaries-and-quality.md). +[Read the architecture record](https://github.com/DocumentDrivenDX/batten/blob/main/docs/helix/02-design/architecture.md) or inspect the quality contract. ## Test the declared behavior diff --git a/docs/helix/guide/developer/composition.md b/docs/helix/guide/developer/composition.md index d4960b4..edf136c 100644 --- a/docs/helix/guide/developer/composition.md +++ b/docs/helix/guide/developer/composition.md @@ -4,9 +4,7 @@ - - # Compose an application diff --git a/docs/helix/guide/developer/example-access-attestation.md b/docs/helix/guide/developer/example-access-attestation.md deleted file mode 100644 index 4bd470f..0000000 --- a/docs/helix/guide/developer/example-access-attestation.md +++ /dev/null @@ -1,38 +0,0 @@ - - - - - -# Access review and attestation walkthrough - -Specification walkthrough. Follow this journey as a resource owner and independent reviewer. Use fabricated data throughout. - -These steps describe the app’s required behavior. This release supplies no runnable implementation or qualified native cohort for this app. Use the linked story as the acceptance target; do not infer runtime support from its integration tags. - -## Capabilities in this journey - -tables, graphs, actions. These tags describe requested integration boundaries. - -## 1. Capture a review snapshot - -A resource owner captures a named snapshot of scoped fabricated resource grants. - -## 2. Review assignments - -An independent reviewer inspects the captured assignments and their snapshot identity. - -## 3. Record an attestation - -Attest an assignment or request removal, retaining snapshot and reviewer identity. This workflow does not automatically change native grants. - -## 4. Change a live grant - -Change native grants after capture. The decision remains bound to the old snapshot while live changes are explicitly reported. - -## Check authority and recovery - -Repeat inspection as an anonymous, foreign or revoked actor. No private result or unauthorized mutation should appear. If an operation may have taken effect, inspect its original identity and retain uncertainty until the result is known. - -## Continue exploring - -[Read the acceptance story](https://github.com/DocumentDrivenDX/batten/blob/main/docs/helix/reference-apps/access-attestation/specs/01-frame/user-stories/US-111-journey.md) or [choose another example](examples.md). diff --git a/docs/helix/guide/developer/example-approval-desk.md b/docs/helix/guide/developer/example-approval-desk.md index 12d4598..699e193 100644 --- a/docs/helix/guide/developer/example-approval-desk.md +++ b/docs/helix/guide/developer/example-approval-desk.md @@ -1,11 +1,7 @@ - - - - # Approval desk walkthrough @@ -43,4 +39,4 @@ Repeat inspection as an anonymous, foreign or revoked actor. No private result o ## Continue exploring -[Read the acceptance story](https://github.com/DocumentDrivenDX/batten/blob/main/docs/helix/reference-apps/approval-desk/specs/01-frame/user-stories/US-101-journey.md) or [choose another example](examples.md). +Read the [example app README](https://github.com/DocumentDrivenDX/batten/blob/main/examples/approval-desk/README.md). diff --git a/docs/helix/guide/developer/example-case-tracker.md b/docs/helix/guide/developer/example-case-tracker.md deleted file mode 100644 index 028e906..0000000 --- a/docs/helix/guide/developer/example-case-tracker.md +++ /dev/null @@ -1,38 +0,0 @@ - - - - - -# Case and task tracker walkthrough - -Specification walkthrough. Follow this journey as a case owner and assigned worker. Use fabricated data throughout. - -These steps describe the app’s required behavior. This release supplies no runnable implementation or qualified native cohort for this app. Use the linked story as the acceptance target; do not infer runtime support from its integration tags. - -## Capabilities in this journey - -tables, graphs, actions. These tags describe requested integration boundaries. - -## 1. Open a case - -A case owner opens a fabricated case and relates a required task to it. - -## 2. Assign the task - -Assign the work to a permitted worker and inspect both the task state and case revision. - -## 3. Try early closure - -Attempt to close the case while the required task is unfinished. The expected refusal preserves both current states. - -## 4. Complete and close - -The assigned worker completes the prerequisite. The owner closes the case and inspects its original task and decision lineage. - -## Check authority and recovery - -Repeat inspection as an anonymous, foreign or revoked actor. No private result or unauthorized mutation should appear. If an operation may have taken effect, inspect its original identity and retain uncertainty until the result is known. - -## Continue exploring - -[Read the acceptance story](https://github.com/DocumentDrivenDX/batten/blob/main/docs/helix/reference-apps/case-tracker/specs/01-frame/user-stories/US-103-journey.md) or [choose another example](examples.md). diff --git a/docs/helix/guide/developer/example-data-reconciliation.md b/docs/helix/guide/developer/example-data-reconciliation.md deleted file mode 100644 index 66035c3..0000000 --- a/docs/helix/guide/developer/example-data-reconciliation.md +++ /dev/null @@ -1,38 +0,0 @@ - - - - - -# Data reconciliation workbench walkthrough - -Specification walkthrough. Follow this journey as a data steward and reconciliation reviewer. Use fabricated data throughout. - -These steps describe the app’s required behavior. This release supplies no runnable implementation or qualified native cohort for this app. Use the linked story as the acceptance target; do not infer runtime support from its integration tags. - -## Capabilities in this journey - -tables, actions, jobs. These tags describe requested integration boundaries. - -## 1. Capture source snapshots - -A data steward compares two bounded fabricated snapshots containing a conflicting field. - -## 2. Inspect the difference - -Review the discrepancy and its original source lineage before proposing a resolution. - -## 3. Approve and apply - -A reconciliation reviewer approves the resolution and inspects its applied result. - -## 4. Change a source before apply - -Change one source after comparison. Applying the old repair must refuse stale inputs and preserve the newer source value. - -## Check authority and recovery - -Repeat inspection as an anonymous, foreign or revoked actor. No private result or unauthorized mutation should appear. If an operation may have taken effect, inspect its original identity and retain uncertainty until the result is known. - -## Continue exploring - -[Read the acceptance story](https://github.com/DocumentDrivenDX/batten/blob/main/docs/helix/reference-apps/data-reconciliation/specs/01-frame/user-stories/US-109-journey.md) or [choose another example](examples.md). diff --git a/docs/helix/guide/developer/example-document-review.md b/docs/helix/guide/developer/example-document-review.md deleted file mode 100644 index 05d4041..0000000 --- a/docs/helix/guide/developer/example-document-review.md +++ /dev/null @@ -1,38 +0,0 @@ - - - - - -# Assisted document review walkthrough - -Specification walkthrough. Follow this journey as a reviewer and final decision owner. Use fabricated data throughout. - -These steps describe the app’s required behavior. This release supplies no runnable implementation or qualified native cohort for this app. Use the linked story as the acceptance target; do not infer runtime support from its integration tags. - -## Capabilities in this journey - -tables, storage, agents, models, actions. These tags describe requested integration boundaries. - -## 1. Provide a document - -An authorized author uploads a fabricated document and requests bounded extraction. - -## 2. Inspect the suggestions - -A reviewer checks extracted facts against the original document and inspects provenance. - -## 3. Correct and accept - -Correct suggestions and accept the reviewed result. Accepted facts must retain document lineage and the human decision. - -## 4. Challenge unsupported output - -Introduce an unsupported assertion or unavailable model response. Unsupported suggestions remain unaccepted, and diagnostics disclose no private prompt or credentials. - -## Check authority and recovery - -Repeat inspection as an anonymous, foreign or revoked actor. No private result or unauthorized mutation should appear. If an operation may have taken effect, inspect its original identity and retain uncertainty until the result is known. - -## Continue exploring - -[Read the acceptance story](https://github.com/DocumentDrivenDX/batten/blob/main/docs/helix/reference-apps/document-review/specs/01-frame/user-stories/US-105-journey.md) or [choose another example](examples.md). diff --git a/docs/helix/guide/developer/example-entity-directory.md b/docs/helix/guide/developer/example-entity-directory.md deleted file mode 100644 index 98053e4..0000000 --- a/docs/helix/guide/developer/example-entity-directory.md +++ /dev/null @@ -1,42 +0,0 @@ - - - - - -# Entity and relationship directory walkthrough - -Specification walkthrough. Follow this journey as a directory steward and scoped analyst. Use fabricated data throughout. - -These steps describe the app’s required behavior. This release supplies no runnable implementation or qualified native cohort for this app. Use the linked story as the acceptance target; do not infer runtime support from its integration tags. - -## Capabilities in this journey - -graphs, actions. These tags describe requested integration boundaries. - -## 1. Register an entity - -An authorized maintainer registers a fabricated entity with its original model identity. - -## 2. Create a relationship - -Link a related entity through an approved action. - -## 3. Traverse the permitted graph - -Inspect authorized attributes and relationships as a reader with a narrower view. - -## 4. Update permitted attributes - -As an authorized maintainer, update approved attributes through a declared action. Inspect the current result and its original model identity. - -## 5. Check a hidden path - -Include a path through a separate hidden entity. Traversal must disclose no hidden endpoint, property or count. - -## Check authority and recovery - -Repeat inspection as an anonymous, foreign or revoked actor. No private result or unauthorized mutation should appear. If an operation may have taken effect, inspect its original identity and retain uncertainty until the result is known. - -## Continue exploring - -[Read the acceptance story](https://github.com/DocumentDrivenDX/batten/blob/main/docs/helix/reference-apps/entity-directory/specs/01-frame/user-stories/US-106-journey.md) or [choose another example](examples.md). diff --git a/docs/helix/guide/developer/example-evidence-library.md b/docs/helix/guide/developer/example-evidence-library.md deleted file mode 100644 index eb61feb..0000000 --- a/docs/helix/guide/developer/example-evidence-library.md +++ /dev/null @@ -1,38 +0,0 @@ - - - - - -# Evidence and attachment library walkthrough - -Specification walkthrough. Follow this journey as a contributor and permitted reader. Use fabricated data throughout. - -These steps describe the app’s required behavior. This release supplies no runnable implementation or qualified native cohort for this app. Use the linked story as the acceptance target; do not infer runtime support from its integration tags. - -## Capabilities in this journey - -tables, storage, actions. These tags describe requested integration boundaries. - -## 1. Start an upload - -Choose fabricated evidence and retain its original upload identity. - -## 2. Verify the bytes - -Publish the object and verify its bytes before confirming the associated record metadata. - -## 3. Link the immutable reference - -Attach the verified immutable object reference to the business record, then retrieve it with current authority. - -## 4. Interrupt at the boundary - -Interrupt after object publication but before metadata confirmation. Reconcile the original outcome while preserving published bytes; do not blindly upload again. - -## Check authority and recovery - -Repeat inspection as an anonymous, foreign or revoked actor. No private result or unauthorized mutation should appear. If an operation may have taken effect, inspect its original identity and retain uncertainty until the result is known. - -## Continue exploring - -[Read the acceptance story](https://github.com/DocumentDrivenDX/batten/blob/main/docs/helix/reference-apps/evidence-library/specs/01-frame/user-stories/US-104-journey.md) or [choose another example](examples.md). diff --git a/docs/helix/guide/developer/example-knowledge-assistant.md b/docs/helix/guide/developer/example-knowledge-assistant.md deleted file mode 100644 index 5048432..0000000 --- a/docs/helix/guide/developer/example-knowledge-assistant.md +++ /dev/null @@ -1,38 +0,0 @@ - - - - - -# Grounded knowledge assistant walkthrough - -Specification walkthrough. Follow this journey as a knowledge consumer and content owner. Use fabricated data throughout. - -These steps describe the app’s required behavior. This release supplies no runnable implementation or qualified native cohort for this app. Use the linked story as the acceptance target; do not infer runtime support from its integration tags. - -## Capabilities in this journey - -tables, storage, agents, models, search. These tags describe requested integration boundaries. - -## 1. Ask a question - -A reader asks a question against fabricated sources with mixed visibility. - -## 2. Retrieve permitted revisions - -Retrieve only authorized sources and retain the exact source revisions used by the answer. - -## 3. Inspect answer and citations - -Read the grounded answer, its uncertainty and citations. Open a permitted citation to inspect the supporting material. - -## 4. Revoke source access - -Revoke access before reopening a citation. Citation access must refuse without revealing the hidden source content. - -## Check authority and recovery - -Repeat inspection as an anonymous, foreign or revoked actor. No private result or unauthorized mutation should appear. If an operation may have taken effect, inspect its original identity and retain uncertainty until the result is known. - -## Continue exploring - -[Read the acceptance story](https://github.com/DocumentDrivenDX/batten/blob/main/docs/helix/reference-apps/knowledge-assistant/specs/01-frame/user-stories/US-107-journey.md) or [choose another example](examples.md). diff --git a/docs/helix/guide/developer/example-model-triage.md b/docs/helix/guide/developer/example-model-triage.md deleted file mode 100644 index 213a189..0000000 --- a/docs/helix/guide/developer/example-model-triage.md +++ /dev/null @@ -1,38 +0,0 @@ - - - - - -# AI-assisted inbox triage walkthrough - -Specification walkthrough. Follow this journey as a triage analyst and automation owner. Use fabricated data throughout. - -These steps describe the app’s required behavior. This release supplies no runnable implementation or qualified native cohort for this app. Use the linked story as the acceptance target; do not infer runtime support from its integration tags. - -## Capabilities in this journey - -tables, messaging, agents, models, actions. These tags describe requested integration boundaries. - -## 1. Receive an inbox item - -Receive fabricated work with a durable message identity. - -## 2. Classify within budget - -Request model assistance within the declared budget and preserve the original item identity. - -## 3. Review the suggestion - -An authorized human reviews the suggestion and applies a disposition. Inspect both the attributable business result and the settled delivery outcome. - -## 4. Redeliver after response loss - -Redeliver the same message after losing its processing response. Observe the original business result without applying the disposition twice. - -## Check authority and recovery - -Repeat inspection as an anonymous, foreign or revoked actor. No private result or unauthorized mutation should appear. If an operation may have taken effect, inspect its original identity and retain uncertainty until the result is known. - -## Continue exploring - -[Read the acceptance story](https://github.com/DocumentDrivenDX/batten/blob/main/docs/helix/reference-apps/model-triage/specs/01-frame/user-stories/US-108-journey.md) or [choose another example](examples.md). diff --git a/docs/helix/guide/developer/example-scheduled-digest.md b/docs/helix/guide/developer/example-scheduled-digest.md deleted file mode 100644 index c582731..0000000 --- a/docs/helix/guide/developer/example-scheduled-digest.md +++ /dev/null @@ -1,38 +0,0 @@ - - - - - -# Scheduled operational digest walkthrough - -Specification walkthrough. Follow this journey as a schedule owner and authorized recipient. Use fabricated data throughout. - -These steps describe the app’s required behavior. This release supplies no runnable implementation or qualified native cohort for this app. Use the linked story as the acceptance target; do not infer runtime support from its integration tags. - -## Capabilities in this journey - -tables, jobs, storage, messaging. These tags describe requested integration boundaries. - -## 1. Define a bounded report - -A schedule owner selects permitted fabricated report rows and a schedule occurrence. - -## 2. Execute due work - -Run the due occurrence with its original identity and bounded inputs. - -## 3. Publish and inspect - -Publish the report artifact and inspect its permitted reference and delivery status. - -## 4. Compete for one occurrence - -Have workers compete for the same occurrence, then lose a response. The original run and possible delivery outcome remain observable without a second business publication. - -## Check authority and recovery - -Repeat inspection as an anonymous, foreign or revoked actor. No private result or unauthorized mutation should appear. If an operation may have taken effect, inspect its original identity and retain uncertainty until the result is known. - -## Continue exploring - -[Read the acceptance story](https://github.com/DocumentDrivenDX/batten/blob/main/docs/helix/reference-apps/scheduled-digest/specs/01-frame/user-stories/US-110-journey.md) or [choose another example](examples.md). diff --git a/docs/helix/guide/developer/example-service-handoff.md b/docs/helix/guide/developer/example-service-handoff.md deleted file mode 100644 index 376b103..0000000 --- a/docs/helix/guide/developer/example-service-handoff.md +++ /dev/null @@ -1,38 +0,0 @@ - - - - - -# Cross-application service handoff walkthrough - -Specification walkthrough. Follow this journey as a requesting user and receiving service owner. Use fabricated data throughout. - -These steps describe the app’s required behavior. This release supplies no runnable implementation or qualified native cohort for this app. Use the linked story as the acceptance target; do not infer runtime support from its integration tags. - -## Capabilities in this journey - -graphs, services, messaging, actions. These tags describe requested integration boundaries. - -## 1. Discover a permitted export - -A requesting user discovers an admitted receiving service export they may see. - -## 2. Bind the exact interface - -Resolve the exact host-approved interface and binding. Discovery alone supplies no authority. - -## 3. Submit and observe - -Submit a request and inspect receiver progress with original causal identity and receiver-scoped authority. - -## 4. Revoke the binding - -Revoke the binding or change the provider interface before invocation. Handoff must refuse without silently choosing another provider or replaying a command. - -## Check authority and recovery - -Repeat inspection as an anonymous, foreign or revoked actor. No private result or unauthorized mutation should appear. If an operation may have taken effect, inspect its original identity and retain uncertainty until the result is known. - -## Continue exploring - -[Read the acceptance story](https://github.com/DocumentDrivenDX/batten/blob/main/docs/helix/reference-apps/service-handoff/specs/01-frame/user-stories/US-112-journey.md) or [choose another example](examples.md). diff --git a/docs/helix/guide/developer/example-service-intake.md b/docs/helix/guide/developer/example-service-intake.md deleted file mode 100644 index 5c0f560..0000000 --- a/docs/helix/guide/developer/example-service-intake.md +++ /dev/null @@ -1,38 +0,0 @@ - - - - - -# Service intake and routing walkthrough - -Specification walkthrough. Follow this journey as a requester and service coordinator. Use fabricated data throughout. - -These steps describe the app’s required behavior. This release supplies no runnable implementation or qualified native cohort for this app. Use the linked story as the acceptance target; do not infer runtime support from its integration tags. - -## Capabilities in this journey - -tables, actions, messaging. These tags describe requested integration boundaries. - -## 1. Submit once - -A requester sends a fabricated service request with a stable submission identity. - -## 2. Classify and route - -A service coordinator classifies the intake and routes it to a queue they are permitted to use. - -## 3. Acknowledge assignment - -Inspect the current assignment and acknowledge it. Only permitted users should see the intake and assignment. - -## 4. Recover a lost submission - -Lose the response and inspect the original submission identity. The expected result is the original intake, without another record. - -## Check authority and recovery - -Repeat inspection as an anonymous, foreign or revoked actor. No private result or unauthorized mutation should appear. If an operation may have taken effect, inspect its original identity and retain uncertainty until the result is known. - -## Continue exploring - -[Read the acceptance story](https://github.com/DocumentDrivenDX/batten/blob/main/docs/helix/reference-apps/service-intake/specs/01-frame/user-stories/US-102-journey.md) or [choose another example](examples.md). diff --git a/docs/helix/guide/developer/examples.md b/docs/helix/guide/developer/examples.md deleted file mode 100644 index b930079..0000000 --- a/docs/helix/guide/developer/examples.md +++ /dev/null @@ -1,80 +0,0 @@ - - - -# Example app walkthroughs - -Follow a business journey through each of Batten’s twelve fabricated reference apps. Approval desk is the runnable local preview in this release; the other walkthroughs explain specified behavior and acceptance targets. They are not claims of completed native integrations. - -Each walkthrough names the business result, the boundary to challenge and the source specification. The interactive architecture explorer remains a separate illustration. - -## Approval desk - -Runnable local preview. Submit a request, inspect its revision, approve or reject, then observe the final decision. - -[Follow the approval desk walkthrough](example-approval-desk.md). - -## Service intake and routing - -Specification walkthrough. Submit an intake form, classify it, route it to a permitted queue and acknowledge assignment. - -[Follow the service intake and routing walkthrough](example-service-intake.md). - -## Case and task tracker - -Specification walkthrough. Open a case, relate a task, assign work, satisfy prerequisites and close the case. - -[Follow the case and task tracker walkthrough](example-case-tracker.md). - -## Evidence and attachment library - -Specification walkthrough. Upload fabricated evidence, verify bytes, link its immutable reference to a record and retrieve it. - -[Follow the evidence and attachment library walkthrough](example-evidence-library.md). - -## Assisted document review - -Specification walkthrough. Upload a fabricated document, request extraction, inspect provenance, correct suggestions and accept a reviewed result. - -[Follow the assisted document review walkthrough](example-document-review.md). - -## Entity and relationship directory - -Specification walkthrough. Register an entity, link a related entity, traverse authorized relationships and update approved attributes. - -[Follow the entity and relationship directory walkthrough](example-entity-directory.md). - -## Grounded knowledge assistant - -Specification walkthrough. Ask a question, retrieve authorized sources, inspect a grounded answer and open permitted citations. - -[Follow the grounded knowledge assistant walkthrough](example-knowledge-assistant.md). - -## AI-assisted inbox triage - -Specification walkthrough. Receive an inbox item, classify it within a budget, review the suggestion and apply an authorized disposition. - -[Follow the ai-assisted inbox triage walkthrough](example-model-triage.md). - -## Data reconciliation workbench - -Specification walkthrough. Compare bounded source snapshots, inspect discrepancies, approve a resolution and inspect the applied result. - -[Follow the data reconciliation workbench walkthrough](example-data-reconciliation.md). - -## Scheduled operational digest - -Specification walkthrough. Schedule a bounded report, execute a due occurrence, publish its artifact and inspect delivery status. - -[Follow the scheduled operational digest walkthrough](example-scheduled-digest.md). - -## Access review and attestation - -Specification walkthrough. Capture a scoped access snapshot, review assignments, attest or request removal and inspect the outcome. - -[Follow the access review and attestation walkthrough](example-access-attestation.md). - -## Cross-application service handoff - -Specification walkthrough. Discover a permitted service, bind its exact interface, submit a request and observe receiving progress. - -[Follow the cross-application service handoff walkthrough](example-service-handoff.md). diff --git a/docs/helix/guide/developer/index.md b/docs/helix/guide/developer/index.md index dd2d23a..9fb7437 100644 --- a/docs/helix/guide/developer/index.md +++ b/docs/helix/guide/developer/index.md @@ -3,11 +3,8 @@ - - - @@ -54,8 +51,6 @@ A provider must satisfy the required interface and exact compatibility checks. A ## Explore the design -Enterprise reference apps have independent HELIX specification scopes and shared conformance obligations. The initial UI path is a TypeScript app. Inventory validation checks the specs; complete app support requires actual client, host and provider evidence. - The local runtime preview delivers an approval desk and a visual application registry, with native UMF/Weft persistence on PostgreSQL 18. Separate wheels package the contracts, runtime, table port, native adapter, ASGI transport, local host and app. Qualification is bounded to the recorded cohort and local development identities; the complete fleet remains a design goal. Optional local object storage has its own release. The interactive explorer illustrates the broader contracts and makes no service calls. [Get the runtime preview](https://github.com/DocumentDrivenDX/batten/releases/tag/runtime-v0.1.0a2) or [read the run instructions](https://github.com/DocumentDrivenDX/batten/blob/main/examples/approval-desk/README.md). @@ -72,4 +67,4 @@ The same properties must qualify a candidate platform before migration. Results ## Follow an example -[Walk through the example apps](examples.md), from the local approval desk to the specification journeys for intake, evidence, agents, graphs and service handoff. +[Walk through the approval desk](example-approval-desk.md), the example app in this release. diff --git a/docs/helix/guide/developer/integrations.md b/docs/helix/guide/developer/integrations.md index 724c827..340e6da 100644 --- a/docs/helix/guide/developer/integrations.md +++ b/docs/helix/guide/developer/integrations.md @@ -12,7 +12,6 @@ - diff --git a/docs/helix/reference-apps/README.md b/docs/helix/reference-apps/README.md deleted file mode 100644 index aa1dbd8..0000000 --- a/docs/helix/reference-apps/README.md +++ /dev/null @@ -1,42 +0,0 @@ -# Enterprise micro-app library - -These are fabricated application specifications, fixtures and qualification targets. -They are not twelve runnable apps. Batten currently supplies local object storage; -complete host, ORM, client and provider integration is tracked separately. - -Each app has its own `.helix.yml` binding `specs/`, app instructions, PRD, user -story, test plan and fabricated data. Open an app directory to target it with the -installed HELIX skill and follow the shared [Batten app workflow](../04-build/batten-app-workflow.md). -This specializes HELIX without vendoring its catalog or installing another skill. - -All initial interactive apps are TypeScript apps using public Batten operations; -ux-builder remains available for qualified design/tooling integration. Declarative -UI generation is a separate longer-term capability. An app may omit UI only after -its own scope and required evidence are revised explicitly. - -| App | User outcome | Integration tags | -| --- | --- | --- | -| [Approval desk](approval-desk/specs/01-frame/prd.md) | Submit a request, inspect its revision, approve or reject, then observe the final decision. | tables,actions | -| [Service intake and routing](service-intake/specs/01-frame/prd.md) | Submit an intake form, classify it, route it to a permitted queue and acknowledge assignment. | tables,actions,messaging | -| [Case and task tracker](case-tracker/specs/01-frame/prd.md) | Open a case, relate a task, assign work, satisfy prerequisites and close the case. | tables,graphs,actions | -| [Evidence and attachment library](evidence-library/specs/01-frame/prd.md) | Upload fabricated evidence, verify bytes, link its immutable reference to a record and retrieve it. | tables,storage,actions | -| [Assisted document review](document-review/specs/01-frame/prd.md) | Upload a fabricated document, request extraction, inspect provenance, correct suggestions and accept a reviewed result. | tables,storage,agents,models,actions | -| [Entity and relationship directory](entity-directory/specs/01-frame/prd.md) | Register an entity, link a related entity, traverse authorized relationships and update approved attributes. | graphs,actions | -| [Grounded knowledge assistant](knowledge-assistant/specs/01-frame/prd.md) | Ask a question, retrieve authorized sources, inspect a grounded answer and open permitted citations. | tables,storage,agents,models,search | -| [AI-assisted inbox triage](model-triage/specs/01-frame/prd.md) | Receive an inbox item, classify it within a budget, review the suggestion and apply an authorized disposition. | tables,messaging,agents,models,actions | -| [Data reconciliation workbench](data-reconciliation/specs/01-frame/prd.md) | Compare bounded source snapshots, inspect discrepancies, approve a resolution and inspect the applied result. | tables,actions,jobs | -| [Scheduled operational digest](scheduled-digest/specs/01-frame/prd.md) | Schedule a bounded report, execute a due occurrence, publish its artifact and inspect delivery status. | tables,jobs,storage,messaging | -| [Access review and attestation](access-attestation/specs/01-frame/prd.md) | Capture a scoped access snapshot, review assignments, attest or request removal and inspect the outcome. | tables,graphs,actions | -| [Cross-application service handoff](service-handoff/specs/01-frame/prd.md) | Discover a permitted service, bind its exact interface, submit a request and observe receiving progress. | graphs,services,messaging,actions | - -Shared obligations cover authority, attribution, commands, lifecycle, limits, -surface parity and observability. Each story adds a distinct business invariant. -Do not build new ORMs or engines to satisfy an example: integrate UMF/PostgreSQL, -UMF/Truss and the other existing platform projects through qualified public APIs. - -Run `python scripts/check_micro_apps.py` from the SDK root for inventory validation. -`--require-execution` deliberately refuses until a trusted complete-app runner and -its evidence contract are qualified. Component-only receipts cannot make it green. -See [scope assessment](../01-frame/feasibility-study.md), -[corpus contract](../02-design/contracts/CONTRACT-011-micro-app-conformance.md), and -[integration queue](../04-build/integration-gaps.md). diff --git a/docs/helix/reference-apps/access-attestation/.helix.yml b/docs/helix/reference-apps/access-attestation/.helix.yml deleted file mode 100644 index 3b26d19..0000000 --- a/docs/helix/reference-apps/access-attestation/.helix.yml +++ /dev/null @@ -1,12 +0,0 @@ -{ - "flows": [ - { - "id": "helix", - "root": "specs/" - } - ], - "x-batten-app": { - "id": "MA-011", - "workflow": "../../04-build/batten-app-workflow.md" - } -} diff --git a/docs/helix/reference-apps/access-attestation/AGENTS.md b/docs/helix/reference-apps/access-attestation/AGENTS.md deleted file mode 100644 index a07c63e..0000000 --- a/docs/helix/reference-apps/access-attestation/AGENTS.md +++ /dev/null @@ -1,19 +0,0 @@ -# Working on Access review and attestation - -Read this directory's `.helix.yml` and engage the installed HELIX skill. This is -application MA-011; governed artifacts belong only in `specs/`. Start with -`specs/01-frame/prd.md`, then the story and test plan. Follow -[the Batten app workflow](../../04-build/batten-app-workflow.md), using templates, -prompts and metadata from the installed HELIX catalog. Do not vendor the catalog. - -Reference app rules are fabricated conformance defaults, not real business policy. -UMF owns models/actions and typed persistence; PostgreSQL 18 and Truss own native -storage/execution. UI is application-authored TypeScript through the public host -client, with room for ux-builder. No direct database/provider access in the UI. -Read applicable SDK contracts through explicit file paths; local artifact IDs -resolve inside this app scope. App specs do not authorize SDK or upstream edits. - -Build only after a scoped app implementation instruction and qualified integration -closure. No credentials, production data, migrations, applies, commits or pushes -without their applicable authorization. Never replace a required failing positive -case with a skip, mock result or changed expected outcome. diff --git a/docs/helix/reference-apps/access-attestation/fixtures.json b/docs/helix/reference-apps/access-attestation/fixtures.json deleted file mode 100644 index 1d6cf84..0000000 --- a/docs/helix/reference-apps/access-attestation/fixtures.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "application": "MA-011", - "record": { - "id": "fabricated-access-attestation-record", - "owner": "actor-a", - "state": "open" - }, - "actors": { - "permitted": "actor-a", - "foreign": "actor-b", - "independent_reviewer": "actor-c" - } -} diff --git a/docs/helix/reference-apps/access-attestation/specs/01-frame/features/FEAT-111-business-journey.md b/docs/helix/reference-apps/access-attestation/specs/01-frame/features/FEAT-111-business-journey.md deleted file mode 100644 index 1c8a3fb..0000000 --- a/docs/helix/reference-apps/access-attestation/specs/01-frame/features/FEAT-111-business-journey.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -ddx: - id: FEAT-111 - type: feature-specification - activity: frame - authoring: - home: repo - links: - - id: access-attestation.prd - kind: derived_from ---- - -# FEAT-111: Governed business journey - -**Feature ID**: FEAT-111 -**Priority**: P0 -**Owner**: Erik LaBianca -**Covered PRD Subsystem(s)**: Governed business journey -**Covered PRD Requirements**: FR-1, FR-2, FR-3, FR-4 -**Cross-Subsystem Rationale**: None; one app-specific journey. - -## Overview - -The app must complete its PRD's business journey through authorized platform -operations and preserve its independently stated business invariant. - -## Ideal Future State - -The actor can rely on the final result or safely reconcile original uncertain -work across supported surfaces, without rebuilding integration or policy. - -## Problem Statement - -Passing component calls do not prove this app's domain outcome. The PRD defines -its users, concepts and rule; the story owns its observable acceptance criteria. - -## Requirements - -- FR-1 must complete the specific app journey in the PRD. -- FR-2 must enforce the PRD's distinct business invariant. -- FR-3 must preserve current permission and actual/uncertain effects on failure. -- FR-4 must preserve meaning and attribution across qualified surfaces/cohorts. - -### Non-Functional Requirements - -No private provider access or client-derived authority. Bounded native work and -safe diagnostics follow SDK CONTRACT-011; Erik supplies production workload and -latency/cost budgets. No numeric operating target is assumed. - -## User Stories - -[US-111](../user-stories/US-111-journey.md) owns the acceptance criteria. - -## Edge Cases and Error Handling - -Foreign/revoked actors, changed inputs, interrupted commands and unavailable -providers retain the story's explicit safe outcomes. No silent scripted replacement. - -## Constraints and Assumptions - -Fabricated business defaults, native UMF data/actions, PostgreSQL 18/Truss when -required, and authored TypeScript UI. Exact platform subset needs qualification. - -## Dependencies - -Local PRD FR-1–4 and SDK CONTRACT-003/004/005/011 through explicit file references -in the app test plan. The app has no authority to modify those shared contracts. - -## Out of Scope - -New platform engines, privileged UI-side data access, production policy or deployment. diff --git a/docs/helix/reference-apps/access-attestation/specs/01-frame/prd.md b/docs/helix/reference-apps/access-attestation/specs/01-frame/prd.md deleted file mode 100644 index 6927012..0000000 --- a/docs/helix/reference-apps/access-attestation/specs/01-frame/prd.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -ddx: - id: access-attestation.prd - type: prd - activity: frame - authoring: - home: repo ---- - -# Access review and attestation - -## Summary - -MA-011 is a fabricated enterprise reference app for a resource owner and independent reviewer. It exercises -capture a scoped access snapshot, review assignments, attest or request removal and inspect the outcome. Its purpose is to qualify a useful business journey -through Batten's platform integrations, rather than introduce a new engine. - -## Problem and Goals - -### Problem - -Users need an attributable business result across data, permission and failure -boundaries. A successful component call alone cannot establish this workflow. - -### Goals - -- Complete the stated journey while preserving current access and original identity. -- Detect the app-specific business invariant: Attestation records a decision about an exact snapshot; it never silently changes native grants. -- Reproduce denied, stale, duplicate, cancelled and uncertain outcomes independently - of the host implementation. - -### Non-Goals - -No identity-provider provisioning or automatic native grant change. - -## Users and Scope - -The resource owner and independent reviewer roles are assumed reference roles selected for this corpus, not -validated research personas. Erik owns real user validation and policy changes. -Business concepts: ReviewCampaign, AccessSnapshot, Attestation. All records and actors are fabricated. - -## Requirements - -### Must Have (P0) - -- Complete the journey and enforce its app-specific business invariant. -- Apply shared authority, lifecycle and evidence obligations without disclosure. -- Qualify required native integrations and real UI outcomes before a support claim. - -## Functional Requirements - -### Subsystem: Governed business journey - -Feature owner: FEAT-111. - -- **FR-1** — Capture a scoped access snapshot, review assignments, attest or request removal and inspect the outcome. -- **FR-2** — Attestation records a decision about an exact snapshot; it never silently changes native grants. -- **FR-3** — Permission loss, stale inputs and interrupted work must preserve - authorized visibility, actual effects and the original uncertain outcome. -- **FR-4** — Supported surfaces and candidate cohorts must preserve the same - business semantics with attributable decisions and safe diagnostics. - -## Acceptance Test Sketches - -| Requirement | Scenario | Input | Expected Output | -| --- | --- | --- | --- | -| FR-1 | Main journey | fabricated resource grants and a named review snapshot | signed-in reviewer decision retains snapshot and actor identity | -| FR-2 | Business boundary | native grants change after snapshot capture | decision remains bound to the old snapshot and live changes are explicitly reported | -| FR-3 | Foreign or revoked actor | Original fixture with changed authority | Safe refusal; no hidden data or new business effect | -| FR-4 | Alternate client/cohort | Same app and business inputs | Same authorized outcome or explicit unsupported refusal | - -## Technical Context - -Integration requirements: tables,graphs,actions. These are corpus tags, not installable -module names or a claim that every adapter exists. Use UMF typed access with -PostgreSQL 18 for tables and Truss for graphs. Initial UI is a TypeScript browser -app under SDK ADR-015 and CONTRACT-005. No frontend framework is selected here. -Platform contracts are explicit dependencies in the test plan; original native -model/action packages require exact source and cohort qualification before build. - -## Constraints, Assumptions, Dependencies - -- Shared obligations in SDK CONTRACT-011 apply in full. -- Fixture states and role separation are conformance defaults, not production rules. -- Same local PostgreSQL instance does not imply one transaction across all services. -- Native authoring, host/client and required provider integrations precede app execution. - -## Risks - -| Risk | Probability | Impact | Mitigation | -| --- | --- | --- | --- | -| Fixture mistaken for a running app | Unmeasured | False support claim | Separate inventory from full execution qualification | -| UI or hook bypasses policy | Unmeasured | Unauthorized outcome | Public host boundary and server-side current authority checks | -| Backend changes business meaning | Unmeasured | Invalid result | Independent expectations and candidate-cohort replay | - -## Open Questions - -Erik supplies workload, latency/cost limits, real retention rules and production -policy. Those values block production qualification, not fabricated specification. - -## Success Criteria - -The governing story's positive and negative criteria pass through exact installed -native integrations and real client/host paths, with safe required telemetry. -The corpus inventory alone establishes none of those execution claims. diff --git a/docs/helix/reference-apps/access-attestation/specs/01-frame/user-stories/US-111-journey.md b/docs/helix/reference-apps/access-attestation/specs/01-frame/user-stories/US-111-journey.md deleted file mode 100644 index 15a4efd..0000000 --- a/docs/helix/reference-apps/access-attestation/specs/01-frame/user-stories/US-111-journey.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -ddx: - id: US-111 - type: user-stories - activity: frame - authoring: - home: repo - links: - - id: access-attestation.prd - kind: derived_from ---- - -# US-111: Complete the access review and attestation journey - -**Feature**: FEAT-111 — Governed business journey -**Feature Requirements**: Reference-app business journey. -**PRD Requirements**: FR-1, FR-2, FR-3, FR-4. -**Priority**: P0. - -## Story - -**As a** resource owner and independent reviewer -**I want** to complete the governed business journey -**So that** I can rely on its authorized result and recover safely after interruption. - -## Context - -This is application MA-011. Business rules below are explicit fabricated defaults. -They remain independent of whichever platform implementation is being qualified. - -## Walkthrough - -1. The actor opens permitted work and inspects its current state and revision. -2. The actor follows the journey: Capture a scoped access snapshot, review assignments, attest or request removal and inspect the outcome. -3. The host checks current authority and original operation identity. -4. The actor observes the result, or reconciles the original uncertain attempt. - -## Acceptance Criteria - -- [ ] **US-111-AC1** — Given fabricated resource grants and a named review snapshot, when the actor performs the journey, then signed-in reviewer decision retains snapshot and actor identity. -- [ ] **US-111-AC2** — Given the app's business invariant, when actors native grants change after snapshot capture, then decision remains bound to the old snapshot and live changes are explicitly reported. -- [ ] **US-111-AC3** — Given a foreign, anonymous or revoked actor, when they attempt the same operation or continuation, then no private result or unauthorized mutation is disclosed. -- [ ] **US-111-AC4** — Given response loss or cancellation, when the actor inspects original work, then actual effects and uncertainty remain attributable without a fresh blind command. -- [ ] **US-111-AC5** — Given the same business inputs on another supported surface or cohort, when the journey runs, then meaning and authority are preserved; unsupported required behavior refuses explicitly. - -## Edge Cases - -- Empty permitted data returns an authorized empty state, not hidden counts. -- Dependency failure exposes a safe outcome; a scripted replacement is not selected. -- Query and inspection do not mutate business records or retry uncertain commands. - -## Test Scenarios - -| Scenario | AC ID | Input / State | Action | Expected Result | -| --- | --- | --- | --- | --- | -| Main journey | US-111-AC1 | fabricated resource grants and a named review snapshot | review and attest the selected assignment | signed-in reviewer decision retains snapshot and actor identity | -| Business invariant | US-111-AC2 | Same original fixture | native grants change after snapshot capture | decision remains bound to the old snapshot and live changes are explicitly reported | -| Current authority | US-111-AC3 | Fixture foreign actor | Attempt and continue work | Safe denial without disclosure | -| Lost response | US-111-AC4 | Original possibly effective attempt | Observe original identity | Actual or uncertain outcome, no blind replay | -| Cohort parity | US-111-AC5 | Same semantic inputs | Exercise supported client/host | Same meaning or explicit refusal | - -## Dependencies - -Local PRD FR-1–4; SDK CONTRACT-003/004/005/011. Native platform model/action -contracts must be selected before executable app construction. Corpus tags: -tables,graphs,actions. Their presence requests support and grants no authority. - -## Out of Scope - -No identity-provider provisioning or automatic native grant change. Full platform implementation is not authorized by this app story. diff --git a/docs/helix/reference-apps/access-attestation/specs/03-test/test-plan.md b/docs/helix/reference-apps/access-attestation/specs/03-test/test-plan.md deleted file mode 100644 index cc8ee86..0000000 --- a/docs/helix/reference-apps/access-attestation/specs/03-test/test-plan.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -ddx: - id: TP-111 - type: test-plan - activity: test - authoring: - home: repo - links: - - id: US-111 - kind: informed_by ---- - -# Access review and attestation: conformance allocation - -## Strategy - -**Goal**: Qualify MA-011's full authorized journey and distinct business invariant. -**Out of scope**: No identity-provider provisioning or automatic native grant change. -Use shared runner obligations from SDK CONTRACT-011 and preserve the independent -story expectations. No app result may be inferred from inventory validation. - -## Framework Selection & Cost - -| Layer | Framework | Justification | CI Time Impact | Maintenance Burden | -| --- | --- | --- | --- | --- | -| Inventory | Existing stdlib corpus checker | Exact scope/fixture integrity without app loading | Measured by shared command; no estimate supplied | Shared | -| Native actions | Qualified UMF/existing provider conformance | Reuse native ORM/graph semantics rather than duplicate them | Unknown; Erik owns budget | One shared runner, app data | -| UI journey | Real TypeScript client/browser harness | Authored UI requires independent observable journeys | Unknown; harness selection precedes app build | App acceptance scenarios | -| Model behavior where requested | Deterministic scripted API plus separate live API cut | Reproducible rules and actual integration prove different properties | Unknown | Fixture/model cohort scoped | - -## Critical Paths (P0) - -1. Story FR-1/2: signed-in reviewer decision retains snapshot and actor identity; invariant: Attestation records a decision about an exact snapshot; it never silently changes native grants. -2. Story FR-3: unauthorized, stale, duplicate and uncertain work never loses its - actual authority or outcome boundary. -3. Story FR-4: exact supported client/cohort preserves business meaning and safe - diagnostics, including current identity on continuation. - -## Acceptance Criteria Layer Allocation - -| AC class / source | Story Test Plan | Primary Layer | Why this layer | -| --- | --- | --- | --- | -| US-111 main business and invariant classes | App story test plan at build handoff | Public client/host/native provider journey | Only full path proves business result | -| US-111 permission/recovery classes | Same app story test plan | Native integration | Current authority and durable effects cross boundaries | -| US-111 surface/candidate classes | Same app story test plan | Real browser plus separate CLI parity observation | TypeScript and server behavior require distinct observations | - -The build handoff must author the per-criterion story test plan and native model/ -technical design from installed HELIX templates before executable app code. -No preselected test function or framework is fabricated before that contract exists. - -## Secondary Paths (P1-P2) - -Optional UI polish cannot weaken required denial, uncertainty or accessibility -behavior. There is no optional escape from an active P0 criterion. - -## Test Data Strategy - -Use `../../fixtures.json` and the story's independent Given/When/Then examples. -Create isolated native namespaces with explicit PostgreSQL 18/Truss bindings and -scoped local identity. No production snapshot, credentials or inferred grants. -Every generated/native input retains its app/model/refinement identity. - -## Known Gaps - -Complete app execution requires qualified host/client, native model artifacts, -selected integrations and a trusted evidence runner. These are qualification -blockers, not accepted runtime risk or passing skips. SDK component storage -checks qualify only their own boundary. TypeScript UI is authored, not generated -from a declarative UI model. UI harness selection belongs to the app build design. - -## Build Commands - -From the SDK repository root: - -```sh -python scripts/check_micro_apps.py -python scripts/check_micro_apps.py --require-execution -``` - -The first command verifies inventory only; the second must refuse absent complete -app execution evidence. SDK platform dependencies are explicit file references: -`../../../../02-design/contracts/CONTRACT-003-composition.md`, -`../../../../02-design/contracts/CONTRACT-004-host-profiles.md`, -`../../../../02-design/contracts/CONTRACT-005-ux-builder-binding.md`, and -`../../../../02-design/contracts/CONTRACT-011-micro-app-conformance.md`. - -**Blocking gate**: Every active story criterion and shared obligation must have -trusted passing evidence for exact inputs before this app is called qualified. -No test-function ceiling increase; parameterize cases in shared machinery. - -## Diagnostic Test Strategy - -Exercise actual safe host audit and required telemetry across client, host and -providers, including a real receiver, refusal, retries, capture loss and shutdown. -A mocked exporter or parsed JSON is not receiver qualification. Erik supplies -workload and diagnostic overhead budgets before production qualification. diff --git a/docs/helix/reference-apps/approval-desk/.helix.yml b/docs/helix/reference-apps/approval-desk/.helix.yml deleted file mode 100644 index 12b0d71..0000000 --- a/docs/helix/reference-apps/approval-desk/.helix.yml +++ /dev/null @@ -1,12 +0,0 @@ -{ - "flows": [ - { - "id": "helix", - "root": "specs/" - } - ], - "x-batten-app": { - "id": "MA-001", - "workflow": "../../04-build/batten-app-workflow.md" - } -} diff --git a/docs/helix/reference-apps/approval-desk/AGENTS.md b/docs/helix/reference-apps/approval-desk/AGENTS.md deleted file mode 100644 index 8a619e6..0000000 --- a/docs/helix/reference-apps/approval-desk/AGENTS.md +++ /dev/null @@ -1,19 +0,0 @@ -# Working on Approval desk - -Read this directory's `.helix.yml` and engage the installed HELIX skill. This is -application MA-001; governed artifacts belong only in `specs/`. Start with -`specs/01-frame/prd.md`, then the story and test plan. Follow -[the Batten app workflow](../../04-build/batten-app-workflow.md), using templates, -prompts and metadata from the installed HELIX catalog. Do not vendor the catalog. - -Reference app rules are fabricated conformance defaults, not real business policy. -UMF owns models/actions and typed persistence; PostgreSQL 18 and Truss own native -storage/execution. UI is application-authored TypeScript through the public host -client, with room for ux-builder. No direct database/provider access in the UI. -Read applicable SDK contracts through explicit file paths; local artifact IDs -resolve inside this app scope. App specs do not authorize SDK or upstream edits. - -Build only after a scoped app implementation instruction and qualified integration -closure. No credentials, production data, migrations, applies, commits or pushes -without their applicable authorization. Never replace a required failing positive -case with a skip, mock result or changed expected outcome. diff --git a/docs/helix/reference-apps/approval-desk/fixtures.json b/docs/helix/reference-apps/approval-desk/fixtures.json deleted file mode 100644 index 7ee8cfb..0000000 --- a/docs/helix/reference-apps/approval-desk/fixtures.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "application": "MA-001", - "record": { - "id": "fabricated-approval-desk-record", - "owner": "actor-a", - "state": "draft" - }, - "actors": { - "permitted": "actor-a", - "foreign": "actor-b", - "independent_reviewer": "actor-c" - } -} diff --git a/docs/helix/reference-apps/approval-desk/specs/01-frame/features/FEAT-101-business-journey.md b/docs/helix/reference-apps/approval-desk/specs/01-frame/features/FEAT-101-business-journey.md deleted file mode 100644 index 3f0dff2..0000000 --- a/docs/helix/reference-apps/approval-desk/specs/01-frame/features/FEAT-101-business-journey.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -ddx: - id: FEAT-101 - type: feature-specification - activity: frame - authoring: - home: repo - links: - - id: approval-desk.prd - kind: derived_from ---- - -# FEAT-101: Governed business journey - -**Feature ID**: FEAT-101 -**Priority**: P0 -**Owner**: Erik LaBianca -**Covered PRD Subsystem(s)**: Governed business journey -**Covered PRD Requirements**: FR-1, FR-2, FR-3, FR-4 -**Cross-Subsystem Rationale**: None; one app-specific journey. - -## Overview - -The app must complete its PRD's business journey through authorized platform -operations and preserve its independently stated business invariant. - -## Ideal Future State - -The actor can rely on the final result or safely reconcile original uncertain -work across supported surfaces, without rebuilding integration or policy. - -## Problem Statement - -Passing component calls do not prove this app's domain outcome. The PRD defines -its users, concepts and rule; the story owns its observable acceptance criteria. - -## Requirements - -- FR-1 must complete the specific app journey in the PRD. -- FR-2 must enforce the PRD's distinct business invariant. -- FR-3 must preserve current permission and actual/uncertain effects on failure. -- FR-4 must preserve meaning and attribution across qualified surfaces/cohorts. - -### Non-Functional Requirements - -No private provider access or client-derived authority. Bounded native work and -safe diagnostics follow SDK CONTRACT-011; Erik supplies production workload and -latency/cost budgets. No numeric operating target is assumed. - -## User Stories - -[US-101](../user-stories/US-101-journey.md) owns the acceptance criteria. - -## Edge Cases and Error Handling - -Foreign/revoked actors, changed inputs, interrupted commands and unavailable -providers retain the story's explicit safe outcomes. No silent scripted replacement. - -## Constraints and Assumptions - -Fabricated business defaults, native UMF data/actions, PostgreSQL 18/Truss when -required, and authored TypeScript UI. Exact platform subset needs qualification. - -## Dependencies - -Local PRD FR-1–4 and SDK CONTRACT-003/004/005/011 through explicit file references -in the app test plan. The app has no authority to modify those shared contracts. - -## Out of Scope - -New platform engines, privileged UI-side data access, production policy or deployment. - -## Local entry point - -**FR-5**: Open the app from the local runtime registry, using a card with its -title, description and packaged visual thumbnail. The Batten brand returns to -the registry. App-specific API and session paths keep app bindings independent. diff --git a/docs/helix/reference-apps/approval-desk/specs/01-frame/prd.md b/docs/helix/reference-apps/approval-desk/specs/01-frame/prd.md deleted file mode 100644 index d24a5dc..0000000 --- a/docs/helix/reference-apps/approval-desk/specs/01-frame/prd.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -ddx: - id: approval-desk.prd - type: prd - activity: frame - authoring: - home: repo ---- - -# Approval desk - -## Summary - -MA-001 is a fabricated enterprise reference app for a requester and independent approver. It exercises -submit a request, inspect its revision, approve or reject, then observe the final decision. Its purpose is to qualify a useful business journey -through Batten's platform integrations, rather than introduce a new engine. - -## Problem and Goals - -### Problem - -Users need an attributable business result across data, permission and failure -boundaries. A successful component call alone cannot establish this workflow. - -### Goals - -- Complete the stated journey while preserving current access and original identity. -- Detect the app-specific business invariant: A requester cannot approve their own request; a stale decision cannot overwrite a later revision. -- Reproduce denied, stale, duplicate, cancelled and uncertain outcomes independently - of the host implementation. - -### Non-Goals - -No money movement or authoritative accounting ledger. - -## Users and Scope - -The requester and independent approver roles are assumed reference roles selected for this corpus, not -validated research personas. Erik owns real user validation and policy changes. -Business concepts: Request, Decision. All records and actors are fabricated. - -## Requirements - -### Must Have (P0) - -- Complete the journey and enforce its app-specific business invariant. -- Apply shared authority, lifecycle and evidence obligations without disclosure. -- Qualify required native integrations and real UI outcomes before a support claim. - -## Functional Requirements - -### Subsystem: Governed business journey - -Feature owner: FEAT-101. - -- **FR-1** — Submit a request, inspect its revision, approve or reject, then observe the final decision. -- **FR-2** — A requester cannot approve their own request; a stale decision cannot overwrite a later revision. -- **FR-3** — Permission loss, stale inputs and interrupted work must preserve - authorized visibility, actual effects and the original uncertain outcome. -- **FR-4** — Supported surfaces and candidate cohorts must preserve the same - business semantics with attributable decisions and safe diagnostics. - -## Acceptance Test Sketches - -| Requirement | Scenario | Input | Expected Output | -| --- | --- | --- | --- | -| FR-1 | Main journey | pending request owned by actor-a | one approved request and attributable independent decision | -| FR-2 | Business boundary | change the request after the approver opens it | stale approval is refused and the newer request remains unchanged | -| FR-3 | Foreign or revoked actor | Original fixture with changed authority | Safe refusal; no hidden data or new business effect | -| FR-4 | Alternate client/cohort | Same app and business inputs | Same authorized outcome or explicit unsupported refusal | - -## Technical Context - -Integration requirements: tables,actions. These are corpus tags, not installable -module names or a claim that every adapter exists. Use UMF typed access with -PostgreSQL 18 for tables and Truss for graphs. Initial UI is a TypeScript browser -app under SDK ADR-015 and CONTRACT-005. No frontend framework is selected here. -Platform contracts are explicit dependencies in the test plan; original native -model/action packages require exact source and cohort qualification before build. - -## Constraints, Assumptions, Dependencies - -- Shared obligations in SDK CONTRACT-011 apply in full. -- Fixture states and role separation are conformance defaults, not production rules. -- Same local PostgreSQL instance does not imply one transaction across all services. -- Native authoring, host/client and required provider integrations precede app execution. - -## Risks - -| Risk | Probability | Impact | Mitigation | -| --- | --- | --- | --- | -| Fixture mistaken for a running app | Unmeasured | False support claim | Separate inventory from full execution qualification | -| UI or hook bypasses policy | Unmeasured | Unauthorized outcome | Public host boundary and server-side current authority checks | -| Backend changes business meaning | Unmeasured | Invalid result | Independent expectations and candidate-cohort replay | - -## Open Questions - -Erik supplies workload, latency/cost limits, real retention rules and production -policy. Those values block production qualification, not fabricated specification. - -## Success Criteria - -The governing story's positive and negative criteria pass through exact installed -native integrations and real client/host paths, with safe required telemetry. -The corpus inventory alone establishes none of those execution claims. - -## Local registry requirement - -**FR-5**: Discover the approval desk through the local runtime registry, with a -description and packaged visual thumbnail. The Batten brand returns to that -registry. App-specific URL and session paths preserve independent app bindings. diff --git a/docs/helix/reference-apps/approval-desk/specs/01-frame/user-stories/US-101-journey.md b/docs/helix/reference-apps/approval-desk/specs/01-frame/user-stories/US-101-journey.md deleted file mode 100644 index ef2f61e..0000000 --- a/docs/helix/reference-apps/approval-desk/specs/01-frame/user-stories/US-101-journey.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -ddx: - id: US-101 - type: user-stories - activity: frame - authoring: - home: repo - links: - - id: approval-desk.prd - kind: derived_from ---- - -# US-101: Complete the approval desk journey - -**Feature**: FEAT-101 — Governed business journey -**Feature Requirements**: Reference-app business journey. -**PRD Requirements**: FR-1, FR-2, FR-3, FR-4. -**Priority**: P0. - -## Story - -**As a** requester and independent approver -**I want** to complete the governed business journey -**So that** I can rely on its authorized result and recover safely after interruption. - -## Context - -This is application MA-001. Business rules below are explicit fabricated defaults. -They remain independent of whichever platform implementation is being qualified. - -## Walkthrough - -1. The actor opens permitted work and inspects its current state and revision. -2. The actor follows the journey: Submit a request, inspect its revision, approve or reject, then observe the final decision. -3. The host checks current authority and original operation identity. -4. The actor observes the result, or reconciles the original uncertain attempt. - -## Acceptance Criteria - -- [ ] **US-101-AC1** — Given pending request owned by actor-a, when the actor performs the journey, then one approved request and attributable independent decision. -- [ ] **US-101-AC2** — Given the app's business invariant, when actors change the request after the approver opens it, then stale approval is refused and the newer request remains unchanged. -- [ ] **US-101-AC3** — Given a foreign, anonymous or revoked actor, when they attempt the same operation or continuation, then no private result or unauthorized mutation is disclosed. -- [ ] **US-101-AC4** — Given response loss or cancellation, when the actor inspects original work, then actual effects and uncertainty remain attributable without a fresh blind command. -- [ ] **US-101-AC5** — Given the same business inputs on another supported surface or cohort, when the journey runs, then meaning and authority are preserved; unsupported required behavior refuses explicitly. - -- [ ] **US-101-AC6** — Given the local runtime registry, when I open the approval desk card and later click the Batten brand, then I see the app description and visual thumbnail, enter its own URL, and return to the registry without gaining business authority from the listing. - -## Edge Cases - -- Empty permitted data returns an authorized empty state, not hidden counts. -- Dependency failure exposes a safe outcome; a scripted replacement is not selected. -- Query and inspection do not mutate business records or retry uncertain commands. - -## Test Scenarios - -| Scenario | AC ID | Input / State | Action | Expected Result | -| --- | --- | --- | --- | --- | -| Main journey | US-101-AC1 | pending request owned by actor-a | approve using the current revision | one approved request and attributable independent decision | -| Business invariant | US-101-AC2 | Same original fixture | change the request after the approver opens it | stale approval is refused and the newer request remains unchanged | -| Current authority | US-101-AC3 | Fixture foreign actor | Attempt and continue work | Safe denial without disclosure | -| Lost response | US-101-AC4 | Original possibly effective attempt | Observe original identity | Actual or uncertain outcome, no blind replay | -| Cohort parity | US-101-AC5 | Same semantic inputs | Exercise supported client/host | Same meaning or explicit refusal | - -## Dependencies - -Local PRD FR-1–4; SDK CONTRACT-003/004/005/011. Native platform model/action -contracts must be selected before executable app construction. Corpus tags: -tables,actions. Their presence requests support and grants no authority. - -## Out of Scope - -No money movement or authoritative accounting ledger. Full platform implementation is not authorized by this app story. diff --git a/docs/helix/reference-apps/approval-desk/specs/02-design/solution-designs/SD-101-approval-desk.md b/docs/helix/reference-apps/approval-desk/specs/02-design/solution-designs/SD-101-approval-desk.md deleted file mode 100644 index dfb7e2d..0000000 --- a/docs/helix/reference-apps/approval-desk/specs/02-design/solution-designs/SD-101-approval-desk.md +++ /dev/null @@ -1,144 +0,0 @@ ---- -ddx: - id: SD-101 - authoring: - home: repo - links: - - id: FEAT-101 - kind: informed_by - - id: ADR-016 - kind: informed_by ---- - -# SD-101-approval-desk: Native local approval workflow - -**Feature**: [[FEAT-101-business-journey]] - -## Scope - -Implement the governed approval journey across a TypeScript browser, generic -Batten operation host, optional original UMF table adapter and dedicated local -PostgreSQL 18 database. SDK architecture, ADR-015/016 and CONTRACT-012 govern -cross-component boundaries. TD-101 owns story implementation details. - -## Requirements Mapping - -| Requirement | Technical Capability | Component | Priority | -| --- | --- | --- | --- | -| FR-1 authorized business journey | Submit, inspect, edit and independently decide | Original UMF model and app operations | P0 | -| FR-2 independent invariant | Pending expected-revision condition and different decision principal | Native command and row policy | P0 | -| FR-3 authority and original outcomes | Server-owned sessions, current authority, original native receipts | Host and UMF adapter | P0 | -| FR-4 surface/cohort parity | Same host and operations through installed CLI and browser | Local assembly and public transport | P0 | -| FR-5 local discovery | Visual registry entries and brand navigation | Optional ASGI registry | P0 | - -Native database integrity governs concurrency. Local deadlines, body bounds and -session limits are explicit typed configuration. No production capacity or -latency budget is inferred; Erik supplies workload and acceptance budgets. - -## Solution Approaches - -**Selected: original platform integration.** UMF declares records, policy, -queries and conditional mutations; Weft plans native SQL. Batten owns public -operation dispatch and injected identity/capture services. Benefits are one -semantic authority and original-attempt recovery. Trade-off: the exact candidate -platform subset and installed cohort require explicit native evidence. - -**Alternative: app-specific persistence.** Handwritten SQL and a separate receipt -store could demonstrate a form quickly but duplicate platform authority, policy -and recovery. Rejected under the native UMF owner ruling. - -**Alternative: new declarative UI engine.** This would add an unqualified runtime -and vocabulary before the chosen TypeScript slice can prove the business journey. -ADR-015 selects authored TypeScript while preserving future ux-builder binding. - -## Domain Model - -A request holds its owner, summary, pending/approved/rejected state, opaque -revision and decision principal. A requester can own multiple requests. A reviewer -can inspect permitted requests and decide another person's pending request. -An invocation key identifies the original attempt; UMF owns its durable receipt. - -### Business Rules - -- **BR-1** — Independent decision: the decision principal differs from the owner. -- **BR-2** — Inspected state: decisions and edits require the current pending revision. -- **BR-3** — Current authority: each operation and observation uses the server-bound current actor. -- **BR-4** — Original outcome: uncertain work retains its original inputs and key. - -## System Decomposition - -| Component | Responsibility | Requirements | Interface / Design | -| --- | --- | --- | --- | -| TypeScript UI | Forms, permitted list, inspected detail and recovery control | FR-1/3 | CONTRACT-012; TD-101 | -| Approval operations | Validate business inputs and map native results | FR-1/2/4 | Public table port; TD-101 | -| Generic host | Admission, lifecycle, current identity, limits and capture outcomes | FR-3/4 | CONTRACT-001/012 | -| UMF PostgreSQL adapter | Delegate original wire, identity and native installation reference | FR-1/2/3 | Original UMF native table binding | -| Local composition | Explicit maintenance, stub sessions, loopback transport and safe capture | FR-3/4 | ADR-016, CONTRACT-012 | - -The browser sends a declared operation to the ASGI adapter; the host resolves -current identity before business dispatch. The app calls the portable table -port. Original UMF executes under the configured native person role and policy. -The result returns through safe host capture. UI response loss observes the -same native receipt; it never triggers an automatic replacement mutation. - -## Technology Rationale - -Original UMF/Weft and psycopg preserve platform ownership. Starlette/Uvicorn are -optional HTTP transport dependencies selected by ADR-016. Bun builds the -TypeScript DOM application; no frontend framework is introduced. Playwright, -TypeScript checking and ESLint are development tools. pgserver provides the -explicit dedicated PostgreSQL 18 local environment. - -## Traceability - -| Requirement ID | Component | Design Element | Test Strategy | -| --- | --- | --- | --- | -| FR-1 | App/model/UI | Public declared operations | STP-101 native browser journey | -| FR-2 | Original UMF model | BR-1/2 native conditions | Stale decision and current independent approval | -| FR-3 | Host/native adapter | BR-3/4 | Foreign/anonymous denial and lost-response observation | -| FR-4 | Local composition | Installed browser/CLI closure | Same native data after restart | - -## Concern Alignment - -Native dependency ownership, async public I/O, explicit typed configuration, -authorization, durable effect knowledge and the existing test ratchet apply. -The app imports no native engine in business/UI code. Core imports no provider. -Local authentication and capture do not qualify remote login or OTLP delivery. -ADR-016 records selected optional dependencies; no other framework is selected. - -## Constraints & Assumptions - -Only fabricated people and records are used. Initialization explicitly creates a -new dedicated cluster; ordinary startup verifies its original installed model/head. -The first local adapter subset accepts one module and one table; it rejects -other installation shapes before database effects. The declared query bounds -remain visible; broader schemas need their own qualification. - -## Risks - -Candidate SDK/source divergence requires original packaging verification and -retained wheel/source hashes. Local stub identity remains loopback-only. -Native, installed, browser and deployed qualification remain distinct claims. - -## Diagnostic Flow - -The host owns operation spans and durable audit. Native connection instrumentation -creates linked database child spans under the same context. The local exporter -filters before durable capture, excluding SQL, request text and connection details. -Capture loss returns safe unavailable/uncertain outcomes. A real OTLP receiver and -fleet diagnostic budgets remain separate qualification work owned by Erik. - -## Schema Basis - -The authoritative `../models/approval.umf.json` composes original UMF core 0.10.0, -tables 0.1.0 and table-operation 0.1. TD-101 declares its `ddx.schemas` identity. -No new vocabulary or ORM is introduced. The pinned original compiler and actual -native/browser journey establish only the exercised local candidate subset. - -## Local discovery - -CONTRACT-012 defines explicit registration metadata and per-app routing. -`AppListing` and `create_registry` stay in the optional ASGI module. The local -assembly supplies the registered app instance; static previews contain fabricated -data and listing grants no business access. STP-101 maps US-101-AC6 to browser -proof of the loaded thumbnail, description, app URL, scoped cookie and return link. diff --git a/docs/helix/reference-apps/approval-desk/specs/02-design/technical-designs/TD-101-approval-desk.md b/docs/helix/reference-apps/approval-desk/specs/02-design/technical-designs/TD-101-approval-desk.md deleted file mode 100644 index 8fa370c..0000000 --- a/docs/helix/reference-apps/approval-desk/specs/02-design/technical-designs/TD-101-approval-desk.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -ddx: - id: TD-101 - type: technical-design - activity: design - authoring: - home: repo - links: - - id: US-101 - kind: informed_by - schemas: - - id: batten.approval-desk - version: "0.10.0" - title: Approval desk native table declarations - path: docs/helix/reference-apps/approval-desk/specs/02-design/models/approval.umf.json - schemaFormat: umf ---- - -# TD-101: Native local approval desk - -**User Story**: [[US-101]] | **Feature**: [[FEAT-101]] | **Solution Design**: [[SD-101-approval-desk]] - -Governing acceptance: US-101-AC1 through US-101-AC6; STP-101 owns exact proof. - -## Technical Approach - -Declare records, row policy, reads and conditional mutations in original UMF. -Use the original deployment compiler and native async table transport, with -current person identity supplied by the host outside wire inputs. Native RLS -permits owned requests and explicitly assigned reviewers. Conditional decisions -also require an inspected pending revision and a different current principal. - -Use a pure generic host factory and injected services. An optional ASGI adapter -serves the TypeScript app through CONTRACT-012. The app cannot install providers, -execute SQL or choose the native identity. Explicit local setup creates an isolated -fabricated PostgreSQL 18 namespace; host startup only opens verified bindings. - -## Component Changes - -| Component | Ownership | Dependency rule | -| --- | --- | --- | -| contracts/runtime | Generic values, operation dispatch and lifecycle | stdlib and contracts only | -| tables | Portable table port | Contracts and stdlib only | -| umf_postgres | Public original UMF native adapter | UMF access/codegen, Weft and psycopg stay optional | -| hosting.local | Local identity, capture and provider assembly | Optional local adapter; no core-to-platform import | -| asgi | Local HTTP host/client boundary | Runtime/contracts and selected Starlette/Uvicorn | -| approval app | Business declaration, configuration and UI | Public Batten surfaces; no native driver in business/UI code | -| local maintenance | Dedicated test/dev database and native installation | Explicit command; never startup or ordinary invocation | - -The common boundary gate must know these owners before dependent source and -reject provider imports in generic core. Public export inventory remains explicit. - -## API/Interface Design - -SDK CONTRACT-001/005/012 govern shared surfaces. The app binds its own original -model operations rather than exposing a raw SQL or unrestricted native API route. -The browser retains original invocation inputs and keys when an outcome is uncertain. - -## Security - -Loopback local stub identity is explicit and distinct from production auth. -Same-origin, host, JSON type, request bounds and cookie protections apply before -mutation dispatch. Current host and native authority are checked on each call. -Only source-declared current-principal values may create owner/decision identity. -Audit contains safe identifiers/outcomes, not request titles, SQL or credentials. - -## Testing - -Qualify native model compilation, actual PostgreSQL 18 row policy, independent -approval, stale edits, hidden/foreign/revoked access and original outcome observation. -Use a real browser for TypeScript interaction, keyboard/focus and denied/uncertain -states. Consolidate duplicated read setup to keep the existing function ceiling; -retain every prior storage assertion and add one complete app journey behavior. - -## Schema Basis - -Reuse original UMF core 0.10.0, tables 0.1.0 and table-operation 0.1 from the inspected -public SDK. No alternate model compiler or schema vocabulary. The app's native -table source owns its actual fields, policy and conditional command bodies. -Compiler and native codec limitations must refuse explicitly before app support. - -## Diagnostic Wiring - -Host invocation and table integration produce scoped OpenTelemetry spans and safe -durable audit. Capture/receiver qualification is reported separately; local output -is not a deployed receiver claim. Native attribution reports actual session roles. - -## Implementation Sequence - -Compile and verify the app source first; establish ownership/import gates; then -wire generic host, native tables, ASGI and the TypeScript client. Complete the -native/browser journey and installed dependency evidence before claiming the slice. - -## Risks - -| Risk | Impact | Mitigation | -| --- | --- | --- | -| Candidate SDK assets differ from source | False cohort | Rebuild in an isolated pinned public source tree and retain hashes | -| Lost mutation response | Duplicate decision | Observe original native receipt and unchanged key/inputs | -| Local stub mistaken for real login | Unauthorized hosting | Restrict loopback/origin and reject production mode | - -## Registry integration - -The local registry owns `/`; this application moves to `/apps/approval-desk/`. -The Batten brand returns to the registry. Relative asset/API URLs and app-scoped -cookie paths preserve multiple app bindings without changing native records. -STP-101's existing journey enters through the registry and returns through the -brand link, proving the registry card's title, description, thumbnail and target. diff --git a/docs/helix/reference-apps/approval-desk/specs/03-test/local-execution.json b/docs/helix/reference-apps/approval-desk/specs/03-test/local-execution.json deleted file mode 100644 index 7eefdff..0000000 --- a/docs/helix/reference-apps/approval-desk/specs/03-test/local-execution.json +++ /dev/null @@ -1,138 +0,0 @@ -{ - "application": "MA-001", - "checks": { - "fast_quality": { - "command": "uv run --frozen python scripts/quality.py", - "native_cases": "separate JavaScript suite", - "passed": 18 - }, - "final_lint": { - "command": ".venv/bin/python scripts/quality.py --lint", - "result": "passed" - }, - "governed_artifacts": "ADR-007/016, CONTRACT-012, dependency-upgrade plan, release notes and approval-desk specs validated against installed HELIX catalog", - "native_browser": { - "command": "bun run test:native", - "passed": 2, - "runner_stats": { - "duration": 392065.85699999996, - "expected": 2, - "flaky": 0, - "skipped": 0, - "startTime": "2026-11-04T04:34:35.874Z", - "unexpected": 0 - }, - "source_hashes": { - ".cache/approval-cohort.json": "4d73fff69136bae575f4dd5f6ab3520053029fda7a2c148a5ca96eb268d069ac", - "bun.lock": "56403d4919f1e81ad31c45880f6c0eed818564cbf119b108e14dc64560bc315b", - "package.json": "1330e7c176fabc9d108151a8592e4388db1013ba43dd8bd8efa2621e8a38a1a3", - "playwright.config.ts": "a1a8a7cc7a6ec71842239dc18e9efd5f0b84f2ff7a5204a0615ea8f92fa46f58", - "tests/apps/approval.spec.ts": "af62c7c788ee425ec1f5fd46e184c54612405f7bb29ca366c2594460d63691c7", - "tests/apps/fixtures.ts": "eb2bd93ed38077b1bfbaddc364d7e775d92bd7b6e57befbf7c0d547f8fc17729", - "tests/apps/host.ts": "02cad565752c7ec9c6ade51321755f7f087277bd3c082ea42ae99ac5acfffb34", - "tests/apps/native_probe.py": "686b8c64bd8186d0fb8248f009a0e1f94c8c5f6a5c053b3350515144d6d4a900", - "uv.lock": "bc0af722f98bffbfccfb8add02cddfa6009c6a35ee3acff62630b1dcbdf1b41e" - }, - "tests": [ - "approval desk native browser journey", - "registry lists visual apps and brand returns home" - ] - }, - "registry_visual": { - "desktop_viewport": [ - 1365, - 900 - ], - "mobile_horizontal_overflow": false, - "mobile_viewport": [ - 390, - 844 - ], - "reviewed": "desktop and mobile renderings inspected locally", - "thumbnail_loaded": true - }, - "test_functions": 17 - }, - "cohort": { - "model_sha256": "8c13d687fa44837aee3137c33b3a3a61966a002bd69ab2ea4f2a59f21857749f", - "packages": { - "annotated-types": "0.8.0", - "anyio": "4.16.0", - "click": "8.5.0", - "fasteners": "0.20", - "h11": "0.16.0", - "idna": "3.20", - "novirhyza-batten-approval-desk": "0.1.0a2", - "novirhyza-batten-asgi": "0.1.0a2", - "novirhyza-batten-contracts": "0.1.0a2", - "novirhyza-batten-local": "0.1.0a2", - "novirhyza-batten-runtime": "0.1.0a2", - "novirhyza-batten-tables": "0.1.0a2", - "novirhyza-batten-umf-postgres": "0.1.0a2", - "opentelemetry-api": "1.45.2", - "opentelemetry-instrumentation": "0.66b2", - "opentelemetry-instrumentation-dbapi": "0.66b2", - "opentelemetry-instrumentation-psycopg": "0.66b2", - "opentelemetry-sdk": "1.45.2", - "opentelemetry-semantic-conventions": "0.66b2", - "packaging": "26.3", - "pgserver-pg18": "18.6.1", - "platformdirs": "4.14.3", - "psutil": "7.2.2", - "psycopg": "3.3.7", - "psycopg-binary": "3.3.7", - "pydantic": "2.14.2", - "pydantic_core": "2.50.2", - "starlette": "1.10.0", - "typing-inspection": "0.4.4", - "typing_extensions": "4.16.0", - "umf-codegen": "0.10.8", - "umf-core": "0.10.8", - "umf-weft": "0.4.57", - "umf_access": "0.1.0.dev8", - "uvicorn": "0.54.0", - "wrapt": "2.5.2" - }, - "python": "3.13.16", - "umf_artifacts": { - "umf_access-0.1.0.dev8-py3-none-any.whl": { - "release": "umf-v0.5.8", - "sha256": "1a21c1ddd59f6b23e9f0b33228280564af0e96bb4d13699b89616d5143e4fd23" - }, - "umf_codegen-0.10.8-py3-none-any.whl": { - "release": "umf-v0.10.8", - "sha256": "0d21acef3171442b818a4ad1dfdbaf99cc0f0f5557e5c670d5ce56243235dbc5" - } - }, - "wheels": { - "novirhyza_batten_approval_desk-0.1.0a2-py3-none-any.whl": "bf5185d5dd51ecf9d843afe027f9e6cc257cdb3aab8febb10260a1a31a9da46b", - "novirhyza_batten_asgi-0.1.0a2-py3-none-any.whl": "895e4760f55bba1858ab2301e1782bfda799d42b7772521f9d78fcef26eb69d4", - "novirhyza_batten_contracts-0.1.0a2-py3-none-any.whl": "cf20c473161a0a7bc3a30b7dcffe8727ce0460b9c574dd71539f18ed51911cc3", - "novirhyza_batten_local-0.1.0a2-py3-none-any.whl": "3f180b774d0342cfcd0961df5695f45965ee2c2bac2f8c6cb5bd4d29e76806cd", - "novirhyza_batten_runtime-0.1.0a2-py3-none-any.whl": "500c7f0f4465b21a6a95924f9fa5379f44e827bcc315fef8d4a3a887716bb27d", - "novirhyza_batten_tables-0.1.0a2-py3-none-any.whl": "45598cd5dda3c1ad7deb8039d66b42c9ddd78b08b90bc7614d3ac35f941d9bee", - "novirhyza_batten_umf_postgres-0.1.0a2-py3-none-any.whl": "5a96922b7c1d6898af4d3eef87a5e6904dad70c77cc7b2816f1fefbb71c629b9", - "umf_access-0.1.0.dev8-py3-none-any.whl": "1a21c1ddd59f6b23e9f0b33228280564af0e96bb4d13699b89616d5143e4fd23", - "umf_codegen-0.10.8-py3-none-any.whl": "0d21acef3171442b818a4ad1dfdbaf99cc0f0f5557e5c670d5ce56243235dbc5" - } - }, - "date": "2026-11-03", - "evidence_limits": "This is one installed local table-app cohort. It does not establish full corpus, other-host, generic semantic generation, OTLP receiver or production qualification; the strict full-corpus gate continues to refuse.", - "kind": "local-execution-evidence", - "observed_behaviors": [ - "native original-UMF deployment and table execution on PostgreSQL 18", - "independent attributable approval", - "stale revision refusal", - "reviewer self-decision refusal with unchanged pending record", - "foreign/anonymous/revoked non-disclosure", - "actual committed mutation response loss and original receipt observation without duplicate rows", - "installed CLI and restart persistence", - "linked database/host spans with request text, SQL and connection details excluded from durable capture", - "registry description and loaded thumbnail, app entry and return navigation", - "app-scoped cookie path and refusal of unregistered or legacy root API routes", - "revoking the reviewer database group blocks cross-owner conditional decisions while preserving the pending row", - "changed native installation head refuses startup and the restored reference starts successfully" - ], - "qualification": "exercised local preview", - "schema": 1 -} diff --git a/docs/helix/reference-apps/approval-desk/specs/03-test/test-plan.md b/docs/helix/reference-apps/approval-desk/specs/03-test/test-plan.md deleted file mode 100644 index d41eb30..0000000 --- a/docs/helix/reference-apps/approval-desk/specs/03-test/test-plan.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -ddx: - id: TP-101 - type: test-plan - activity: test - authoring: - home: repo - links: - - id: US-101 - kind: informed_by ---- - -# Approval desk: conformance allocation - -## Strategy - -**Goal**: Qualify MA-001's full authorized journey and distinct business invariant. -**Out of scope**: No money movement or authoritative accounting ledger. -Use shared runner obligations from SDK CONTRACT-011 and preserve the independent -story expectations. No app result may be inferred from inventory validation. - -## Framework Selection & Cost - -| Layer | Framework | Justification | CI Time Impact | Maintenance Burden | -| --- | --- | --- | --- | --- | -| Inventory | Existing stdlib corpus checker | Exact scope/fixture integrity without app loading | Measured by shared command; no estimate supplied | Shared | -| Native actions | Qualified UMF/existing provider conformance | Reuse native ORM/graph semantics rather than duplicate them | Unknown; Erik owns budget | One shared runner, app data | -| UI journey | Real TypeScript client/browser harness | Authored UI requires independent observable journeys | Unknown; harness selection precedes app build | App acceptance scenarios | -| Model behavior where requested | Deterministic scripted API plus separate live API cut | Reproducible rules and actual integration prove different properties | Unknown | Fixture/model cohort scoped | - -## Critical Paths (P0) - -1. Story FR-1/2: one approved request and attributable independent decision; invariant: A requester cannot approve their own request; a stale decision cannot overwrite a later revision. -2. Story FR-3: unauthorized, stale, duplicate and uncertain work never loses its - actual authority or outcome boundary. -3. Story FR-4: exact supported client/cohort preserves business meaning and safe - diagnostics, including current identity on continuation. - -## Acceptance Criteria Layer Allocation - -| AC class / source | Story Test Plan | Primary Layer | Why this layer | -| --- | --- | --- | --- | -| US-101 main business and invariant classes | App story test plan at build handoff | Public client/host/native provider journey | Only full path proves business result | -| US-101 permission/recovery classes | Same app story test plan | Native integration | Current authority and durable effects cross boundaries | -| US-101 surface/candidate classes | Same app story test plan | Real browser plus separate CLI parity observation | TypeScript and server behavior require distinct observations | - -The authorized local build uses [[SD-101-approval-desk]], -[[TD-101-approval-desk]] and [[STP-101-approval-desk]] for exact native/model/browser -allocation. Playwright exercises installed artifacts on a dedicated PostgreSQL 18 -cluster; the broad corpus/receiver obligations remain distinct from that local proof. - -## Secondary Paths (P1-P2) - -Optional UI polish cannot weaken required denial, uncertainty or accessibility -behavior. There is no optional escape from an active P0 criterion. - -## Test Data Strategy - -Use `../../fixtures.json` and the story's independent Given/When/Then examples. -Create isolated native namespaces with explicit PostgreSQL 18/Truss bindings and -scoped local identity. No production snapshot, credentials or inferred grants. -Every generated/native input retains its app/model/refinement identity. - -## Known Gaps - -Complete app execution requires qualified host/client, native model artifacts, -selected integrations and a trusted evidence runner. These are qualification -blockers, not accepted runtime risk or passing skips. SDK component storage -checks qualify only their own boundary. TypeScript UI is authored, not generated -from a declarative UI model. UI harness selection belongs to the app build design. - -## Build Commands - -From the SDK repository root: - -```sh -python scripts/check_micro_apps.py -python scripts/check_micro_apps.py --require-execution -``` - -The first command verifies inventory only; the second must refuse absent complete -app execution evidence. SDK platform dependencies are explicit file references: -`../../../../02-design/contracts/CONTRACT-003-composition.md`, -`../../../../02-design/contracts/CONTRACT-004-host-profiles.md`, -`../../../../02-design/contracts/CONTRACT-005-ux-builder-binding.md`, and -`../../../../02-design/contracts/CONTRACT-011-micro-app-conformance.md`. - -**Blocking gate**: Every active story criterion and shared obligation must have -trusted passing evidence for exact inputs before this app is called qualified. -No test-function ceiling increase; parameterize cases in shared machinery. - -## Diagnostic Test Strategy - -Exercise actual safe host audit and required telemetry across client, host and -providers, including a real receiver, refusal, retries, capture loss and shutdown. -A mocked exporter or parsed JSON is not receiver qualification. Erik supplies -workload and diagnostic overhead budgets before production qualification. diff --git a/docs/helix/reference-apps/approval-desk/specs/03-test/test-plans/STP-101-approval-desk.md b/docs/helix/reference-apps/approval-desk/specs/03-test/test-plans/STP-101-approval-desk.md deleted file mode 100644 index 2d7c0d3..0000000 --- a/docs/helix/reference-apps/approval-desk/specs/03-test/test-plans/STP-101-approval-desk.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -ddx: - id: STP-101 - authoring: - home: repo - links: - - id: US-101 - kind: informed_by - - id: TD-101 - kind: informed_by ---- - -# Story Test Plan: STP-101-approval-desk - -## Story Reference - -**User Story**: [[US-101-journey]] -**Technical Design**: [[TD-101-approval-desk]] -**Related Solution Design**: [[SD-101-approval-desk]], SDK architecture and CONTRACT-012. -**Project Test Plan**: [[test-plan]] (TP-101). - -## Scope and Objective - -Prove the first local application through installed wheels, real PostgreSQL 18, -original UMF/Weft and the actual TypeScript browser client. The blocking command -is `just approval-test`. This bounded proof does not qualify other hosts/cohorts, -the complete micro-app corpus, generated semantic suites or an OTLP receiver. - -## Acceptance Criteria Test Mapping - -The business rows use `approval desk native browser journey` in -`tests/apps/approval.spec.ts`, citing each ID in its source comment. This table -allocates required coverage; `local-execution.json` records the exact exercised -subset and observed results. - -| AC ID | Acceptance Criterion | New or Existing Test(s) to Create or Run | Asserted Behavior (what the test verifies) | AC-ID Citation | Test Level | File or Command | Setup / Data | Notes | -| --- | --- | --- | --- | --- | --- | --- | --- | --- | -| US-101-AC1 | Submit, inspect, independently decide | Native browser journey | Blake approves Alex's pending record, current owner/title and attributable decision survive restart | `@covers US-101-AC1` | E2E | `just approval-test` | Dedicated new local cluster; fabricated people | Empty view is exercised; both decision values remain required qualification targets | -| US-101-AC2 | Inspected revision becomes stale | Same journey | Alex's edit persists; Blake's stale approval returns conflict; refresh permits the current revision; self decision has no effect | `@covers US-101-AC2` | E2E | Same command | Two independent browser sessions | Server/native conditions govern | -| US-101-AC3 | Foreign, anonymous or revoked access | Same journey | Anonymous and logged-out calls denied; Casey cannot see foreign record; browser-supplied identity and alternate origin/host refused | `@covers US-101-AC3` | E2E | Same command | Actual cookie sessions | No client role authority | -| US-101-AC4 | Mutation response is lost | Same journey | Browser intercept forwards the real mutation then aborts its response; original key observation confirms the actual receipt with no duplicate record | `@covers US-101-AC4` | E2E | Same command | Real native receipt | Capture loss remains explicit | -| US-101-AC5 | Another supported surface | Same journey | Installed CLI sees the same decided record under current identity after server restart; unsupported operations refuse | `@covers US-101-AC5` | Integration | Same command | Same dedicated cluster | One exact local cohort only | -| US-101-AC6 | Discover app and return to registry | `registry lists visual apps and brand returns home` | Card includes description and loaded visual thumbnail; opens its app URL; brand returns to registry; cookies use the app path; unregistered/legacy API routes return 404 | `@covers US-101-AC6` | E2E | `just approval-test` | Same installed local cluster, without new business mutations | Listing grants no authority | - -## Executable Proof - -### Primary Commands - -```sh -just approval-prepare -just approval-test -just check -``` - -### Planned Test Files - -`tests/apps/approval.spec.ts` owns both canonical scenarios; its fixtures own only -process setup/cleanup. Shared storage range/integrity coverage consolidates real -read setup without removing assertions, keeping the function ceiling unchanged. Registry coverage also consolidates the -shared listing setup for projection, progress and cursor scope without dropping -any storage assertions. - -### Coverage Focus - -Authorization, native revision conditions, safe original-outcome recovery, -installed closure and no implicit deployment during startup. - -## Data and Setup - -Use fixture names Alex, Blake and Casey; all titles are fabricated. Compile the -original app UMF source with the pinned public SDK. Explicitly initialize a fresh -temporary PostgreSQL 18 cluster. Await the socket-bound JSON readiness signal; -use Playwright's observable-state assertions, with no test sleeps or blind retries. - -## Edge Cases and Failure Modes - -Empty state, invalid/foreign operations, stale decisions, self decisions, revoked -sessions, response loss and capture failure must preserve actual effect knowledge. -Transport denial occurs before business invocation. Startup verifies the original -installed schema head rather than creating roles, tables or migrating data. - -## Build Handoff - -Initialize the native model, assemble installed dependencies, then execute the -browser journey and installed CLI against the same data. Keep core independent -of providers and business/UI code independent of native clients. Completion -requires passing observed results, not only this allocation or inventory checks. - -## Diagnostic Proof - -Inspect actual instrumented database child spans and durable safe audit records; -no titles, SQL, connection strings or cookie material may reach these files. -A required-capture failure must return a safe unavailable/uncertain result. -This local capture profile is separate from the real receiver qualification -required for fleet deployment; JSONL inspection cannot establish that claim. -Erik owns the production workload and telemetry overhead budgets. - -## UX Coverage - -| Pattern | Disposition | AC IDs or Reason | Evidence | -| --- | --- | --- | --- | -| navigation | covered | US-101-AC1, US-101-AC6 | Browser selects and inspects requests | -| keyboard-overlays | not-applicable | No modal, menu, popover or keyboard overlay exists | Native form controls and visible focus remain required | -| async-actions | covered | US-101-AC2, US-101-AC4 | Busy guards, stale refresh and explicit original outcome check | -| forms | covered | US-101-AC1 | Labeled required summary, edit and decision controls | -| data-states | covered | US-101-AC1, US-101-AC3 | Empty, permitted, denied and final record states | -| destructive-actions | covered | US-101-AC2 | Decisions are conditional on an inspected pending revision | - -## Completion observation - -On 2026-11-02 the installed native/browser suite passed both named tests. The -common fast gate passed 18 cases; the function census remains 17. Final lint, -strict Python/TypeScript checking, import/export/shape gates and governed artifact -validation passed. [Local execution evidence](../local-execution.json) records -the exact original platform source, wheel hashes, observed behaviors and limits. -Registry desktop/mobile renders were inspected locally; the thumbnail loaded and -the mobile view had no horizontal overflow. Full corpus and receiver qualification -remain separate, and no inventory flag is treated as executable proof. diff --git a/docs/helix/reference-apps/approval-desk/specs/04-build/implementation-plan.md b/docs/helix/reference-apps/approval-desk/specs/04-build/implementation-plan.md deleted file mode 100644 index 9008a36..0000000 --- a/docs/helix/reference-apps/approval-desk/specs/04-build/implementation-plan.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -ddx: - id: approval-desk.build - type: implementation-plan - activity: build - authoring: - home: repo - links: - - id: US-101 - kind: informed_by - - id: TP-101 - kind: informed_by ---- - -# Approval desk build - -## Scope - -The owner authorized building the first reference app after pushing the corpus. -Implement the requester/independent approver journey with native UMF/PostgreSQL -tables, local host and authored TypeScript UI. US-101, FEAT-101 and TP-101 govern -business behavior; SDK CONTRACT-001/003/005/011 and ADR-015/016 govern integration. - -## Shared Constraints - -No new ORM, compiler, agent or UI framework. Generic runtime imports no platform -libraries. Browser code uses public operations; authentication is explicitly -local-only and server-bound. Startup never migrates; explicit maintenance creates -only the dedicated fabricated local namespace. No production service or secret -access. Preserve the decreasing measured test-function ceiling and native meanings. - -## Implementation Slices - -| Slice | Story / Area | Governing Artifacts | Depends On | Validation Gate | -| --- | --- | --- | --- | --- | -| AD-01 | Contract and native source basis | US-101, ADR-016 | None | Inspect public SDK and compile original app declarations | -| AD-02 | Module boundaries and generic host ports | SDK CONTRACT-001/002 | AD-01 | Import/export/shape gates and negative controls before dependent source | -| AD-03 | Native tables and explicit local setup | Original UMF app model | AD-02 | PostgreSQL 18, RLS, conditional commands and original receipt observation | -| AD-04 | Public ASGI/client and TypeScript app | SDK CONTRACT-005, app transport contract | AD-03 | Same-origin/local identity, native authorization and accessible browser journey | -| AD-05 | Native/browser proof and documentation | TP-101 and story test plan | AD-04 | Positive, stale, self/foreign/revoked, retry/recovery and restart outcomes | - -## Execution Contract - -The current user instruction supplies build authorization, including necessary -local test setup. No production apply, real credentials or migration of existing -data is authorized. Token, money and time ceilings were not supplied; available -tools have no reliable billing meter. Verification and review remain in scope. -The preceding corpus commit/push is separate from this implementation's source. - -## Continuation Evidence - -Resume from the diff, native compilation and actual test outputs. The corpus was -pushed before source work. Keep native SDK limitations explicit; do not replace -an unavailable feature with handwritten persistence or a scripted app result. - -## Validation Plan - -Reuse installed original SDK code and compile app-owned UMF declarations. Test -real PostgreSQL 18 and actual TypeScript browser interactions, current authority, -stale revisions, original-attempt observation and server restart. Consolidate only -duplicated read setup to preserve the global function budget. Inventory validation -does not establish app execution, and local capture does not establish deployed -or OTLP receiver qualification. Record each actual evidence layer separately. - -## Risks and Rollbacks - -| Risk | Impact | Response | Rollback | -| --- | --- | --- | --- | -| Candidate SDK subset refuses app semantics | Native integration blocked | Diagnose exact public capability and retain upstream ownership | Refuse affected operation | -| Local stub escapes intended surface | Identity confusion | Loopback-only origin/host guards and explicit local mode | Disable local authentication route | -| Mutation acknowledgement is lost | Duplicate decision | Observe original native receipt with unchanged inputs | Never blindly replay with a fresh key | - -## Exit Criteria - -The app can be built and run locally through documented commands, and its chosen -native/browser journey passes against original UMF/PostgreSQL behavior. Required -boundaries and evidence remain explicit; no unsupported production, broader SDK -or full-corpus qualification is claimed. - -## Completion evidence - -The local approval journey and registry are implemented. Native/browser proof -passed two tests; the fast gate passed 18 cases within the unchanged 17-function -ceiling. See `../03-test/local-execution.json` and STP-101 for exact cohort and -assertion scope. Broader platform and production qualification remain governed by -their own integration work items. diff --git a/docs/helix/reference-apps/case-tracker/.helix.yml b/docs/helix/reference-apps/case-tracker/.helix.yml deleted file mode 100644 index da1d4a0..0000000 --- a/docs/helix/reference-apps/case-tracker/.helix.yml +++ /dev/null @@ -1,12 +0,0 @@ -{ - "flows": [ - { - "id": "helix", - "root": "specs/" - } - ], - "x-batten-app": { - "id": "MA-003", - "workflow": "../../04-build/batten-app-workflow.md" - } -} diff --git a/docs/helix/reference-apps/case-tracker/AGENTS.md b/docs/helix/reference-apps/case-tracker/AGENTS.md deleted file mode 100644 index e2524cd..0000000 --- a/docs/helix/reference-apps/case-tracker/AGENTS.md +++ /dev/null @@ -1,19 +0,0 @@ -# Working on Case and task tracker - -Read this directory's `.helix.yml` and engage the installed HELIX skill. This is -application MA-003; governed artifacts belong only in `specs/`. Start with -`specs/01-frame/prd.md`, then the story and test plan. Follow -[the Batten app workflow](../../04-build/batten-app-workflow.md), using templates, -prompts and metadata from the installed HELIX catalog. Do not vendor the catalog. - -Reference app rules are fabricated conformance defaults, not real business policy. -UMF owns models/actions and typed persistence; PostgreSQL 18 and Truss own native -storage/execution. UI is application-authored TypeScript through the public host -client, with room for ux-builder. No direct database/provider access in the UI. -Read applicable SDK contracts through explicit file paths; local artifact IDs -resolve inside this app scope. App specs do not authorize SDK or upstream edits. - -Build only after a scoped app implementation instruction and qualified integration -closure. No credentials, production data, migrations, applies, commits or pushes -without their applicable authorization. Never replace a required failing positive -case with a skip, mock result or changed expected outcome. diff --git a/docs/helix/reference-apps/case-tracker/fixtures.json b/docs/helix/reference-apps/case-tracker/fixtures.json deleted file mode 100644 index 9277b9d..0000000 --- a/docs/helix/reference-apps/case-tracker/fixtures.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "application": "MA-003", - "record": { - "id": "fabricated-case-tracker-record", - "owner": "actor-a", - "state": "open" - }, - "actors": { - "permitted": "actor-a", - "foreign": "actor-b", - "independent_reviewer": "actor-c" - } -} diff --git a/docs/helix/reference-apps/case-tracker/specs/01-frame/features/FEAT-103-business-journey.md b/docs/helix/reference-apps/case-tracker/specs/01-frame/features/FEAT-103-business-journey.md deleted file mode 100644 index 63d854e..0000000 --- a/docs/helix/reference-apps/case-tracker/specs/01-frame/features/FEAT-103-business-journey.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -ddx: - id: FEAT-103 - type: feature-specification - activity: frame - authoring: - home: repo - links: - - id: case-tracker.prd - kind: derived_from ---- - -# FEAT-103: Governed business journey - -**Feature ID**: FEAT-103 -**Priority**: P0 -**Owner**: Erik LaBianca -**Covered PRD Subsystem(s)**: Governed business journey -**Covered PRD Requirements**: FR-1, FR-2, FR-3, FR-4 -**Cross-Subsystem Rationale**: None; one app-specific journey. - -## Overview - -The app must complete its PRD's business journey through authorized platform -operations and preserve its independently stated business invariant. - -## Ideal Future State - -The actor can rely on the final result or safely reconcile original uncertain -work across supported surfaces, without rebuilding integration or policy. - -## Problem Statement - -Passing component calls do not prove this app's domain outcome. The PRD defines -its users, concepts and rule; the story owns its observable acceptance criteria. - -## Requirements - -- FR-1 must complete the specific app journey in the PRD. -- FR-2 must enforce the PRD's distinct business invariant. -- FR-3 must preserve current permission and actual/uncertain effects on failure. -- FR-4 must preserve meaning and attribution across qualified surfaces/cohorts. - -### Non-Functional Requirements - -No private provider access or client-derived authority. Bounded native work and -safe diagnostics follow SDK CONTRACT-011; Erik supplies production workload and -latency/cost budgets. No numeric operating target is assumed. - -## User Stories - -[US-103](../user-stories/US-103-journey.md) owns the acceptance criteria. - -## Edge Cases and Error Handling - -Foreign/revoked actors, changed inputs, interrupted commands and unavailable -providers retain the story's explicit safe outcomes. No silent scripted replacement. - -## Constraints and Assumptions - -Fabricated business defaults, native UMF data/actions, PostgreSQL 18/Truss when -required, and authored TypeScript UI. Exact platform subset needs qualification. - -## Dependencies - -Local PRD FR-1–4 and SDK CONTRACT-003/004/005/011 through explicit file references -in the app test plan. The app has no authority to modify those shared contracts. - -## Out of Scope - -New platform engines, privileged UI-side data access, production policy or deployment. diff --git a/docs/helix/reference-apps/case-tracker/specs/01-frame/prd.md b/docs/helix/reference-apps/case-tracker/specs/01-frame/prd.md deleted file mode 100644 index 59b4102..0000000 --- a/docs/helix/reference-apps/case-tracker/specs/01-frame/prd.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -ddx: - id: case-tracker.prd - type: prd - activity: frame - authoring: - home: repo ---- - -# Case and task tracker - -## Summary - -MA-003 is a fabricated enterprise reference app for a case owner and assigned worker. It exercises -open a case, relate a task, assign work, satisfy prerequisites and close the case. Its purpose is to qualify a useful business journey -through Batten's platform integrations, rather than introduce a new engine. - -## Problem and Goals - -### Problem - -Users need an attributable business result across data, permission and failure -boundaries. A successful component call alone cannot establish this workflow. - -### Goals - -- Complete the stated journey while preserving current access and original identity. -- Detect the app-specific business invariant: A case cannot close with unresolved required work; a task relationship does not confer read permission. -- Reproduce denied, stale, duplicate, cancelled and uncertain outcomes independently - of the host implementation. - -### Non-Goals - -No general-purpose project-planning or collaboration engine. - -## Users and Scope - -The case owner and assigned worker roles are assumed reference roles selected for this corpus, not -validated research personas. Erik owns real user validation and policy changes. -Business concepts: Case, Task, Dependency. All records and actors are fabricated. - -## Requirements - -### Must Have (P0) - -- Complete the journey and enforce its app-specific business invariant. -- Apply shared authority, lifecycle and evidence obligations without disclosure. -- Qualify required native integrations and real UI outcomes before a support claim. - -## Functional Requirements - -### Subsystem: Governed business journey - -Feature owner: FEAT-103. - -- **FR-1** — Open a case, relate a task, assign work, satisfy prerequisites and close the case. -- **FR-2** — A case cannot close with unresolved required work; a task relationship does not confer read permission. -- **FR-3** — Permission loss, stale inputs and interrupted work must preserve - authorized visibility, actual effects and the original uncertain outcome. -- **FR-4** — Supported surfaces and candidate cohorts must preserve the same - business semantics with attributable decisions and safe diagnostics. - -## Acceptance Test Sketches - -| Requirement | Scenario | Input | Expected Output | -| --- | --- | --- | --- | -| FR-1 | Main journey | case with a required unfinished task | closed case with original task and decision lineage | -| FR-2 | Business boundary | attempt closure while the required task remains open | closure is refused and both current states remain visible only to authorized actors | -| FR-3 | Foreign or revoked actor | Original fixture with changed authority | Safe refusal; no hidden data or new business effect | -| FR-4 | Alternate client/cohort | Same app and business inputs | Same authorized outcome or explicit unsupported refusal | - -## Technical Context - -Integration requirements: tables,graphs,actions. These are corpus tags, not installable -module names or a claim that every adapter exists. Use UMF typed access with -PostgreSQL 18 for tables and Truss for graphs. Initial UI is a TypeScript browser -app under SDK ADR-015 and CONTRACT-005. No frontend framework is selected here. -Platform contracts are explicit dependencies in the test plan; original native -model/action packages require exact source and cohort qualification before build. - -## Constraints, Assumptions, Dependencies - -- Shared obligations in SDK CONTRACT-011 apply in full. -- Fixture states and role separation are conformance defaults, not production rules. -- Same local PostgreSQL instance does not imply one transaction across all services. -- Native authoring, host/client and required provider integrations precede app execution. - -## Risks - -| Risk | Probability | Impact | Mitigation | -| --- | --- | --- | --- | -| Fixture mistaken for a running app | Unmeasured | False support claim | Separate inventory from full execution qualification | -| UI or hook bypasses policy | Unmeasured | Unauthorized outcome | Public host boundary and server-side current authority checks | -| Backend changes business meaning | Unmeasured | Invalid result | Independent expectations and candidate-cohort replay | - -## Open Questions - -Erik supplies workload, latency/cost limits, real retention rules and production -policy. Those values block production qualification, not fabricated specification. - -## Success Criteria - -The governing story's positive and negative criteria pass through exact installed -native integrations and real client/host paths, with safe required telemetry. -The corpus inventory alone establishes none of those execution claims. diff --git a/docs/helix/reference-apps/case-tracker/specs/01-frame/user-stories/US-103-journey.md b/docs/helix/reference-apps/case-tracker/specs/01-frame/user-stories/US-103-journey.md deleted file mode 100644 index 859ebe0..0000000 --- a/docs/helix/reference-apps/case-tracker/specs/01-frame/user-stories/US-103-journey.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -ddx: - id: US-103 - type: user-stories - activity: frame - authoring: - home: repo - links: - - id: case-tracker.prd - kind: derived_from ---- - -# US-103: Complete the case and task tracker journey - -**Feature**: FEAT-103 — Governed business journey -**Feature Requirements**: Reference-app business journey. -**PRD Requirements**: FR-1, FR-2, FR-3, FR-4. -**Priority**: P0. - -## Story - -**As a** case owner and assigned worker -**I want** to complete the governed business journey -**So that** I can rely on its authorized result and recover safely after interruption. - -## Context - -This is application MA-003. Business rules below are explicit fabricated defaults. -They remain independent of whichever platform implementation is being qualified. - -## Walkthrough - -1. The actor opens permitted work and inspects its current state and revision. -2. The actor follows the journey: Open a case, relate a task, assign work, satisfy prerequisites and close the case. -3. The host checks current authority and original operation identity. -4. The actor observes the result, or reconciles the original uncertain attempt. - -## Acceptance Criteria - -- [ ] **US-103-AC1** — Given case with a required unfinished task, when the actor performs the journey, then closed case with original task and decision lineage. -- [ ] **US-103-AC2** — Given the app's business invariant, when actors attempt closure while the required task remains open, then closure is refused and both current states remain visible only to authorized actors. -- [ ] **US-103-AC3** — Given a foreign, anonymous or revoked actor, when they attempt the same operation or continuation, then no private result or unauthorized mutation is disclosed. -- [ ] **US-103-AC4** — Given response loss or cancellation, when the actor inspects original work, then actual effects and uncertainty remain attributable without a fresh blind command. -- [ ] **US-103-AC5** — Given the same business inputs on another supported surface or cohort, when the journey runs, then meaning and authority are preserved; unsupported required behavior refuses explicitly. - -## Edge Cases - -- Empty permitted data returns an authorized empty state, not hidden counts. -- Dependency failure exposes a safe outcome; a scripted replacement is not selected. -- Query and inspection do not mutate business records or retry uncertain commands. - -## Test Scenarios - -| Scenario | AC ID | Input / State | Action | Expected Result | -| --- | --- | --- | --- | --- | -| Main journey | US-103-AC1 | case with a required unfinished task | complete the task and close the case | closed case with original task and decision lineage | -| Business invariant | US-103-AC2 | Same original fixture | attempt closure while the required task remains open | closure is refused and both current states remain visible only to authorized actors | -| Current authority | US-103-AC3 | Fixture foreign actor | Attempt and continue work | Safe denial without disclosure | -| Lost response | US-103-AC4 | Original possibly effective attempt | Observe original identity | Actual or uncertain outcome, no blind replay | -| Cohort parity | US-103-AC5 | Same semantic inputs | Exercise supported client/host | Same meaning or explicit refusal | - -## Dependencies - -Local PRD FR-1–4; SDK CONTRACT-003/004/005/011. Native platform model/action -contracts must be selected before executable app construction. Corpus tags: -tables,graphs,actions. Their presence requests support and grants no authority. - -## Out of Scope - -No general-purpose project-planning or collaboration engine. Full platform implementation is not authorized by this app story. diff --git a/docs/helix/reference-apps/case-tracker/specs/03-test/test-plan.md b/docs/helix/reference-apps/case-tracker/specs/03-test/test-plan.md deleted file mode 100644 index 16dbedd..0000000 --- a/docs/helix/reference-apps/case-tracker/specs/03-test/test-plan.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -ddx: - id: TP-103 - type: test-plan - activity: test - authoring: - home: repo - links: - - id: US-103 - kind: informed_by ---- - -# Case and task tracker: conformance allocation - -## Strategy - -**Goal**: Qualify MA-003's full authorized journey and distinct business invariant. -**Out of scope**: No general-purpose project-planning or collaboration engine. -Use shared runner obligations from SDK CONTRACT-011 and preserve the independent -story expectations. No app result may be inferred from inventory validation. - -## Framework Selection & Cost - -| Layer | Framework | Justification | CI Time Impact | Maintenance Burden | -| --- | --- | --- | --- | --- | -| Inventory | Existing stdlib corpus checker | Exact scope/fixture integrity without app loading | Measured by shared command; no estimate supplied | Shared | -| Native actions | Qualified UMF/existing provider conformance | Reuse native ORM/graph semantics rather than duplicate them | Unknown; Erik owns budget | One shared runner, app data | -| UI journey | Real TypeScript client/browser harness | Authored UI requires independent observable journeys | Unknown; harness selection precedes app build | App acceptance scenarios | -| Model behavior where requested | Deterministic scripted API plus separate live API cut | Reproducible rules and actual integration prove different properties | Unknown | Fixture/model cohort scoped | - -## Critical Paths (P0) - -1. Story FR-1/2: closed case with original task and decision lineage; invariant: A case cannot close with unresolved required work; a task relationship does not confer read permission. -2. Story FR-3: unauthorized, stale, duplicate and uncertain work never loses its - actual authority or outcome boundary. -3. Story FR-4: exact supported client/cohort preserves business meaning and safe - diagnostics, including current identity on continuation. - -## Acceptance Criteria Layer Allocation - -| AC class / source | Story Test Plan | Primary Layer | Why this layer | -| --- | --- | --- | --- | -| US-103 main business and invariant classes | App story test plan at build handoff | Public client/host/native provider journey | Only full path proves business result | -| US-103 permission/recovery classes | Same app story test plan | Native integration | Current authority and durable effects cross boundaries | -| US-103 surface/candidate classes | Same app story test plan | Real browser plus separate CLI parity observation | TypeScript and server behavior require distinct observations | - -The build handoff must author the per-criterion story test plan and native model/ -technical design from installed HELIX templates before executable app code. -No preselected test function or framework is fabricated before that contract exists. - -## Secondary Paths (P1-P2) - -Optional UI polish cannot weaken required denial, uncertainty or accessibility -behavior. There is no optional escape from an active P0 criterion. - -## Test Data Strategy - -Use `../../fixtures.json` and the story's independent Given/When/Then examples. -Create isolated native namespaces with explicit PostgreSQL 18/Truss bindings and -scoped local identity. No production snapshot, credentials or inferred grants. -Every generated/native input retains its app/model/refinement identity. - -## Known Gaps - -Complete app execution requires qualified host/client, native model artifacts, -selected integrations and a trusted evidence runner. These are qualification -blockers, not accepted runtime risk or passing skips. SDK component storage -checks qualify only their own boundary. TypeScript UI is authored, not generated -from a declarative UI model. UI harness selection belongs to the app build design. - -## Build Commands - -From the SDK repository root: - -```sh -python scripts/check_micro_apps.py -python scripts/check_micro_apps.py --require-execution -``` - -The first command verifies inventory only; the second must refuse absent complete -app execution evidence. SDK platform dependencies are explicit file references: -`../../../../02-design/contracts/CONTRACT-003-composition.md`, -`../../../../02-design/contracts/CONTRACT-004-host-profiles.md`, -`../../../../02-design/contracts/CONTRACT-005-ux-builder-binding.md`, and -`../../../../02-design/contracts/CONTRACT-011-micro-app-conformance.md`. - -**Blocking gate**: Every active story criterion and shared obligation must have -trusted passing evidence for exact inputs before this app is called qualified. -No test-function ceiling increase; parameterize cases in shared machinery. - -## Diagnostic Test Strategy - -Exercise actual safe host audit and required telemetry across client, host and -providers, including a real receiver, refusal, retries, capture loss and shutdown. -A mocked exporter or parsed JSON is not receiver qualification. Erik supplies -workload and diagnostic overhead budgets before production qualification. diff --git a/docs/helix/reference-apps/catalog.json b/docs/helix/reference-apps/catalog.json deleted file mode 100644 index 564ec22..0000000 --- a/docs/helix/reference-apps/catalog.json +++ /dev/null @@ -1,264 +0,0 @@ -{ - "version": 1, - "workflow": "docs/helix/04-build/batten-app-workflow.md", - "apps": [ - { - "id": "MA-001", - "slug": "approval-desk", - "root": "docs/helix/reference-apps/approval-desk", - "ui": "typescript", - "modules": [ - "tables", - "actions" - ], - "story": "US-101", - "obligations": [ - "AUTH", - "IDENTITY", - "COMMANDS", - "LIFECYCLE", - "LIMITS", - "PARITY", - "OBSERVABILITY" - ] - }, - { - "id": "MA-002", - "slug": "service-intake", - "root": "docs/helix/reference-apps/service-intake", - "ui": "typescript", - "modules": [ - "tables", - "actions", - "messaging" - ], - "story": "US-102", - "obligations": [ - "AUTH", - "IDENTITY", - "COMMANDS", - "LIFECYCLE", - "LIMITS", - "PARITY", - "OBSERVABILITY" - ] - }, - { - "id": "MA-003", - "slug": "case-tracker", - "root": "docs/helix/reference-apps/case-tracker", - "ui": "typescript", - "modules": [ - "tables", - "graphs", - "actions" - ], - "story": "US-103", - "obligations": [ - "AUTH", - "IDENTITY", - "COMMANDS", - "LIFECYCLE", - "LIMITS", - "PARITY", - "OBSERVABILITY" - ] - }, - { - "id": "MA-004", - "slug": "evidence-library", - "root": "docs/helix/reference-apps/evidence-library", - "ui": "typescript", - "modules": [ - "tables", - "storage", - "actions" - ], - "story": "US-104", - "obligations": [ - "AUTH", - "IDENTITY", - "COMMANDS", - "LIFECYCLE", - "LIMITS", - "PARITY", - "OBSERVABILITY" - ] - }, - { - "id": "MA-005", - "slug": "document-review", - "root": "docs/helix/reference-apps/document-review", - "ui": "typescript", - "modules": [ - "tables", - "storage", - "agents", - "models", - "actions" - ], - "story": "US-105", - "obligations": [ - "AUTH", - "IDENTITY", - "COMMANDS", - "LIFECYCLE", - "LIMITS", - "PARITY", - "OBSERVABILITY" - ] - }, - { - "id": "MA-006", - "slug": "entity-directory", - "root": "docs/helix/reference-apps/entity-directory", - "ui": "typescript", - "modules": [ - "graphs", - "actions" - ], - "story": "US-106", - "obligations": [ - "AUTH", - "IDENTITY", - "COMMANDS", - "LIFECYCLE", - "LIMITS", - "PARITY", - "OBSERVABILITY" - ] - }, - { - "id": "MA-007", - "slug": "knowledge-assistant", - "root": "docs/helix/reference-apps/knowledge-assistant", - "ui": "typescript", - "modules": [ - "tables", - "storage", - "agents", - "models", - "search" - ], - "story": "US-107", - "obligations": [ - "AUTH", - "IDENTITY", - "COMMANDS", - "LIFECYCLE", - "LIMITS", - "PARITY", - "OBSERVABILITY" - ] - }, - { - "id": "MA-008", - "slug": "model-triage", - "root": "docs/helix/reference-apps/model-triage", - "ui": "typescript", - "modules": [ - "tables", - "messaging", - "agents", - "models", - "actions" - ], - "story": "US-108", - "obligations": [ - "AUTH", - "IDENTITY", - "COMMANDS", - "LIFECYCLE", - "LIMITS", - "PARITY", - "OBSERVABILITY" - ] - }, - { - "id": "MA-009", - "slug": "data-reconciliation", - "root": "docs/helix/reference-apps/data-reconciliation", - "ui": "typescript", - "modules": [ - "tables", - "actions", - "jobs" - ], - "story": "US-109", - "obligations": [ - "AUTH", - "IDENTITY", - "COMMANDS", - "LIFECYCLE", - "LIMITS", - "PARITY", - "OBSERVABILITY" - ] - }, - { - "id": "MA-010", - "slug": "scheduled-digest", - "root": "docs/helix/reference-apps/scheduled-digest", - "ui": "typescript", - "modules": [ - "tables", - "jobs", - "storage", - "messaging" - ], - "story": "US-110", - "obligations": [ - "AUTH", - "IDENTITY", - "COMMANDS", - "LIFECYCLE", - "LIMITS", - "PARITY", - "OBSERVABILITY" - ] - }, - { - "id": "MA-011", - "slug": "access-attestation", - "root": "docs/helix/reference-apps/access-attestation", - "ui": "typescript", - "modules": [ - "tables", - "graphs", - "actions" - ], - "story": "US-111", - "obligations": [ - "AUTH", - "IDENTITY", - "COMMANDS", - "LIFECYCLE", - "LIMITS", - "PARITY", - "OBSERVABILITY" - ] - }, - { - "id": "MA-012", - "slug": "service-handoff", - "root": "docs/helix/reference-apps/service-handoff", - "ui": "typescript", - "modules": [ - "graphs", - "services", - "messaging", - "actions" - ], - "story": "US-112", - "obligations": [ - "AUTH", - "IDENTITY", - "COMMANDS", - "LIFECYCLE", - "LIMITS", - "PARITY", - "OBSERVABILITY" - ] - } - ] -} diff --git a/docs/helix/reference-apps/data-reconciliation/.helix.yml b/docs/helix/reference-apps/data-reconciliation/.helix.yml deleted file mode 100644 index 3b21de1..0000000 --- a/docs/helix/reference-apps/data-reconciliation/.helix.yml +++ /dev/null @@ -1,12 +0,0 @@ -{ - "flows": [ - { - "id": "helix", - "root": "specs/" - } - ], - "x-batten-app": { - "id": "MA-009", - "workflow": "../../04-build/batten-app-workflow.md" - } -} diff --git a/docs/helix/reference-apps/data-reconciliation/AGENTS.md b/docs/helix/reference-apps/data-reconciliation/AGENTS.md deleted file mode 100644 index 386a7ba..0000000 --- a/docs/helix/reference-apps/data-reconciliation/AGENTS.md +++ /dev/null @@ -1,19 +0,0 @@ -# Working on Data reconciliation workbench - -Read this directory's `.helix.yml` and engage the installed HELIX skill. This is -application MA-009; governed artifacts belong only in `specs/`. Start with -`specs/01-frame/prd.md`, then the story and test plan. Follow -[the Batten app workflow](../../04-build/batten-app-workflow.md), using templates, -prompts and metadata from the installed HELIX catalog. Do not vendor the catalog. - -Reference app rules are fabricated conformance defaults, not real business policy. -UMF owns models/actions and typed persistence; PostgreSQL 18 and Truss own native -storage/execution. UI is application-authored TypeScript through the public host -client, with room for ux-builder. No direct database/provider access in the UI. -Read applicable SDK contracts through explicit file paths; local artifact IDs -resolve inside this app scope. App specs do not authorize SDK or upstream edits. - -Build only after a scoped app implementation instruction and qualified integration -closure. No credentials, production data, migrations, applies, commits or pushes -without their applicable authorization. Never replace a required failing positive -case with a skip, mock result or changed expected outcome. diff --git a/docs/helix/reference-apps/data-reconciliation/fixtures.json b/docs/helix/reference-apps/data-reconciliation/fixtures.json deleted file mode 100644 index e939b37..0000000 --- a/docs/helix/reference-apps/data-reconciliation/fixtures.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "application": "MA-009", - "record": { - "id": "fabricated-data-reconciliation-record", - "owner": "actor-a", - "state": "unmatched" - }, - "actors": { - "permitted": "actor-a", - "foreign": "actor-b", - "independent_reviewer": "actor-c" - } -} diff --git a/docs/helix/reference-apps/data-reconciliation/specs/01-frame/features/FEAT-109-business-journey.md b/docs/helix/reference-apps/data-reconciliation/specs/01-frame/features/FEAT-109-business-journey.md deleted file mode 100644 index 2b3b236..0000000 --- a/docs/helix/reference-apps/data-reconciliation/specs/01-frame/features/FEAT-109-business-journey.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -ddx: - id: FEAT-109 - type: feature-specification - activity: frame - authoring: - home: repo - links: - - id: data-reconciliation.prd - kind: derived_from ---- - -# FEAT-109: Governed business journey - -**Feature ID**: FEAT-109 -**Priority**: P0 -**Owner**: Erik LaBianca -**Covered PRD Subsystem(s)**: Governed business journey -**Covered PRD Requirements**: FR-1, FR-2, FR-3, FR-4 -**Cross-Subsystem Rationale**: None; one app-specific journey. - -## Overview - -The app must complete its PRD's business journey through authorized platform -operations and preserve its independently stated business invariant. - -## Ideal Future State - -The actor can rely on the final result or safely reconcile original uncertain -work across supported surfaces, without rebuilding integration or policy. - -## Problem Statement - -Passing component calls do not prove this app's domain outcome. The PRD defines -its users, concepts and rule; the story owns its observable acceptance criteria. - -## Requirements - -- FR-1 must complete the specific app journey in the PRD. -- FR-2 must enforce the PRD's distinct business invariant. -- FR-3 must preserve current permission and actual/uncertain effects on failure. -- FR-4 must preserve meaning and attribution across qualified surfaces/cohorts. - -### Non-Functional Requirements - -No private provider access or client-derived authority. Bounded native work and -safe diagnostics follow SDK CONTRACT-011; Erik supplies production workload and -latency/cost budgets. No numeric operating target is assumed. - -## User Stories - -[US-109](../user-stories/US-109-journey.md) owns the acceptance criteria. - -## Edge Cases and Error Handling - -Foreign/revoked actors, changed inputs, interrupted commands and unavailable -providers retain the story's explicit safe outcomes. No silent scripted replacement. - -## Constraints and Assumptions - -Fabricated business defaults, native UMF data/actions, PostgreSQL 18/Truss when -required, and authored TypeScript UI. Exact platform subset needs qualification. - -## Dependencies - -Local PRD FR-1–4 and SDK CONTRACT-003/004/005/011 through explicit file references -in the app test plan. The app has no authority to modify those shared contracts. - -## Out of Scope - -New platform engines, privileged UI-side data access, production policy or deployment. diff --git a/docs/helix/reference-apps/data-reconciliation/specs/01-frame/prd.md b/docs/helix/reference-apps/data-reconciliation/specs/01-frame/prd.md deleted file mode 100644 index 9ff5cca..0000000 --- a/docs/helix/reference-apps/data-reconciliation/specs/01-frame/prd.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -ddx: - id: data-reconciliation.prd - type: prd - activity: frame - authoring: - home: repo ---- - -# Data reconciliation workbench - -## Summary - -MA-009 is a fabricated enterprise reference app for a data steward and reconciliation reviewer. It exercises -compare bounded source snapshots, inspect discrepancies, approve a resolution and inspect the applied result. Its purpose is to qualify a useful business journey -through Batten's platform integrations, rather than introduce a new engine. - -## Problem and Goals - -### Problem - -Users need an attributable business result across data, permission and failure -boundaries. A successful component call alone cannot establish this workflow. - -### Goals - -- Complete the stated journey while preserving current access and original identity. -- Detect the app-specific business invariant: A resolution is bound to the compared source revisions; a later change invalidates the proposed repair. -- Reproduce denied, stale, duplicate, cancelled and uncertain outcomes independently - of the host implementation. - -### Non-Goals - -Large transformations stay in existing platform jobs; no new ETL engine. - -## Users and Scope - -The data steward and reconciliation reviewer roles are assumed reference roles selected for this corpus, not -validated research personas. Erik owns real user validation and policy changes. -Business concepts: SourceRow, Difference, Resolution. All records and actors are fabricated. - -## Requirements - -### Must Have (P0) - -- Complete the journey and enforce its app-specific business invariant. -- Apply shared authority, lifecycle and evidence obligations without disclosure. -- Qualify required native integrations and real UI outcomes before a support claim. - -## Functional Requirements - -### Subsystem: Governed business journey - -Feature owner: FEAT-109. - -- **FR-1** — Compare bounded source snapshots, inspect discrepancies, approve a resolution and inspect the applied result. -- **FR-2** — A resolution is bound to the compared source revisions; a later change invalidates the proposed repair. -- **FR-3** — Permission loss, stale inputs and interrupted work must preserve - authorized visibility, actual effects and the original uncertain outcome. -- **FR-4** — Supported surfaces and candidate cohorts must preserve the same - business semantics with attributable decisions and safe diagnostics. - -## Acceptance Test Sketches - -| Requirement | Scenario | Input | Expected Output | -| --- | --- | --- | --- | -| FR-1 | Main journey | two fabricated source snapshots and a conflicting field | approved difference resolves with original source lineage | -| FR-2 | Business boundary | change a source after comparison and before apply | repair refuses stale inputs and preserves the new source value | -| FR-3 | Foreign or revoked actor | Original fixture with changed authority | Safe refusal; no hidden data or new business effect | -| FR-4 | Alternate client/cohort | Same app and business inputs | Same authorized outcome or explicit unsupported refusal | - -## Technical Context - -Integration requirements: tables,actions,jobs. These are corpus tags, not installable -module names or a claim that every adapter exists. Use UMF typed access with -PostgreSQL 18 for tables and Truss for graphs. Initial UI is a TypeScript browser -app under SDK ADR-015 and CONTRACT-005. No frontend framework is selected here. -Platform contracts are explicit dependencies in the test plan; original native -model/action packages require exact source and cohort qualification before build. - -## Constraints, Assumptions, Dependencies - -- Shared obligations in SDK CONTRACT-011 apply in full. -- Fixture states and role separation are conformance defaults, not production rules. -- Same local PostgreSQL instance does not imply one transaction across all services. -- Native authoring, host/client and required provider integrations precede app execution. - -## Risks - -| Risk | Probability | Impact | Mitigation | -| --- | --- | --- | --- | -| Fixture mistaken for a running app | Unmeasured | False support claim | Separate inventory from full execution qualification | -| UI or hook bypasses policy | Unmeasured | Unauthorized outcome | Public host boundary and server-side current authority checks | -| Backend changes business meaning | Unmeasured | Invalid result | Independent expectations and candidate-cohort replay | - -## Open Questions - -Erik supplies workload, latency/cost limits, real retention rules and production -policy. Those values block production qualification, not fabricated specification. - -## Success Criteria - -The governing story's positive and negative criteria pass through exact installed -native integrations and real client/host paths, with safe required telemetry. -The corpus inventory alone establishes none of those execution claims. diff --git a/docs/helix/reference-apps/data-reconciliation/specs/01-frame/user-stories/US-109-journey.md b/docs/helix/reference-apps/data-reconciliation/specs/01-frame/user-stories/US-109-journey.md deleted file mode 100644 index 206f8bd..0000000 --- a/docs/helix/reference-apps/data-reconciliation/specs/01-frame/user-stories/US-109-journey.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -ddx: - id: US-109 - type: user-stories - activity: frame - authoring: - home: repo - links: - - id: data-reconciliation.prd - kind: derived_from ---- - -# US-109: Complete the data reconciliation workbench journey - -**Feature**: FEAT-109 — Governed business journey -**Feature Requirements**: Reference-app business journey. -**PRD Requirements**: FR-1, FR-2, FR-3, FR-4. -**Priority**: P0. - -## Story - -**As a** data steward and reconciliation reviewer -**I want** to complete the governed business journey -**So that** I can rely on its authorized result and recover safely after interruption. - -## Context - -This is application MA-009. Business rules below are explicit fabricated defaults. -They remain independent of whichever platform implementation is being qualified. - -## Walkthrough - -1. The actor opens permitted work and inspects its current state and revision. -2. The actor follows the journey: Compare bounded source snapshots, inspect discrepancies, approve a resolution and inspect the applied result. -3. The host checks current authority and original operation identity. -4. The actor observes the result, or reconciles the original uncertain attempt. - -## Acceptance Criteria - -- [ ] **US-109-AC1** — Given two fabricated source snapshots and a conflicting field, when the actor performs the journey, then approved difference resolves with original source lineage. -- [ ] **US-109-AC2** — Given the app's business invariant, when actors change a source after comparison and before apply, then repair refuses stale inputs and preserves the new source value. -- [ ] **US-109-AC3** — Given a foreign, anonymous or revoked actor, when they attempt the same operation or continuation, then no private result or unauthorized mutation is disclosed. -- [ ] **US-109-AC4** — Given response loss or cancellation, when the actor inspects original work, then actual effects and uncertainty remain attributable without a fresh blind command. -- [ ] **US-109-AC5** — Given the same business inputs on another supported surface or cohort, when the journey runs, then meaning and authority are preserved; unsupported required behavior refuses explicitly. - -## Edge Cases - -- Empty permitted data returns an authorized empty state, not hidden counts. -- Dependency failure exposes a safe outcome; a scripted replacement is not selected. -- Query and inspection do not mutate business records or retry uncertain commands. - -## Test Scenarios - -| Scenario | AC ID | Input / State | Action | Expected Result | -| --- | --- | --- | --- | --- | -| Main journey | US-109-AC1 | two fabricated source snapshots and a conflicting field | compare, review and conditionally apply a repair | approved difference resolves with original source lineage | -| Business invariant | US-109-AC2 | Same original fixture | change a source after comparison and before apply | repair refuses stale inputs and preserves the new source value | -| Current authority | US-109-AC3 | Fixture foreign actor | Attempt and continue work | Safe denial without disclosure | -| Lost response | US-109-AC4 | Original possibly effective attempt | Observe original identity | Actual or uncertain outcome, no blind replay | -| Cohort parity | US-109-AC5 | Same semantic inputs | Exercise supported client/host | Same meaning or explicit refusal | - -## Dependencies - -Local PRD FR-1–4; SDK CONTRACT-003/004/005/011. Native platform model/action -contracts must be selected before executable app construction. Corpus tags: -tables,actions,jobs. Their presence requests support and grants no authority. - -## Out of Scope - -Large transformations stay in existing platform jobs; no new ETL engine. Full platform implementation is not authorized by this app story. diff --git a/docs/helix/reference-apps/data-reconciliation/specs/03-test/test-plan.md b/docs/helix/reference-apps/data-reconciliation/specs/03-test/test-plan.md deleted file mode 100644 index 6ca6277..0000000 --- a/docs/helix/reference-apps/data-reconciliation/specs/03-test/test-plan.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -ddx: - id: TP-109 - type: test-plan - activity: test - authoring: - home: repo - links: - - id: US-109 - kind: informed_by ---- - -# Data reconciliation workbench: conformance allocation - -## Strategy - -**Goal**: Qualify MA-009's full authorized journey and distinct business invariant. -**Out of scope**: Large transformations stay in existing platform jobs; no new ETL engine. -Use shared runner obligations from SDK CONTRACT-011 and preserve the independent -story expectations. No app result may be inferred from inventory validation. - -## Framework Selection & Cost - -| Layer | Framework | Justification | CI Time Impact | Maintenance Burden | -| --- | --- | --- | --- | --- | -| Inventory | Existing stdlib corpus checker | Exact scope/fixture integrity without app loading | Measured by shared command; no estimate supplied | Shared | -| Native actions | Qualified UMF/existing provider conformance | Reuse native ORM/graph semantics rather than duplicate them | Unknown; Erik owns budget | One shared runner, app data | -| UI journey | Real TypeScript client/browser harness | Authored UI requires independent observable journeys | Unknown; harness selection precedes app build | App acceptance scenarios | -| Model behavior where requested | Deterministic scripted API plus separate live API cut | Reproducible rules and actual integration prove different properties | Unknown | Fixture/model cohort scoped | - -## Critical Paths (P0) - -1. Story FR-1/2: approved difference resolves with original source lineage; invariant: A resolution is bound to the compared source revisions; a later change invalidates the proposed repair. -2. Story FR-3: unauthorized, stale, duplicate and uncertain work never loses its - actual authority or outcome boundary. -3. Story FR-4: exact supported client/cohort preserves business meaning and safe - diagnostics, including current identity on continuation. - -## Acceptance Criteria Layer Allocation - -| AC class / source | Story Test Plan | Primary Layer | Why this layer | -| --- | --- | --- | --- | -| US-109 main business and invariant classes | App story test plan at build handoff | Public client/host/native provider journey | Only full path proves business result | -| US-109 permission/recovery classes | Same app story test plan | Native integration | Current authority and durable effects cross boundaries | -| US-109 surface/candidate classes | Same app story test plan | Real browser plus separate CLI parity observation | TypeScript and server behavior require distinct observations | - -The build handoff must author the per-criterion story test plan and native model/ -technical design from installed HELIX templates before executable app code. -No preselected test function or framework is fabricated before that contract exists. - -## Secondary Paths (P1-P2) - -Optional UI polish cannot weaken required denial, uncertainty or accessibility -behavior. There is no optional escape from an active P0 criterion. - -## Test Data Strategy - -Use `../../fixtures.json` and the story's independent Given/When/Then examples. -Create isolated native namespaces with explicit PostgreSQL 18/Truss bindings and -scoped local identity. No production snapshot, credentials or inferred grants. -Every generated/native input retains its app/model/refinement identity. - -## Known Gaps - -Complete app execution requires qualified host/client, native model artifacts, -selected integrations and a trusted evidence runner. These are qualification -blockers, not accepted runtime risk or passing skips. SDK component storage -checks qualify only their own boundary. TypeScript UI is authored, not generated -from a declarative UI model. UI harness selection belongs to the app build design. - -## Build Commands - -From the SDK repository root: - -```sh -python scripts/check_micro_apps.py -python scripts/check_micro_apps.py --require-execution -``` - -The first command verifies inventory only; the second must refuse absent complete -app execution evidence. SDK platform dependencies are explicit file references: -`../../../../02-design/contracts/CONTRACT-003-composition.md`, -`../../../../02-design/contracts/CONTRACT-004-host-profiles.md`, -`../../../../02-design/contracts/CONTRACT-005-ux-builder-binding.md`, and -`../../../../02-design/contracts/CONTRACT-011-micro-app-conformance.md`. - -**Blocking gate**: Every active story criterion and shared obligation must have -trusted passing evidence for exact inputs before this app is called qualified. -No test-function ceiling increase; parameterize cases in shared machinery. - -## Diagnostic Test Strategy - -Exercise actual safe host audit and required telemetry across client, host and -providers, including a real receiver, refusal, retries, capture loss and shutdown. -A mocked exporter or parsed JSON is not receiver qualification. Erik supplies -workload and diagnostic overhead budgets before production qualification. diff --git a/docs/helix/reference-apps/document-review/.helix.yml b/docs/helix/reference-apps/document-review/.helix.yml deleted file mode 100644 index d26fdd8..0000000 --- a/docs/helix/reference-apps/document-review/.helix.yml +++ /dev/null @@ -1,12 +0,0 @@ -{ - "flows": [ - { - "id": "helix", - "root": "specs/" - } - ], - "x-batten-app": { - "id": "MA-005", - "workflow": "../../04-build/batten-app-workflow.md" - } -} diff --git a/docs/helix/reference-apps/document-review/AGENTS.md b/docs/helix/reference-apps/document-review/AGENTS.md deleted file mode 100644 index 4757596..0000000 --- a/docs/helix/reference-apps/document-review/AGENTS.md +++ /dev/null @@ -1,19 +0,0 @@ -# Working on Assisted document review - -Read this directory's `.helix.yml` and engage the installed HELIX skill. This is -application MA-005; governed artifacts belong only in `specs/`. Start with -`specs/01-frame/prd.md`, then the story and test plan. Follow -[the Batten app workflow](../../04-build/batten-app-workflow.md), using templates, -prompts and metadata from the installed HELIX catalog. Do not vendor the catalog. - -Reference app rules are fabricated conformance defaults, not real business policy. -UMF owns models/actions and typed persistence; PostgreSQL 18 and Truss own native -storage/execution. UI is application-authored TypeScript through the public host -client, with room for ux-builder. No direct database/provider access in the UI. -Read applicable SDK contracts through explicit file paths; local artifact IDs -resolve inside this app scope. App specs do not authorize SDK or upstream edits. - -Build only after a scoped app implementation instruction and qualified integration -closure. No credentials, production data, migrations, applies, commits or pushes -without their applicable authorization. Never replace a required failing positive -case with a skip, mock result or changed expected outcome. diff --git a/docs/helix/reference-apps/document-review/fixtures.json b/docs/helix/reference-apps/document-review/fixtures.json deleted file mode 100644 index 8ca4563..0000000 --- a/docs/helix/reference-apps/document-review/fixtures.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "application": "MA-005", - "record": { - "id": "fabricated-document-review-record", - "owner": "actor-a", - "state": "received" - }, - "actors": { - "permitted": "actor-a", - "foreign": "actor-b", - "independent_reviewer": "actor-c" - } -} diff --git a/docs/helix/reference-apps/document-review/specs/01-frame/features/FEAT-105-business-journey.md b/docs/helix/reference-apps/document-review/specs/01-frame/features/FEAT-105-business-journey.md deleted file mode 100644 index c8b7b6f..0000000 --- a/docs/helix/reference-apps/document-review/specs/01-frame/features/FEAT-105-business-journey.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -ddx: - id: FEAT-105 - type: feature-specification - activity: frame - authoring: - home: repo - links: - - id: document-review.prd - kind: derived_from ---- - -# FEAT-105: Governed business journey - -**Feature ID**: FEAT-105 -**Priority**: P0 -**Owner**: Erik LaBianca -**Covered PRD Subsystem(s)**: Governed business journey -**Covered PRD Requirements**: FR-1, FR-2, FR-3, FR-4 -**Cross-Subsystem Rationale**: None; one app-specific journey. - -## Overview - -The app must complete its PRD's business journey through authorized platform -operations and preserve its independently stated business invariant. - -## Ideal Future State - -The actor can rely on the final result or safely reconcile original uncertain -work across supported surfaces, without rebuilding integration or policy. - -## Problem Statement - -Passing component calls do not prove this app's domain outcome. The PRD defines -its users, concepts and rule; the story owns its observable acceptance criteria. - -## Requirements - -- FR-1 must complete the specific app journey in the PRD. -- FR-2 must enforce the PRD's distinct business invariant. -- FR-3 must preserve current permission and actual/uncertain effects on failure. -- FR-4 must preserve meaning and attribution across qualified surfaces/cohorts. - -### Non-Functional Requirements - -No private provider access or client-derived authority. Bounded native work and -safe diagnostics follow SDK CONTRACT-011; Erik supplies production workload and -latency/cost budgets. No numeric operating target is assumed. - -## User Stories - -[US-105](../user-stories/US-105-journey.md) owns the acceptance criteria. - -## Edge Cases and Error Handling - -Foreign/revoked actors, changed inputs, interrupted commands and unavailable -providers retain the story's explicit safe outcomes. No silent scripted replacement. - -## Constraints and Assumptions - -Fabricated business defaults, native UMF data/actions, PostgreSQL 18/Truss when -required, and authored TypeScript UI. Exact platform subset needs qualification. - -## Dependencies - -Local PRD FR-1–4 and SDK CONTRACT-003/004/005/011 through explicit file references -in the app test plan. The app has no authority to modify those shared contracts. - -## Out of Scope - -New platform engines, privileged UI-side data access, production policy or deployment. diff --git a/docs/helix/reference-apps/document-review/specs/01-frame/prd.md b/docs/helix/reference-apps/document-review/specs/01-frame/prd.md deleted file mode 100644 index d0d81bb..0000000 --- a/docs/helix/reference-apps/document-review/specs/01-frame/prd.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -ddx: - id: document-review.prd - type: prd - activity: frame - authoring: - home: repo ---- - -# Assisted document review - -## Summary - -MA-005 is a fabricated enterprise reference app for a reviewer and final decision owner. It exercises -upload a fabricated document, request extraction, inspect provenance, correct suggestions and accept a reviewed result. Its purpose is to qualify a useful business journey -through Batten's platform integrations, rather than introduce a new engine. - -## Problem and Goals - -### Problem - -Users need an attributable business result across data, permission and failure -boundaries. A successful component call alone cannot establish this workflow. - -### Goals - -- Complete the stated journey while preserving current access and original identity. -- Detect the app-specific business invariant: Model output is an untrusted suggestion; only an authorized human decision updates accepted facts. -- Reproduce denied, stale, duplicate, cancelled and uncertain outcomes independently - of the host implementation. - -### Non-Goals - -No legal opinion, OCR engine or provider-independent model quality guarantee. - -## Users and Scope - -The reviewer and final decision owner roles are assumed reference roles selected for this corpus, not -validated research personas. Erik owns real user validation and policy changes. -Business concepts: Document, Suggestion, ReviewDecision. All records and actors are fabricated. - -## Requirements - -### Must Have (P0) - -- Complete the journey and enforce its app-specific business invariant. -- Apply shared authority, lifecycle and evidence obligations without disclosure. -- Qualify required native integrations and real UI outcomes before a support claim. - -## Functional Requirements - -### Subsystem: Governed business journey - -Feature owner: FEAT-105. - -- **FR-1** — Upload a fabricated document, request extraction, inspect provenance, correct suggestions and accept a reviewed result. -- **FR-2** — Model output is an untrusted suggestion; only an authorized human decision updates accepted facts. -- **FR-3** — Permission loss, stale inputs and interrupted work must preserve - authorized visibility, actual effects and the original uncertain outcome. -- **FR-4** — Supported surfaces and candidate cohorts must preserve the same - business semantics with attributable decisions and safe diagnostics. - -## Acceptance Test Sketches - -| Requirement | Scenario | Input | Expected Output | -| --- | --- | --- | --- | -| FR-1 | Main journey | document with fabricated content and a bounded model request | accepted facts retain original document and human decision provenance | -| FR-2 | Business boundary | model returns an unsupported factual assertion or unavailable response | unsupported suggestions remain unaccepted; failure exposes no private prompt or credentials | -| FR-3 | Foreign or revoked actor | Original fixture with changed authority | Safe refusal; no hidden data or new business effect | -| FR-4 | Alternate client/cohort | Same app and business inputs | Same authorized outcome or explicit unsupported refusal | - -## Technical Context - -Integration requirements: tables,storage,agents,models,actions. These are corpus tags, not installable -module names or a claim that every adapter exists. Use UMF typed access with -PostgreSQL 18 for tables and Truss for graphs. Initial UI is a TypeScript browser -app under SDK ADR-015 and CONTRACT-005. No frontend framework is selected here. -Platform contracts are explicit dependencies in the test plan; original native -model/action packages require exact source and cohort qualification before build. - -## Constraints, Assumptions, Dependencies - -- Shared obligations in SDK CONTRACT-011 apply in full. -- Fixture states and role separation are conformance defaults, not production rules. -- Same local PostgreSQL instance does not imply one transaction across all services. -- Native authoring, host/client and required provider integrations precede app execution. - -## Risks - -| Risk | Probability | Impact | Mitigation | -| --- | --- | --- | --- | -| Fixture mistaken for a running app | Unmeasured | False support claim | Separate inventory from full execution qualification | -| UI or hook bypasses policy | Unmeasured | Unauthorized outcome | Public host boundary and server-side current authority checks | -| Backend changes business meaning | Unmeasured | Invalid result | Independent expectations and candidate-cohort replay | - -## Open Questions - -Erik supplies workload, latency/cost limits, real retention rules and production -policy. Those values block production qualification, not fabricated specification. - -## Success Criteria - -The governing story's positive and negative criteria pass through exact installed -native integrations and real client/host paths, with safe required telemetry. -The corpus inventory alone establishes none of those execution claims. diff --git a/docs/helix/reference-apps/document-review/specs/01-frame/user-stories/US-105-journey.md b/docs/helix/reference-apps/document-review/specs/01-frame/user-stories/US-105-journey.md deleted file mode 100644 index a84b7d3..0000000 --- a/docs/helix/reference-apps/document-review/specs/01-frame/user-stories/US-105-journey.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -ddx: - id: US-105 - type: user-stories - activity: frame - authoring: - home: repo - links: - - id: document-review.prd - kind: derived_from ---- - -# US-105: Complete the assisted document review journey - -**Feature**: FEAT-105 — Governed business journey -**Feature Requirements**: Reference-app business journey. -**PRD Requirements**: FR-1, FR-2, FR-3, FR-4. -**Priority**: P0. - -## Story - -**As a** reviewer and final decision owner -**I want** to complete the governed business journey -**So that** I can rely on its authorized result and recover safely after interruption. - -## Context - -This is application MA-005. Business rules below are explicit fabricated defaults. -They remain independent of whichever platform implementation is being qualified. - -## Walkthrough - -1. The actor opens permitted work and inspects its current state and revision. -2. The actor follows the journey: Upload a fabricated document, request extraction, inspect provenance, correct suggestions and accept a reviewed result. -3. The host checks current authority and original operation identity. -4. The actor observes the result, or reconciles the original uncertain attempt. - -## Acceptance Criteria - -- [ ] **US-105-AC1** — Given document with fabricated content and a bounded model request, when the actor performs the journey, then accepted facts retain original document and human decision provenance. -- [ ] **US-105-AC2** — Given the app's business invariant, when actors model returns an unsupported factual assertion or unavailable response, then unsupported suggestions remain unaccepted; failure exposes no private prompt or credentials. -- [ ] **US-105-AC3** — Given a foreign, anonymous or revoked actor, when they attempt the same operation or continuation, then no private result or unauthorized mutation is disclosed. -- [ ] **US-105-AC4** — Given response loss or cancellation, when the actor inspects original work, then actual effects and uncertainty remain attributable without a fresh blind command. -- [ ] **US-105-AC5** — Given the same business inputs on another supported surface or cohort, when the journey runs, then meaning and authority are preserved; unsupported required behavior refuses explicitly. - -## Edge Cases - -- Empty permitted data returns an authorized empty state, not hidden counts. -- Dependency failure exposes a safe outcome; a scripted replacement is not selected. -- Query and inspection do not mutate business records or retry uncertain commands. - -## Test Scenarios - -| Scenario | AC ID | Input / State | Action | Expected Result | -| --- | --- | --- | --- | --- | -| Main journey | US-105-AC1 | document with fabricated content and a bounded model request | extract suggestions then accept a corrected result | accepted facts retain original document and human decision provenance | -| Business invariant | US-105-AC2 | Same original fixture | model returns an unsupported factual assertion or unavailable response | unsupported suggestions remain unaccepted; failure exposes no private prompt or credentials | -| Current authority | US-105-AC3 | Fixture foreign actor | Attempt and continue work | Safe denial without disclosure | -| Lost response | US-105-AC4 | Original possibly effective attempt | Observe original identity | Actual or uncertain outcome, no blind replay | -| Cohort parity | US-105-AC5 | Same semantic inputs | Exercise supported client/host | Same meaning or explicit refusal | - -## Dependencies - -Local PRD FR-1–4; SDK CONTRACT-003/004/005/011. Native platform model/action -contracts must be selected before executable app construction. Corpus tags: -tables,storage,agents,models,actions. Their presence requests support and grants no authority. - -## Out of Scope - -No legal opinion, OCR engine or provider-independent model quality guarantee. Full platform implementation is not authorized by this app story. diff --git a/docs/helix/reference-apps/document-review/specs/03-test/test-plan.md b/docs/helix/reference-apps/document-review/specs/03-test/test-plan.md deleted file mode 100644 index 403edc8..0000000 --- a/docs/helix/reference-apps/document-review/specs/03-test/test-plan.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -ddx: - id: TP-105 - type: test-plan - activity: test - authoring: - home: repo - links: - - id: US-105 - kind: informed_by ---- - -# Assisted document review: conformance allocation - -## Strategy - -**Goal**: Qualify MA-005's full authorized journey and distinct business invariant. -**Out of scope**: No legal opinion, OCR engine or provider-independent model quality guarantee. -Use shared runner obligations from SDK CONTRACT-011 and preserve the independent -story expectations. No app result may be inferred from inventory validation. - -## Framework Selection & Cost - -| Layer | Framework | Justification | CI Time Impact | Maintenance Burden | -| --- | --- | --- | --- | --- | -| Inventory | Existing stdlib corpus checker | Exact scope/fixture integrity without app loading | Measured by shared command; no estimate supplied | Shared | -| Native actions | Qualified UMF/existing provider conformance | Reuse native ORM/graph semantics rather than duplicate them | Unknown; Erik owns budget | One shared runner, app data | -| UI journey | Real TypeScript client/browser harness | Authored UI requires independent observable journeys | Unknown; harness selection precedes app build | App acceptance scenarios | -| Model behavior where requested | Deterministic scripted API plus separate live API cut | Reproducible rules and actual integration prove different properties | Unknown | Fixture/model cohort scoped | - -## Critical Paths (P0) - -1. Story FR-1/2: accepted facts retain original document and human decision provenance; invariant: Model output is an untrusted suggestion; only an authorized human decision updates accepted facts. -2. Story FR-3: unauthorized, stale, duplicate and uncertain work never loses its - actual authority or outcome boundary. -3. Story FR-4: exact supported client/cohort preserves business meaning and safe - diagnostics, including current identity on continuation. - -## Acceptance Criteria Layer Allocation - -| AC class / source | Story Test Plan | Primary Layer | Why this layer | -| --- | --- | --- | --- | -| US-105 main business and invariant classes | App story test plan at build handoff | Public client/host/native provider journey | Only full path proves business result | -| US-105 permission/recovery classes | Same app story test plan | Native integration | Current authority and durable effects cross boundaries | -| US-105 surface/candidate classes | Same app story test plan | Real browser plus separate CLI parity observation | TypeScript and server behavior require distinct observations | - -The build handoff must author the per-criterion story test plan and native model/ -technical design from installed HELIX templates before executable app code. -No preselected test function or framework is fabricated before that contract exists. - -## Secondary Paths (P1-P2) - -Optional UI polish cannot weaken required denial, uncertainty or accessibility -behavior. There is no optional escape from an active P0 criterion. - -## Test Data Strategy - -Use `../../fixtures.json` and the story's independent Given/When/Then examples. -Create isolated native namespaces with explicit PostgreSQL 18/Truss bindings and -scoped local identity. No production snapshot, credentials or inferred grants. -Every generated/native input retains its app/model/refinement identity. - -## Known Gaps - -Complete app execution requires qualified host/client, native model artifacts, -selected integrations and a trusted evidence runner. These are qualification -blockers, not accepted runtime risk or passing skips. SDK component storage -checks qualify only their own boundary. TypeScript UI is authored, not generated -from a declarative UI model. UI harness selection belongs to the app build design. - -## Build Commands - -From the SDK repository root: - -```sh -python scripts/check_micro_apps.py -python scripts/check_micro_apps.py --require-execution -``` - -The first command verifies inventory only; the second must refuse absent complete -app execution evidence. SDK platform dependencies are explicit file references: -`../../../../02-design/contracts/CONTRACT-003-composition.md`, -`../../../../02-design/contracts/CONTRACT-004-host-profiles.md`, -`../../../../02-design/contracts/CONTRACT-005-ux-builder-binding.md`, and -`../../../../02-design/contracts/CONTRACT-011-micro-app-conformance.md`. - -**Blocking gate**: Every active story criterion and shared obligation must have -trusted passing evidence for exact inputs before this app is called qualified. -No test-function ceiling increase; parameterize cases in shared machinery. - -## Diagnostic Test Strategy - -Exercise actual safe host audit and required telemetry across client, host and -providers, including a real receiver, refusal, retries, capture loss and shutdown. -A mocked exporter or parsed JSON is not receiver qualification. Erik supplies -workload and diagnostic overhead budgets before production qualification. diff --git a/docs/helix/reference-apps/entity-directory/.helix.yml b/docs/helix/reference-apps/entity-directory/.helix.yml deleted file mode 100644 index 057ea23..0000000 --- a/docs/helix/reference-apps/entity-directory/.helix.yml +++ /dev/null @@ -1,12 +0,0 @@ -{ - "flows": [ - { - "id": "helix", - "root": "specs/" - } - ], - "x-batten-app": { - "id": "MA-006", - "workflow": "../../04-build/batten-app-workflow.md" - } -} diff --git a/docs/helix/reference-apps/entity-directory/AGENTS.md b/docs/helix/reference-apps/entity-directory/AGENTS.md deleted file mode 100644 index d046c96..0000000 --- a/docs/helix/reference-apps/entity-directory/AGENTS.md +++ /dev/null @@ -1,19 +0,0 @@ -# Working on Entity and relationship directory - -Read this directory's `.helix.yml` and engage the installed HELIX skill. This is -application MA-006; governed artifacts belong only in `specs/`. Start with -`specs/01-frame/prd.md`, then the story and test plan. Follow -[the Batten app workflow](../../04-build/batten-app-workflow.md), using templates, -prompts and metadata from the installed HELIX catalog. Do not vendor the catalog. - -Reference app rules are fabricated conformance defaults, not real business policy. -UMF owns models/actions and typed persistence; PostgreSQL 18 and Truss own native -storage/execution. UI is application-authored TypeScript through the public host -client, with room for ux-builder. No direct database/provider access in the UI. -Read applicable SDK contracts through explicit file paths; local artifact IDs -resolve inside this app scope. App specs do not authorize SDK or upstream edits. - -Build only after a scoped app implementation instruction and qualified integration -closure. No credentials, production data, migrations, applies, commits or pushes -without their applicable authorization. Never replace a required failing positive -case with a skip, mock result or changed expected outcome. diff --git a/docs/helix/reference-apps/entity-directory/fixtures.json b/docs/helix/reference-apps/entity-directory/fixtures.json deleted file mode 100644 index b1c5285..0000000 --- a/docs/helix/reference-apps/entity-directory/fixtures.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "application": "MA-006", - "record": { - "id": "fabricated-entity-directory-record", - "owner": "actor-a", - "state": "registered" - }, - "actors": { - "permitted": "actor-a", - "foreign": "actor-b", - "independent_reviewer": "actor-c" - } -} diff --git a/docs/helix/reference-apps/entity-directory/specs/01-frame/features/FEAT-106-business-journey.md b/docs/helix/reference-apps/entity-directory/specs/01-frame/features/FEAT-106-business-journey.md deleted file mode 100644 index 840fb44..0000000 --- a/docs/helix/reference-apps/entity-directory/specs/01-frame/features/FEAT-106-business-journey.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -ddx: - id: FEAT-106 - type: feature-specification - activity: frame - authoring: - home: repo - links: - - id: entity-directory.prd - kind: derived_from ---- - -# FEAT-106: Governed business journey - -**Feature ID**: FEAT-106 -**Priority**: P0 -**Owner**: Erik LaBianca -**Covered PRD Subsystem(s)**: Governed business journey -**Covered PRD Requirements**: FR-1, FR-2, FR-3, FR-4 -**Cross-Subsystem Rationale**: None; one app-specific journey. - -## Overview - -The app must complete its PRD's business journey through authorized platform -operations and preserve its independently stated business invariant. - -## Ideal Future State - -The actor can rely on the final result or safely reconcile original uncertain -work across supported surfaces, without rebuilding integration or policy. - -## Problem Statement - -Passing component calls do not prove this app's domain outcome. The PRD defines -its users, concepts and rule; the story owns its observable acceptance criteria. - -## Requirements - -- FR-1 must complete the specific app journey in the PRD. -- FR-2 must enforce the PRD's distinct business invariant. -- FR-3 must preserve current permission and actual/uncertain effects on failure. -- FR-4 must preserve meaning and attribution across qualified surfaces/cohorts. - -### Non-Functional Requirements - -No private provider access or client-derived authority. Bounded native work and -safe diagnostics follow SDK CONTRACT-011; Erik supplies production workload and -latency/cost budgets. No numeric operating target is assumed. - -## User Stories - -[US-106](../user-stories/US-106-journey.md) owns the acceptance criteria. - -## Edge Cases and Error Handling - -Foreign/revoked actors, changed inputs, interrupted commands and unavailable -providers retain the story's explicit safe outcomes. No silent scripted replacement. - -## Constraints and Assumptions - -Fabricated business defaults, native UMF data/actions, PostgreSQL 18/Truss when -required, and authored TypeScript UI. Exact platform subset needs qualification. - -## Dependencies - -Local PRD FR-1–4 and SDK CONTRACT-003/004/005/011 through explicit file references -in the app test plan. The app has no authority to modify those shared contracts. - -## Out of Scope - -New platform engines, privileged UI-side data access, production policy or deployment. diff --git a/docs/helix/reference-apps/entity-directory/specs/01-frame/prd.md b/docs/helix/reference-apps/entity-directory/specs/01-frame/prd.md deleted file mode 100644 index e61825c..0000000 --- a/docs/helix/reference-apps/entity-directory/specs/01-frame/prd.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -ddx: - id: entity-directory.prd - type: prd - activity: frame - authoring: - home: repo ---- - -# Entity and relationship directory - -## Summary - -MA-006 is a fabricated enterprise reference app for a directory steward and scoped analyst. It exercises -register an entity, link a related entity, traverse authorized relationships and update approved attributes. Its purpose is to qualify a useful business journey -through Batten's platform integrations, rather than introduce a new engine. - -## Problem and Goals - -### Problem - -Users need an attributable business result across data, permission and failure -boundaries. A successful component call alone cannot establish this workflow. - -### Goals - -- Complete the stated journey while preserving current access and original identity. -- Detect the app-specific business invariant: Hidden entities and relationships cannot leak through traversal, counts or relationship endpoints. -- Reproduce denied, stale, duplicate, cancelled and uncertain outcomes independently - of the host implementation. - -### Non-Goals - -No duplicated ontology/query engine; Truss remains the graph executor. - -## Users and Scope - -The directory steward and scoped analyst roles are assumed reference roles selected for this corpus, not -validated research personas. Erik owns real user validation and policy changes. -Business concepts: Entity, Relationship. All records and actors are fabricated. - -## Requirements - -### Must Have (P0) - -- Complete the journey and enforce its app-specific business invariant. -- Apply shared authority, lifecycle and evidence obligations without disclosure. -- Qualify required native integrations and real UI outcomes before a support claim. - -## Functional Requirements - -### Subsystem: Governed business journey - -Feature owner: FEAT-106. - -- **FR-1** — Register an entity, link a related entity, traverse authorized relationships and update approved attributes. -- **FR-2** — Hidden entities and relationships cannot leak through traversal, counts or relationship endpoints. -- **FR-3** — Permission loss, stale inputs and interrupted work must preserve - authorized visibility, actual effects and the original uncertain outcome. -- **FR-4** — Supported surfaces and candidate cohorts must preserve the same - business semantics with attributable decisions and safe diagnostics. - -## Acceptance Test Sketches - -| Requirement | Scenario | Input | Expected Output | -| --- | --- | --- | --- | -| FR-1 | Main journey | permitted entity plus a separate hidden entity | only authorized attributes and relationships are returned with their original model identity | -| FR-2 | Business boundary | include a path through the hidden entity | no hidden endpoint, property or count is disclosed | -| FR-3 | Foreign or revoked actor | Original fixture with changed authority | Safe refusal; no hidden data or new business effect | -| FR-4 | Alternate client/cohort | Same app and business inputs | Same authorized outcome or explicit unsupported refusal | - -## Technical Context - -Integration requirements: graphs,actions. These are corpus tags, not installable -module names or a claim that every adapter exists. Use UMF typed access with -PostgreSQL 18 for tables and Truss for graphs. Initial UI is a TypeScript browser -app under SDK ADR-015 and CONTRACT-005. No frontend framework is selected here. -Platform contracts are explicit dependencies in the test plan; original native -model/action packages require exact source and cohort qualification before build. - -## Constraints, Assumptions, Dependencies - -- Shared obligations in SDK CONTRACT-011 apply in full. -- Fixture states and role separation are conformance defaults, not production rules. -- Same local PostgreSQL instance does not imply one transaction across all services. -- Native authoring, host/client and required provider integrations precede app execution. - -## Risks - -| Risk | Probability | Impact | Mitigation | -| --- | --- | --- | --- | -| Fixture mistaken for a running app | Unmeasured | False support claim | Separate inventory from full execution qualification | -| UI or hook bypasses policy | Unmeasured | Unauthorized outcome | Public host boundary and server-side current authority checks | -| Backend changes business meaning | Unmeasured | Invalid result | Independent expectations and candidate-cohort replay | - -## Open Questions - -Erik supplies workload, latency/cost limits, real retention rules and production -policy. Those values block production qualification, not fabricated specification. - -## Success Criteria - -The governing story's positive and negative criteria pass through exact installed -native integrations and real client/host paths, with safe required telemetry. -The corpus inventory alone establishes none of those execution claims. diff --git a/docs/helix/reference-apps/entity-directory/specs/01-frame/user-stories/US-106-journey.md b/docs/helix/reference-apps/entity-directory/specs/01-frame/user-stories/US-106-journey.md deleted file mode 100644 index dabb858..0000000 --- a/docs/helix/reference-apps/entity-directory/specs/01-frame/user-stories/US-106-journey.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -ddx: - id: US-106 - type: user-stories - activity: frame - authoring: - home: repo - links: - - id: entity-directory.prd - kind: derived_from ---- - -# US-106: Complete the entity and relationship directory journey - -**Feature**: FEAT-106 — Governed business journey -**Feature Requirements**: Reference-app business journey. -**PRD Requirements**: FR-1, FR-2, FR-3, FR-4. -**Priority**: P0. - -## Story - -**As a** directory steward and scoped analyst -**I want** to complete the governed business journey -**So that** I can rely on its authorized result and recover safely after interruption. - -## Context - -This is application MA-006. Business rules below are explicit fabricated defaults. -They remain independent of whichever platform implementation is being qualified. - -## Walkthrough - -1. The actor opens permitted work and inspects its current state and revision. -2. The actor follows the journey: Register an entity, link a related entity, traverse authorized relationships and update approved attributes. -3. The host checks current authority and original operation identity. -4. The actor observes the result, or reconciles the original uncertain attempt. - -## Acceptance Criteria - -- [ ] **US-106-AC1** — Given permitted entity plus a separate hidden entity, when the actor performs the journey, then only authorized attributes and relationships are returned with their original model identity. -- [ ] **US-106-AC2** — Given the app's business invariant, when actors include a path through the hidden entity, then no hidden endpoint, property or count is disclosed. -- [ ] **US-106-AC3** — Given a foreign, anonymous or revoked actor, when they attempt the same operation or continuation, then no private result or unauthorized mutation is disclosed. -- [ ] **US-106-AC4** — Given response loss or cancellation, when the actor inspects original work, then actual effects and uncertainty remain attributable without a fresh blind command. -- [ ] **US-106-AC5** — Given the same business inputs on another supported surface or cohort, when the journey runs, then meaning and authority are preserved; unsupported required behavior refuses explicitly. - -## Edge Cases - -- Empty permitted data returns an authorized empty state, not hidden counts. -- Dependency failure exposes a safe outcome; a scripted replacement is not selected. -- Query and inspection do not mutate business records or retry uncertain commands. - -## Test Scenarios - -| Scenario | AC ID | Input / State | Action | Expected Result | -| --- | --- | --- | --- | --- | -| Main journey | US-106-AC1 | permitted entity plus a separate hidden entity | query the scoped entity and its permitted relationships | only authorized attributes and relationships are returned with their original model identity | -| Business invariant | US-106-AC2 | Same original fixture | include a path through the hidden entity | no hidden endpoint, property or count is disclosed | -| Current authority | US-106-AC3 | Fixture foreign actor | Attempt and continue work | Safe denial without disclosure | -| Lost response | US-106-AC4 | Original possibly effective attempt | Observe original identity | Actual or uncertain outcome, no blind replay | -| Cohort parity | US-106-AC5 | Same semantic inputs | Exercise supported client/host | Same meaning or explicit refusal | - -## Dependencies - -Local PRD FR-1–4; SDK CONTRACT-003/004/005/011. Native platform model/action -contracts must be selected before executable app construction. Corpus tags: -graphs,actions. Their presence requests support and grants no authority. - -## Out of Scope - -No duplicated ontology/query engine; Truss remains the graph executor. Full platform implementation is not authorized by this app story. diff --git a/docs/helix/reference-apps/entity-directory/specs/03-test/test-plan.md b/docs/helix/reference-apps/entity-directory/specs/03-test/test-plan.md deleted file mode 100644 index 9a917e8..0000000 --- a/docs/helix/reference-apps/entity-directory/specs/03-test/test-plan.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -ddx: - id: TP-106 - type: test-plan - activity: test - authoring: - home: repo - links: - - id: US-106 - kind: informed_by ---- - -# Entity and relationship directory: conformance allocation - -## Strategy - -**Goal**: Qualify MA-006's full authorized journey and distinct business invariant. -**Out of scope**: No duplicated ontology/query engine; Truss remains the graph executor. -Use shared runner obligations from SDK CONTRACT-011 and preserve the independent -story expectations. No app result may be inferred from inventory validation. - -## Framework Selection & Cost - -| Layer | Framework | Justification | CI Time Impact | Maintenance Burden | -| --- | --- | --- | --- | --- | -| Inventory | Existing stdlib corpus checker | Exact scope/fixture integrity without app loading | Measured by shared command; no estimate supplied | Shared | -| Native actions | Qualified UMF/existing provider conformance | Reuse native ORM/graph semantics rather than duplicate them | Unknown; Erik owns budget | One shared runner, app data | -| UI journey | Real TypeScript client/browser harness | Authored UI requires independent observable journeys | Unknown; harness selection precedes app build | App acceptance scenarios | -| Model behavior where requested | Deterministic scripted API plus separate live API cut | Reproducible rules and actual integration prove different properties | Unknown | Fixture/model cohort scoped | - -## Critical Paths (P0) - -1. Story FR-1/2: only authorized attributes and relationships are returned with their original model identity; invariant: Hidden entities and relationships cannot leak through traversal, counts or relationship endpoints. -2. Story FR-3: unauthorized, stale, duplicate and uncertain work never loses its - actual authority or outcome boundary. -3. Story FR-4: exact supported client/cohort preserves business meaning and safe - diagnostics, including current identity on continuation. - -## Acceptance Criteria Layer Allocation - -| AC class / source | Story Test Plan | Primary Layer | Why this layer | -| --- | --- | --- | --- | -| US-106 main business and invariant classes | App story test plan at build handoff | Public client/host/native provider journey | Only full path proves business result | -| US-106 permission/recovery classes | Same app story test plan | Native integration | Current authority and durable effects cross boundaries | -| US-106 surface/candidate classes | Same app story test plan | Real browser plus separate CLI parity observation | TypeScript and server behavior require distinct observations | - -The build handoff must author the per-criterion story test plan and native model/ -technical design from installed HELIX templates before executable app code. -No preselected test function or framework is fabricated before that contract exists. - -## Secondary Paths (P1-P2) - -Optional UI polish cannot weaken required denial, uncertainty or accessibility -behavior. There is no optional escape from an active P0 criterion. - -## Test Data Strategy - -Use `../../fixtures.json` and the story's independent Given/When/Then examples. -Create isolated native namespaces with explicit PostgreSQL 18/Truss bindings and -scoped local identity. No production snapshot, credentials or inferred grants. -Every generated/native input retains its app/model/refinement identity. - -## Known Gaps - -Complete app execution requires qualified host/client, native model artifacts, -selected integrations and a trusted evidence runner. These are qualification -blockers, not accepted runtime risk or passing skips. SDK component storage -checks qualify only their own boundary. TypeScript UI is authored, not generated -from a declarative UI model. UI harness selection belongs to the app build design. - -## Build Commands - -From the SDK repository root: - -```sh -python scripts/check_micro_apps.py -python scripts/check_micro_apps.py --require-execution -``` - -The first command verifies inventory only; the second must refuse absent complete -app execution evidence. SDK platform dependencies are explicit file references: -`../../../../02-design/contracts/CONTRACT-003-composition.md`, -`../../../../02-design/contracts/CONTRACT-004-host-profiles.md`, -`../../../../02-design/contracts/CONTRACT-005-ux-builder-binding.md`, and -`../../../../02-design/contracts/CONTRACT-011-micro-app-conformance.md`. - -**Blocking gate**: Every active story criterion and shared obligation must have -trusted passing evidence for exact inputs before this app is called qualified. -No test-function ceiling increase; parameterize cases in shared machinery. - -## Diagnostic Test Strategy - -Exercise actual safe host audit and required telemetry across client, host and -providers, including a real receiver, refusal, retries, capture loss and shutdown. -A mocked exporter or parsed JSON is not receiver qualification. Erik supplies -workload and diagnostic overhead budgets before production qualification. diff --git a/docs/helix/reference-apps/evidence-library/.helix.yml b/docs/helix/reference-apps/evidence-library/.helix.yml deleted file mode 100644 index 433b917..0000000 --- a/docs/helix/reference-apps/evidence-library/.helix.yml +++ /dev/null @@ -1,12 +0,0 @@ -{ - "flows": [ - { - "id": "helix", - "root": "specs/" - } - ], - "x-batten-app": { - "id": "MA-004", - "workflow": "../../04-build/batten-app-workflow.md" - } -} diff --git a/docs/helix/reference-apps/evidence-library/AGENTS.md b/docs/helix/reference-apps/evidence-library/AGENTS.md deleted file mode 100644 index a2cb23a..0000000 --- a/docs/helix/reference-apps/evidence-library/AGENTS.md +++ /dev/null @@ -1,19 +0,0 @@ -# Working on Evidence and attachment library - -Read this directory's `.helix.yml` and engage the installed HELIX skill. This is -application MA-004; governed artifacts belong only in `specs/`. Start with -`specs/01-frame/prd.md`, then the story and test plan. Follow -[the Batten app workflow](../../04-build/batten-app-workflow.md), using templates, -prompts and metadata from the installed HELIX catalog. Do not vendor the catalog. - -Reference app rules are fabricated conformance defaults, not real business policy. -UMF owns models/actions and typed persistence; PostgreSQL 18 and Truss own native -storage/execution. UI is application-authored TypeScript through the public host -client, with room for ux-builder. No direct database/provider access in the UI. -Read applicable SDK contracts through explicit file paths; local artifact IDs -resolve inside this app scope. App specs do not authorize SDK or upstream edits. - -Build only after a scoped app implementation instruction and qualified integration -closure. No credentials, production data, migrations, applies, commits or pushes -without their applicable authorization. Never replace a required failing positive -case with a skip, mock result or changed expected outcome. diff --git a/docs/helix/reference-apps/evidence-library/fixtures.json b/docs/helix/reference-apps/evidence-library/fixtures.json deleted file mode 100644 index c097d61..0000000 --- a/docs/helix/reference-apps/evidence-library/fixtures.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "application": "MA-004", - "record": { - "id": "fabricated-evidence-library-record", - "owner": "actor-a", - "state": "draft" - }, - "actors": { - "permitted": "actor-a", - "foreign": "actor-b", - "independent_reviewer": "actor-c" - } -} diff --git a/docs/helix/reference-apps/evidence-library/specs/01-frame/features/FEAT-104-business-journey.md b/docs/helix/reference-apps/evidence-library/specs/01-frame/features/FEAT-104-business-journey.md deleted file mode 100644 index dde786c..0000000 --- a/docs/helix/reference-apps/evidence-library/specs/01-frame/features/FEAT-104-business-journey.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -ddx: - id: FEAT-104 - type: feature-specification - activity: frame - authoring: - home: repo - links: - - id: evidence-library.prd - kind: derived_from ---- - -# FEAT-104: Governed business journey - -**Feature ID**: FEAT-104 -**Priority**: P0 -**Owner**: Erik LaBianca -**Covered PRD Subsystem(s)**: Governed business journey -**Covered PRD Requirements**: FR-1, FR-2, FR-3, FR-4 -**Cross-Subsystem Rationale**: None; one app-specific journey. - -## Overview - -The app must complete its PRD's business journey through authorized platform -operations and preserve its independently stated business invariant. - -## Ideal Future State - -The actor can rely on the final result or safely reconcile original uncertain -work across supported surfaces, without rebuilding integration or policy. - -## Problem Statement - -Passing component calls do not prove this app's domain outcome. The PRD defines -its users, concepts and rule; the story owns its observable acceptance criteria. - -## Requirements - -- FR-1 must complete the specific app journey in the PRD. -- FR-2 must enforce the PRD's distinct business invariant. -- FR-3 must preserve current permission and actual/uncertain effects on failure. -- FR-4 must preserve meaning and attribution across qualified surfaces/cohorts. - -### Non-Functional Requirements - -No private provider access or client-derived authority. Bounded native work and -safe diagnostics follow SDK CONTRACT-011; Erik supplies production workload and -latency/cost budgets. No numeric operating target is assumed. - -## User Stories - -[US-104](../user-stories/US-104-journey.md) owns the acceptance criteria. - -## Edge Cases and Error Handling - -Foreign/revoked actors, changed inputs, interrupted commands and unavailable -providers retain the story's explicit safe outcomes. No silent scripted replacement. - -## Constraints and Assumptions - -Fabricated business defaults, native UMF data/actions, PostgreSQL 18/Truss when -required, and authored TypeScript UI. Exact platform subset needs qualification. - -## Dependencies - -Local PRD FR-1–4 and SDK CONTRACT-003/004/005/011 through explicit file references -in the app test plan. The app has no authority to modify those shared contracts. - -## Out of Scope - -New platform engines, privileged UI-side data access, production policy or deployment. diff --git a/docs/helix/reference-apps/evidence-library/specs/01-frame/prd.md b/docs/helix/reference-apps/evidence-library/specs/01-frame/prd.md deleted file mode 100644 index 3bb99bd..0000000 --- a/docs/helix/reference-apps/evidence-library/specs/01-frame/prd.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -ddx: - id: evidence-library.prd - type: prd - activity: frame - authoring: - home: repo ---- - -# Evidence and attachment library - -## Summary - -MA-004 is a fabricated enterprise reference app for a contributor and permitted reader. It exercises -upload fabricated evidence, verify bytes, link its immutable reference to a record and retrieve it. Its purpose is to qualify a useful business journey -through Batten's platform integrations, rather than introduce a new engine. - -## Problem and Goals - -### Problem - -Users need an attributable business result across data, permission and failure -boundaries. A successful component call alone cannot establish this workflow. - -### Goals - -- Complete the stated journey while preserving current access and original identity. -- Detect the app-specific business invariant: Metadata must never claim available evidence before the qualified object exists; uncertain row/blob outcomes remain reconcilable. -- Reproduce denied, stale, duplicate, cancelled and uncertain outcomes independently - of the host implementation. - -### Non-Goals - -No claim of an atomic transaction across database rows and object storage. - -## Users and Scope - -The contributor and permitted reader roles are assumed reference roles selected for this corpus, not -validated research personas. Erik owns real user validation and policy changes. -Business concepts: Evidence, BlobReference. All records and actors are fabricated. - -## Requirements - -### Must Have (P0) - -- Complete the journey and enforce its app-specific business invariant. -- Apply shared authority, lifecycle and evidence obligations without disclosure. -- Qualify required native integrations and real UI outcomes before a support claim. - -## Functional Requirements - -### Subsystem: Governed business journey - -Feature owner: FEAT-104. - -- **FR-1** — Upload fabricated evidence, verify bytes, link its immutable reference to a record and retrieve it. -- **FR-2** — Metadata must never claim available evidence before the qualified object exists; uncertain row/blob outcomes remain reconcilable. -- **FR-3** — Permission loss, stale inputs and interrupted work must preserve - authorized visibility, actual effects and the original uncertain outcome. -- **FR-4** — Supported surfaces and candidate cohorts must preserve the same - business semantics with attributable decisions and safe diagnostics. - -## Acceptance Test Sketches - -| Requirement | Scenario | Input | Expected Output | -| --- | --- | --- | --- | -| FR-1 | Main journey | fabricated attachment with an original upload identity | authorized retrieval returns the verified bytes and matching record reference | -| FR-2 | Business boundary | interrupt between object publication and metadata confirmation | published bytes are preserved and the original outcome is reconciled without blind upload replay | -| FR-3 | Foreign or revoked actor | Original fixture with changed authority | Safe refusal; no hidden data or new business effect | -| FR-4 | Alternate client/cohort | Same app and business inputs | Same authorized outcome or explicit unsupported refusal | - -## Technical Context - -Integration requirements: tables,storage,actions. These are corpus tags, not installable -module names or a claim that every adapter exists. Use UMF typed access with -PostgreSQL 18 for tables and Truss for graphs. Initial UI is a TypeScript browser -app under SDK ADR-015 and CONTRACT-005. No frontend framework is selected here. -Platform contracts are explicit dependencies in the test plan; original native -model/action packages require exact source and cohort qualification before build. - -## Constraints, Assumptions, Dependencies - -- Shared obligations in SDK CONTRACT-011 apply in full. -- Fixture states and role separation are conformance defaults, not production rules. -- Same local PostgreSQL instance does not imply one transaction across all services. -- Native authoring, host/client and required provider integrations precede app execution. - -## Risks - -| Risk | Probability | Impact | Mitigation | -| --- | --- | --- | --- | -| Fixture mistaken for a running app | Unmeasured | False support claim | Separate inventory from full execution qualification | -| UI or hook bypasses policy | Unmeasured | Unauthorized outcome | Public host boundary and server-side current authority checks | -| Backend changes business meaning | Unmeasured | Invalid result | Independent expectations and candidate-cohort replay | - -## Open Questions - -Erik supplies workload, latency/cost limits, real retention rules and production -policy. Those values block production qualification, not fabricated specification. - -## Success Criteria - -The governing story's positive and negative criteria pass through exact installed -native integrations and real client/host paths, with safe required telemetry. -The corpus inventory alone establishes none of those execution claims. diff --git a/docs/helix/reference-apps/evidence-library/specs/01-frame/user-stories/US-104-journey.md b/docs/helix/reference-apps/evidence-library/specs/01-frame/user-stories/US-104-journey.md deleted file mode 100644 index eead861..0000000 --- a/docs/helix/reference-apps/evidence-library/specs/01-frame/user-stories/US-104-journey.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -ddx: - id: US-104 - type: user-stories - activity: frame - authoring: - home: repo - links: - - id: evidence-library.prd - kind: derived_from ---- - -# US-104: Complete the evidence and attachment library journey - -**Feature**: FEAT-104 — Governed business journey -**Feature Requirements**: Reference-app business journey. -**PRD Requirements**: FR-1, FR-2, FR-3, FR-4. -**Priority**: P0. - -## Story - -**As a** contributor and permitted reader -**I want** to complete the governed business journey -**So that** I can rely on its authorized result and recover safely after interruption. - -## Context - -This is application MA-004. Business rules below are explicit fabricated defaults. -They remain independent of whichever platform implementation is being qualified. - -## Walkthrough - -1. The actor opens permitted work and inspects its current state and revision. -2. The actor follows the journey: Upload fabricated evidence, verify bytes, link its immutable reference to a record and retrieve it. -3. The host checks current authority and original operation identity. -4. The actor observes the result, or reconciles the original uncertain attempt. - -## Acceptance Criteria - -- [ ] **US-104-AC1** — Given fabricated attachment with an original upload identity, when the actor performs the journey, then authorized retrieval returns the verified bytes and matching record reference. -- [ ] **US-104-AC2** — Given the app's business invariant, when actors interrupt between object publication and metadata confirmation, then published bytes are preserved and the original outcome is reconciled without blind upload replay. -- [ ] **US-104-AC3** — Given a foreign, anonymous or revoked actor, when they attempt the same operation or continuation, then no private result or unauthorized mutation is disclosed. -- [ ] **US-104-AC4** — Given response loss or cancellation, when the actor inspects original work, then actual effects and uncertainty remain attributable without a fresh blind command. -- [ ] **US-104-AC5** — Given the same business inputs on another supported surface or cohort, when the journey runs, then meaning and authority are preserved; unsupported required behavior refuses explicitly. - -## Edge Cases - -- Empty permitted data returns an authorized empty state, not hidden counts. -- Dependency failure exposes a safe outcome; a scripted replacement is not selected. -- Query and inspection do not mutate business records or retry uncertain commands. - -## Test Scenarios - -| Scenario | AC ID | Input / State | Action | Expected Result | -| --- | --- | --- | --- | --- | -| Main journey | US-104-AC1 | fabricated attachment with an original upload identity | upload, verify and publish its reference | authorized retrieval returns the verified bytes and matching record reference | -| Business invariant | US-104-AC2 | Same original fixture | interrupt between object publication and metadata confirmation | published bytes are preserved and the original outcome is reconciled without blind upload replay | -| Current authority | US-104-AC3 | Fixture foreign actor | Attempt and continue work | Safe denial without disclosure | -| Lost response | US-104-AC4 | Original possibly effective attempt | Observe original identity | Actual or uncertain outcome, no blind replay | -| Cohort parity | US-104-AC5 | Same semantic inputs | Exercise supported client/host | Same meaning or explicit refusal | - -## Dependencies - -Local PRD FR-1–4; SDK CONTRACT-003/004/005/011. Native platform model/action -contracts must be selected before executable app construction. Corpus tags: -tables,storage,actions. Their presence requests support and grants no authority. - -## Out of Scope - -No claim of an atomic transaction across database rows and object storage. Full platform implementation is not authorized by this app story. diff --git a/docs/helix/reference-apps/evidence-library/specs/03-test/test-plan.md b/docs/helix/reference-apps/evidence-library/specs/03-test/test-plan.md deleted file mode 100644 index b3e8029..0000000 --- a/docs/helix/reference-apps/evidence-library/specs/03-test/test-plan.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -ddx: - id: TP-104 - type: test-plan - activity: test - authoring: - home: repo - links: - - id: US-104 - kind: informed_by ---- - -# Evidence and attachment library: conformance allocation - -## Strategy - -**Goal**: Qualify MA-004's full authorized journey and distinct business invariant. -**Out of scope**: No claim of an atomic transaction across database rows and object storage. -Use shared runner obligations from SDK CONTRACT-011 and preserve the independent -story expectations. No app result may be inferred from inventory validation. - -## Framework Selection & Cost - -| Layer | Framework | Justification | CI Time Impact | Maintenance Burden | -| --- | --- | --- | --- | --- | -| Inventory | Existing stdlib corpus checker | Exact scope/fixture integrity without app loading | Measured by shared command; no estimate supplied | Shared | -| Native actions | Qualified UMF/existing provider conformance | Reuse native ORM/graph semantics rather than duplicate them | Unknown; Erik owns budget | One shared runner, app data | -| UI journey | Real TypeScript client/browser harness | Authored UI requires independent observable journeys | Unknown; harness selection precedes app build | App acceptance scenarios | -| Model behavior where requested | Deterministic scripted API plus separate live API cut | Reproducible rules and actual integration prove different properties | Unknown | Fixture/model cohort scoped | - -## Critical Paths (P0) - -1. Story FR-1/2: authorized retrieval returns the verified bytes and matching record reference; invariant: Metadata must never claim available evidence before the qualified object exists; uncertain row/blob outcomes remain reconcilable. -2. Story FR-3: unauthorized, stale, duplicate and uncertain work never loses its - actual authority or outcome boundary. -3. Story FR-4: exact supported client/cohort preserves business meaning and safe - diagnostics, including current identity on continuation. - -## Acceptance Criteria Layer Allocation - -| AC class / source | Story Test Plan | Primary Layer | Why this layer | -| --- | --- | --- | --- | -| US-104 main business and invariant classes | App story test plan at build handoff | Public client/host/native provider journey | Only full path proves business result | -| US-104 permission/recovery classes | Same app story test plan | Native integration | Current authority and durable effects cross boundaries | -| US-104 surface/candidate classes | Same app story test plan | Real browser plus separate CLI parity observation | TypeScript and server behavior require distinct observations | - -The build handoff must author the per-criterion story test plan and native model/ -technical design from installed HELIX templates before executable app code. -No preselected test function or framework is fabricated before that contract exists. - -## Secondary Paths (P1-P2) - -Optional UI polish cannot weaken required denial, uncertainty or accessibility -behavior. There is no optional escape from an active P0 criterion. - -## Test Data Strategy - -Use `../../fixtures.json` and the story's independent Given/When/Then examples. -Create isolated native namespaces with explicit PostgreSQL 18/Truss bindings and -scoped local identity. No production snapshot, credentials or inferred grants. -Every generated/native input retains its app/model/refinement identity. - -## Known Gaps - -Complete app execution requires qualified host/client, native model artifacts, -selected integrations and a trusted evidence runner. These are qualification -blockers, not accepted runtime risk or passing skips. SDK component storage -checks qualify only their own boundary. TypeScript UI is authored, not generated -from a declarative UI model. UI harness selection belongs to the app build design. - -## Build Commands - -From the SDK repository root: - -```sh -python scripts/check_micro_apps.py -python scripts/check_micro_apps.py --require-execution -``` - -The first command verifies inventory only; the second must refuse absent complete -app execution evidence. SDK platform dependencies are explicit file references: -`../../../../02-design/contracts/CONTRACT-003-composition.md`, -`../../../../02-design/contracts/CONTRACT-004-host-profiles.md`, -`../../../../02-design/contracts/CONTRACT-005-ux-builder-binding.md`, and -`../../../../02-design/contracts/CONTRACT-011-micro-app-conformance.md`. - -**Blocking gate**: Every active story criterion and shared obligation must have -trusted passing evidence for exact inputs before this app is called qualified. -No test-function ceiling increase; parameterize cases in shared machinery. - -## Diagnostic Test Strategy - -Exercise actual safe host audit and required telemetry across client, host and -providers, including a real receiver, refusal, retries, capture loss and shutdown. -A mocked exporter or parsed JSON is not receiver qualification. Erik supplies -workload and diagnostic overhead budgets before production qualification. diff --git a/docs/helix/reference-apps/knowledge-assistant/.helix.yml b/docs/helix/reference-apps/knowledge-assistant/.helix.yml deleted file mode 100644 index 67eebe4..0000000 --- a/docs/helix/reference-apps/knowledge-assistant/.helix.yml +++ /dev/null @@ -1,12 +0,0 @@ -{ - "flows": [ - { - "id": "helix", - "root": "specs/" - } - ], - "x-batten-app": { - "id": "MA-007", - "workflow": "../../04-build/batten-app-workflow.md" - } -} diff --git a/docs/helix/reference-apps/knowledge-assistant/AGENTS.md b/docs/helix/reference-apps/knowledge-assistant/AGENTS.md deleted file mode 100644 index c25b331..0000000 --- a/docs/helix/reference-apps/knowledge-assistant/AGENTS.md +++ /dev/null @@ -1,19 +0,0 @@ -# Working on Grounded knowledge assistant - -Read this directory's `.helix.yml` and engage the installed HELIX skill. This is -application MA-007; governed artifacts belong only in `specs/`. Start with -`specs/01-frame/prd.md`, then the story and test plan. Follow -[the Batten app workflow](../../04-build/batten-app-workflow.md), using templates, -prompts and metadata from the installed HELIX catalog. Do not vendor the catalog. - -Reference app rules are fabricated conformance defaults, not real business policy. -UMF owns models/actions and typed persistence; PostgreSQL 18 and Truss own native -storage/execution. UI is application-authored TypeScript through the public host -client, with room for ux-builder. No direct database/provider access in the UI. -Read applicable SDK contracts through explicit file paths; local artifact IDs -resolve inside this app scope. App specs do not authorize SDK or upstream edits. - -Build only after a scoped app implementation instruction and qualified integration -closure. No credentials, production data, migrations, applies, commits or pushes -without their applicable authorization. Never replace a required failing positive -case with a skip, mock result or changed expected outcome. diff --git a/docs/helix/reference-apps/knowledge-assistant/fixtures.json b/docs/helix/reference-apps/knowledge-assistant/fixtures.json deleted file mode 100644 index 1c54e03..0000000 --- a/docs/helix/reference-apps/knowledge-assistant/fixtures.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "application": "MA-007", - "record": { - "id": "fabricated-knowledge-assistant-record", - "owner": "actor-a", - "state": "asked" - }, - "actors": { - "permitted": "actor-a", - "foreign": "actor-b", - "independent_reviewer": "actor-c" - } -} diff --git a/docs/helix/reference-apps/knowledge-assistant/specs/01-frame/features/FEAT-107-business-journey.md b/docs/helix/reference-apps/knowledge-assistant/specs/01-frame/features/FEAT-107-business-journey.md deleted file mode 100644 index b942a10..0000000 --- a/docs/helix/reference-apps/knowledge-assistant/specs/01-frame/features/FEAT-107-business-journey.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -ddx: - id: FEAT-107 - type: feature-specification - activity: frame - authoring: - home: repo - links: - - id: knowledge-assistant.prd - kind: derived_from ---- - -# FEAT-107: Governed business journey - -**Feature ID**: FEAT-107 -**Priority**: P0 -**Owner**: Erik LaBianca -**Covered PRD Subsystem(s)**: Governed business journey -**Covered PRD Requirements**: FR-1, FR-2, FR-3, FR-4 -**Cross-Subsystem Rationale**: None; one app-specific journey. - -## Overview - -The app must complete its PRD's business journey through authorized platform -operations and preserve its independently stated business invariant. - -## Ideal Future State - -The actor can rely on the final result or safely reconcile original uncertain -work across supported surfaces, without rebuilding integration or policy. - -## Problem Statement - -Passing component calls do not prove this app's domain outcome. The PRD defines -its users, concepts and rule; the story owns its observable acceptance criteria. - -## Requirements - -- FR-1 must complete the specific app journey in the PRD. -- FR-2 must enforce the PRD's distinct business invariant. -- FR-3 must preserve current permission and actual/uncertain effects on failure. -- FR-4 must preserve meaning and attribution across qualified surfaces/cohorts. - -### Non-Functional Requirements - -No private provider access or client-derived authority. Bounded native work and -safe diagnostics follow SDK CONTRACT-011; Erik supplies production workload and -latency/cost budgets. No numeric operating target is assumed. - -## User Stories - -[US-107](../user-stories/US-107-journey.md) owns the acceptance criteria. - -## Edge Cases and Error Handling - -Foreign/revoked actors, changed inputs, interrupted commands and unavailable -providers retain the story's explicit safe outcomes. No silent scripted replacement. - -## Constraints and Assumptions - -Fabricated business defaults, native UMF data/actions, PostgreSQL 18/Truss when -required, and authored TypeScript UI. Exact platform subset needs qualification. - -## Dependencies - -Local PRD FR-1–4 and SDK CONTRACT-003/004/005/011 through explicit file references -in the app test plan. The app has no authority to modify those shared contracts. - -## Out of Scope - -New platform engines, privileged UI-side data access, production policy or deployment. diff --git a/docs/helix/reference-apps/knowledge-assistant/specs/01-frame/prd.md b/docs/helix/reference-apps/knowledge-assistant/specs/01-frame/prd.md deleted file mode 100644 index 658a1d8..0000000 --- a/docs/helix/reference-apps/knowledge-assistant/specs/01-frame/prd.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -ddx: - id: knowledge-assistant.prd - type: prd - activity: frame - authoring: - home: repo ---- - -# Grounded knowledge assistant - -## Summary - -MA-007 is a fabricated enterprise reference app for a knowledge consumer and content owner. It exercises -ask a question, retrieve authorized sources, inspect a grounded answer and open permitted citations. Its purpose is to qualify a useful business journey -through Batten's platform integrations, rather than introduce a new engine. - -## Problem and Goals - -### Problem - -Users need an attributable business result across data, permission and failure -boundaries. A successful component call alone cannot establish this workflow. - -### Goals - -- Complete the stated journey while preserving current access and original identity. -- Detect the app-specific business invariant: Every factual citation resolves to an authorized source revision; retrieval visibility never grants download authority. -- Reproduce denied, stale, duplicate, cancelled and uncertain outcomes independently - of the host implementation. - -### Non-Goals - -No search/vector backend or accuracy level is implicitly selected. - -## Users and Scope - -The knowledge consumer and content owner roles are assumed reference roles selected for this corpus, not -validated research personas. Erik owns real user validation and policy changes. -Business concepts: Source, Citation, AnswerDraft. All records and actors are fabricated. - -## Requirements - -### Must Have (P0) - -- Complete the journey and enforce its app-specific business invariant. -- Apply shared authority, lifecycle and evidence obligations without disclosure. -- Qualify required native integrations and real UI outcomes before a support claim. - -## Functional Requirements - -### Subsystem: Governed business journey - -Feature owner: FEAT-107. - -- **FR-1** — Ask a question, retrieve authorized sources, inspect a grounded answer and open permitted citations. -- **FR-2** — Every factual citation resolves to an authorized source revision; retrieval visibility never grants download authority. -- **FR-3** — Permission loss, stale inputs and interrupted work must preserve - authorized visibility, actual effects and the original uncertain outcome. -- **FR-4** — Supported surfaces and candidate cohorts must preserve the same - business semantics with attributable decisions and safe diagnostics. - -## Acceptance Test Sketches - -| Requirement | Scenario | Input | Expected Output | -| --- | --- | --- | --- | -| FR-1 | Main journey | question and fabricated sources with mixed visibility | answer cites only available permitted source revisions and exposes uncertainty | -| FR-2 | Business boundary | revoke source access before opening a citation | citation access is refused without disclosing hidden source content | -| FR-3 | Foreign or revoked actor | Original fixture with changed authority | Safe refusal; no hidden data or new business effect | -| FR-4 | Alternate client/cohort | Same app and business inputs | Same authorized outcome or explicit unsupported refusal | - -## Technical Context - -Integration requirements: tables,storage,agents,models,search. These are corpus tags, not installable -module names or a claim that every adapter exists. Use UMF typed access with -PostgreSQL 18 for tables and Truss for graphs. Initial UI is a TypeScript browser -app under SDK ADR-015 and CONTRACT-005. No frontend framework is selected here. -Platform contracts are explicit dependencies in the test plan; original native -model/action packages require exact source and cohort qualification before build. - -## Constraints, Assumptions, Dependencies - -- Shared obligations in SDK CONTRACT-011 apply in full. -- Fixture states and role separation are conformance defaults, not production rules. -- Same local PostgreSQL instance does not imply one transaction across all services. -- Native authoring, host/client and required provider integrations precede app execution. - -## Risks - -| Risk | Probability | Impact | Mitigation | -| --- | --- | --- | --- | -| Fixture mistaken for a running app | Unmeasured | False support claim | Separate inventory from full execution qualification | -| UI or hook bypasses policy | Unmeasured | Unauthorized outcome | Public host boundary and server-side current authority checks | -| Backend changes business meaning | Unmeasured | Invalid result | Independent expectations and candidate-cohort replay | - -## Open Questions - -Erik supplies workload, latency/cost limits, real retention rules and production -policy. Those values block production qualification, not fabricated specification. - -## Success Criteria - -The governing story's positive and negative criteria pass through exact installed -native integrations and real client/host paths, with safe required telemetry. -The corpus inventory alone establishes none of those execution claims. diff --git a/docs/helix/reference-apps/knowledge-assistant/specs/01-frame/user-stories/US-107-journey.md b/docs/helix/reference-apps/knowledge-assistant/specs/01-frame/user-stories/US-107-journey.md deleted file mode 100644 index d9639c8..0000000 --- a/docs/helix/reference-apps/knowledge-assistant/specs/01-frame/user-stories/US-107-journey.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -ddx: - id: US-107 - type: user-stories - activity: frame - authoring: - home: repo - links: - - id: knowledge-assistant.prd - kind: derived_from ---- - -# US-107: Complete the grounded knowledge assistant journey - -**Feature**: FEAT-107 — Governed business journey -**Feature Requirements**: Reference-app business journey. -**PRD Requirements**: FR-1, FR-2, FR-3, FR-4. -**Priority**: P0. - -## Story - -**As a** knowledge consumer and content owner -**I want** to complete the governed business journey -**So that** I can rely on its authorized result and recover safely after interruption. - -## Context - -This is application MA-007. Business rules below are explicit fabricated defaults. -They remain independent of whichever platform implementation is being qualified. - -## Walkthrough - -1. The actor opens permitted work and inspects its current state and revision. -2. The actor follows the journey: Ask a question, retrieve authorized sources, inspect a grounded answer and open permitted citations. -3. The host checks current authority and original operation identity. -4. The actor observes the result, or reconciles the original uncertain attempt. - -## Acceptance Criteria - -- [ ] **US-107-AC1** — Given question and fabricated sources with mixed visibility, when the actor performs the journey, then answer cites only available permitted source revisions and exposes uncertainty. -- [ ] **US-107-AC2** — Given the app's business invariant, when actors revoke source access before opening a citation, then citation access is refused without disclosing hidden source content. -- [ ] **US-107-AC3** — Given a foreign, anonymous or revoked actor, when they attempt the same operation or continuation, then no private result or unauthorized mutation is disclosed. -- [ ] **US-107-AC4** — Given response loss or cancellation, when the actor inspects original work, then actual effects and uncertainty remain attributable without a fresh blind command. -- [ ] **US-107-AC5** — Given the same business inputs on another supported surface or cohort, when the journey runs, then meaning and authority are preserved; unsupported required behavior refuses explicitly. - -## Edge Cases - -- Empty permitted data returns an authorized empty state, not hidden counts. -- Dependency failure exposes a safe outcome; a scripted replacement is not selected. -- Query and inspection do not mutate business records or retry uncertain commands. - -## Test Scenarios - -| Scenario | AC ID | Input / State | Action | Expected Result | -| --- | --- | --- | --- | --- | -| Main journey | US-107-AC1 | question and fabricated sources with mixed visibility | retrieve authorized evidence and produce an answer draft | answer cites only available permitted source revisions and exposes uncertainty | -| Business invariant | US-107-AC2 | Same original fixture | revoke source access before opening a citation | citation access is refused without disclosing hidden source content | -| Current authority | US-107-AC3 | Fixture foreign actor | Attempt and continue work | Safe denial without disclosure | -| Lost response | US-107-AC4 | Original possibly effective attempt | Observe original identity | Actual or uncertain outcome, no blind replay | -| Cohort parity | US-107-AC5 | Same semantic inputs | Exercise supported client/host | Same meaning or explicit refusal | - -## Dependencies - -Local PRD FR-1–4; SDK CONTRACT-003/004/005/011. Native platform model/action -contracts must be selected before executable app construction. Corpus tags: -tables,storage,agents,models,search. Their presence requests support and grants no authority. - -## Out of Scope - -No search/vector backend or accuracy level is implicitly selected. Full platform implementation is not authorized by this app story. diff --git a/docs/helix/reference-apps/knowledge-assistant/specs/03-test/test-plan.md b/docs/helix/reference-apps/knowledge-assistant/specs/03-test/test-plan.md deleted file mode 100644 index 556b207..0000000 --- a/docs/helix/reference-apps/knowledge-assistant/specs/03-test/test-plan.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -ddx: - id: TP-107 - type: test-plan - activity: test - authoring: - home: repo - links: - - id: US-107 - kind: informed_by ---- - -# Grounded knowledge assistant: conformance allocation - -## Strategy - -**Goal**: Qualify MA-007's full authorized journey and distinct business invariant. -**Out of scope**: No search/vector backend or accuracy level is implicitly selected. -Use shared runner obligations from SDK CONTRACT-011 and preserve the independent -story expectations. No app result may be inferred from inventory validation. - -## Framework Selection & Cost - -| Layer | Framework | Justification | CI Time Impact | Maintenance Burden | -| --- | --- | --- | --- | --- | -| Inventory | Existing stdlib corpus checker | Exact scope/fixture integrity without app loading | Measured by shared command; no estimate supplied | Shared | -| Native actions | Qualified UMF/existing provider conformance | Reuse native ORM/graph semantics rather than duplicate them | Unknown; Erik owns budget | One shared runner, app data | -| UI journey | Real TypeScript client/browser harness | Authored UI requires independent observable journeys | Unknown; harness selection precedes app build | App acceptance scenarios | -| Model behavior where requested | Deterministic scripted API plus separate live API cut | Reproducible rules and actual integration prove different properties | Unknown | Fixture/model cohort scoped | - -## Critical Paths (P0) - -1. Story FR-1/2: answer cites only available permitted source revisions and exposes uncertainty; invariant: Every factual citation resolves to an authorized source revision; retrieval visibility never grants download authority. -2. Story FR-3: unauthorized, stale, duplicate and uncertain work never loses its - actual authority or outcome boundary. -3. Story FR-4: exact supported client/cohort preserves business meaning and safe - diagnostics, including current identity on continuation. - -## Acceptance Criteria Layer Allocation - -| AC class / source | Story Test Plan | Primary Layer | Why this layer | -| --- | --- | --- | --- | -| US-107 main business and invariant classes | App story test plan at build handoff | Public client/host/native provider journey | Only full path proves business result | -| US-107 permission/recovery classes | Same app story test plan | Native integration | Current authority and durable effects cross boundaries | -| US-107 surface/candidate classes | Same app story test plan | Real browser plus separate CLI parity observation | TypeScript and server behavior require distinct observations | - -The build handoff must author the per-criterion story test plan and native model/ -technical design from installed HELIX templates before executable app code. -No preselected test function or framework is fabricated before that contract exists. - -## Secondary Paths (P1-P2) - -Optional UI polish cannot weaken required denial, uncertainty or accessibility -behavior. There is no optional escape from an active P0 criterion. - -## Test Data Strategy - -Use `../../fixtures.json` and the story's independent Given/When/Then examples. -Create isolated native namespaces with explicit PostgreSQL 18/Truss bindings and -scoped local identity. No production snapshot, credentials or inferred grants. -Every generated/native input retains its app/model/refinement identity. - -## Known Gaps - -Complete app execution requires qualified host/client, native model artifacts, -selected integrations and a trusted evidence runner. These are qualification -blockers, not accepted runtime risk or passing skips. SDK component storage -checks qualify only their own boundary. TypeScript UI is authored, not generated -from a declarative UI model. UI harness selection belongs to the app build design. - -## Build Commands - -From the SDK repository root: - -```sh -python scripts/check_micro_apps.py -python scripts/check_micro_apps.py --require-execution -``` - -The first command verifies inventory only; the second must refuse absent complete -app execution evidence. SDK platform dependencies are explicit file references: -`../../../../02-design/contracts/CONTRACT-003-composition.md`, -`../../../../02-design/contracts/CONTRACT-004-host-profiles.md`, -`../../../../02-design/contracts/CONTRACT-005-ux-builder-binding.md`, and -`../../../../02-design/contracts/CONTRACT-011-micro-app-conformance.md`. - -**Blocking gate**: Every active story criterion and shared obligation must have -trusted passing evidence for exact inputs before this app is called qualified. -No test-function ceiling increase; parameterize cases in shared machinery. - -## Diagnostic Test Strategy - -Exercise actual safe host audit and required telemetry across client, host and -providers, including a real receiver, refusal, retries, capture loss and shutdown. -A mocked exporter or parsed JSON is not receiver qualification. Erik supplies -workload and diagnostic overhead budgets before production qualification. diff --git a/docs/helix/reference-apps/model-triage/.helix.yml b/docs/helix/reference-apps/model-triage/.helix.yml deleted file mode 100644 index b8515be..0000000 --- a/docs/helix/reference-apps/model-triage/.helix.yml +++ /dev/null @@ -1,12 +0,0 @@ -{ - "flows": [ - { - "id": "helix", - "root": "specs/" - } - ], - "x-batten-app": { - "id": "MA-008", - "workflow": "../../04-build/batten-app-workflow.md" - } -} diff --git a/docs/helix/reference-apps/model-triage/AGENTS.md b/docs/helix/reference-apps/model-triage/AGENTS.md deleted file mode 100644 index 8105099..0000000 --- a/docs/helix/reference-apps/model-triage/AGENTS.md +++ /dev/null @@ -1,19 +0,0 @@ -# Working on AI-assisted inbox triage - -Read this directory's `.helix.yml` and engage the installed HELIX skill. This is -application MA-008; governed artifacts belong only in `specs/`. Start with -`specs/01-frame/prd.md`, then the story and test plan. Follow -[the Batten app workflow](../../04-build/batten-app-workflow.md), using templates, -prompts and metadata from the installed HELIX catalog. Do not vendor the catalog. - -Reference app rules are fabricated conformance defaults, not real business policy. -UMF owns models/actions and typed persistence; PostgreSQL 18 and Truss own native -storage/execution. UI is application-authored TypeScript through the public host -client, with room for ux-builder. No direct database/provider access in the UI. -Read applicable SDK contracts through explicit file paths; local artifact IDs -resolve inside this app scope. App specs do not authorize SDK or upstream edits. - -Build only after a scoped app implementation instruction and qualified integration -closure. No credentials, production data, migrations, applies, commits or pushes -without their applicable authorization. Never replace a required failing positive -case with a skip, mock result or changed expected outcome. diff --git a/docs/helix/reference-apps/model-triage/fixtures.json b/docs/helix/reference-apps/model-triage/fixtures.json deleted file mode 100644 index b439622..0000000 --- a/docs/helix/reference-apps/model-triage/fixtures.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "application": "MA-008", - "record": { - "id": "fabricated-model-triage-record", - "owner": "actor-a", - "state": "received" - }, - "actors": { - "permitted": "actor-a", - "foreign": "actor-b", - "independent_reviewer": "actor-c" - } -} diff --git a/docs/helix/reference-apps/model-triage/specs/01-frame/features/FEAT-108-business-journey.md b/docs/helix/reference-apps/model-triage/specs/01-frame/features/FEAT-108-business-journey.md deleted file mode 100644 index 75b32b3..0000000 --- a/docs/helix/reference-apps/model-triage/specs/01-frame/features/FEAT-108-business-journey.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -ddx: - id: FEAT-108 - type: feature-specification - activity: frame - authoring: - home: repo - links: - - id: model-triage.prd - kind: derived_from ---- - -# FEAT-108: Governed business journey - -**Feature ID**: FEAT-108 -**Priority**: P0 -**Owner**: Erik LaBianca -**Covered PRD Subsystem(s)**: Governed business journey -**Covered PRD Requirements**: FR-1, FR-2, FR-3, FR-4 -**Cross-Subsystem Rationale**: None; one app-specific journey. - -## Overview - -The app must complete its PRD's business journey through authorized platform -operations and preserve its independently stated business invariant. - -## Ideal Future State - -The actor can rely on the final result or safely reconcile original uncertain -work across supported surfaces, without rebuilding integration or policy. - -## Problem Statement - -Passing component calls do not prove this app's domain outcome. The PRD defines -its users, concepts and rule; the story owns its observable acceptance criteria. - -## Requirements - -- FR-1 must complete the specific app journey in the PRD. -- FR-2 must enforce the PRD's distinct business invariant. -- FR-3 must preserve current permission and actual/uncertain effects on failure. -- FR-4 must preserve meaning and attribution across qualified surfaces/cohorts. - -### Non-Functional Requirements - -No private provider access or client-derived authority. Bounded native work and -safe diagnostics follow SDK CONTRACT-011; Erik supplies production workload and -latency/cost budgets. No numeric operating target is assumed. - -## User Stories - -[US-108](../user-stories/US-108-journey.md) owns the acceptance criteria. - -## Edge Cases and Error Handling - -Foreign/revoked actors, changed inputs, interrupted commands and unavailable -providers retain the story's explicit safe outcomes. No silent scripted replacement. - -## Constraints and Assumptions - -Fabricated business defaults, native UMF data/actions, PostgreSQL 18/Truss when -required, and authored TypeScript UI. Exact platform subset needs qualification. - -## Dependencies - -Local PRD FR-1–4 and SDK CONTRACT-003/004/005/011 through explicit file references -in the app test plan. The app has no authority to modify those shared contracts. - -## Out of Scope - -New platform engines, privileged UI-side data access, production policy or deployment. diff --git a/docs/helix/reference-apps/model-triage/specs/01-frame/prd.md b/docs/helix/reference-apps/model-triage/specs/01-frame/prd.md deleted file mode 100644 index d2fcce5..0000000 --- a/docs/helix/reference-apps/model-triage/specs/01-frame/prd.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -ddx: - id: model-triage.prd - type: prd - activity: frame - authoring: - home: repo ---- - -# AI-assisted inbox triage - -## Summary - -MA-008 is a fabricated enterprise reference app for a triage analyst and automation owner. It exercises -receive an inbox item, classify it within a budget, review the suggestion and apply an authorized disposition. Its purpose is to qualify a useful business journey -through Batten's platform integrations, rather than introduce a new engine. - -## Problem and Goals - -### Problem - -Users need an attributable business result across data, permission and failure -boundaries. A successful component call alone cannot establish this workflow. - -### Goals - -- Complete the stated journey while preserving current access and original identity. -- Detect the app-specific business invariant: Delivery retries cannot repeat an accepted business disposition; a model suggestion cannot grant write authority. -- Reproduce denied, stale, duplicate, cancelled and uncertain outcomes independently - of the host implementation. - -### Non-Goals - -No exactly-once external side-effect guarantee or autonomous high-impact decision. - -## Users and Scope - -The triage analyst and automation owner roles are assumed reference roles selected for this corpus, not -validated research personas. Erik owns real user validation and policy changes. -Business concepts: InboxItem, Classification, TriageDecision. All records and actors are fabricated. - -## Requirements - -### Must Have (P0) - -- Complete the journey and enforce its app-specific business invariant. -- Apply shared authority, lifecycle and evidence obligations without disclosure. -- Qualify required native integrations and real UI outcomes before a support claim. - -## Functional Requirements - -### Subsystem: Governed business journey - -Feature owner: FEAT-108. - -- **FR-1** — Receive an inbox item, classify it within a budget, review the suggestion and apply an authorized disposition. -- **FR-2** — Delivery retries cannot repeat an accepted business disposition; a model suggestion cannot grant write authority. -- **FR-3** — Permission loss, stale inputs and interrupted work must preserve - authorized visibility, actual effects and the original uncertain outcome. -- **FR-4** — Supported surfaces and candidate cohorts must preserve the same - business semantics with attributable decisions and safe diagnostics. - -## Acceptance Test Sketches - -| Requirement | Scenario | Input | Expected Output | -| --- | --- | --- | --- | -| FR-1 | Main journey | fabricated inbox item with one durable message identity | one attributable disposition and a settled delivery outcome | -| FR-2 | Business boundary | redeliver after processing response loss | consumer observes original business result and does not apply the disposition twice | -| FR-3 | Foreign or revoked actor | Original fixture with changed authority | Safe refusal; no hidden data or new business effect | -| FR-4 | Alternate client/cohort | Same app and business inputs | Same authorized outcome or explicit unsupported refusal | - -## Technical Context - -Integration requirements: tables,messaging,agents,models,actions. These are corpus tags, not installable -module names or a claim that every adapter exists. Use UMF typed access with -PostgreSQL 18 for tables and Truss for graphs. Initial UI is a TypeScript browser -app under SDK ADR-015 and CONTRACT-005. No frontend framework is selected here. -Platform contracts are explicit dependencies in the test plan; original native -model/action packages require exact source and cohort qualification before build. - -## Constraints, Assumptions, Dependencies - -- Shared obligations in SDK CONTRACT-011 apply in full. -- Fixture states and role separation are conformance defaults, not production rules. -- Same local PostgreSQL instance does not imply one transaction across all services. -- Native authoring, host/client and required provider integrations precede app execution. - -## Risks - -| Risk | Probability | Impact | Mitigation | -| --- | --- | --- | --- | -| Fixture mistaken for a running app | Unmeasured | False support claim | Separate inventory from full execution qualification | -| UI or hook bypasses policy | Unmeasured | Unauthorized outcome | Public host boundary and server-side current authority checks | -| Backend changes business meaning | Unmeasured | Invalid result | Independent expectations and candidate-cohort replay | - -## Open Questions - -Erik supplies workload, latency/cost limits, real retention rules and production -policy. Those values block production qualification, not fabricated specification. - -## Success Criteria - -The governing story's positive and negative criteria pass through exact installed -native integrations and real client/host paths, with safe required telemetry. -The corpus inventory alone establishes none of those execution claims. diff --git a/docs/helix/reference-apps/model-triage/specs/01-frame/user-stories/US-108-journey.md b/docs/helix/reference-apps/model-triage/specs/01-frame/user-stories/US-108-journey.md deleted file mode 100644 index a2e9101..0000000 --- a/docs/helix/reference-apps/model-triage/specs/01-frame/user-stories/US-108-journey.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -ddx: - id: US-108 - type: user-stories - activity: frame - authoring: - home: repo - links: - - id: model-triage.prd - kind: derived_from ---- - -# US-108: Complete the ai-assisted inbox triage journey - -**Feature**: FEAT-108 — Governed business journey -**Feature Requirements**: Reference-app business journey. -**PRD Requirements**: FR-1, FR-2, FR-3, FR-4. -**Priority**: P0. - -## Story - -**As a** triage analyst and automation owner -**I want** to complete the governed business journey -**So that** I can rely on its authorized result and recover safely after interruption. - -## Context - -This is application MA-008. Business rules below are explicit fabricated defaults. -They remain independent of whichever platform implementation is being qualified. - -## Walkthrough - -1. The actor opens permitted work and inspects its current state and revision. -2. The actor follows the journey: Receive an inbox item, classify it within a budget, review the suggestion and apply an authorized disposition. -3. The host checks current authority and original operation identity. -4. The actor observes the result, or reconciles the original uncertain attempt. - -## Acceptance Criteria - -- [ ] **US-108-AC1** — Given fabricated inbox item with one durable message identity, when the actor performs the journey, then one attributable disposition and a settled delivery outcome. -- [ ] **US-108-AC2** — Given the app's business invariant, when actors redeliver after processing response loss, then consumer observes original business result and does not apply the disposition twice. -- [ ] **US-108-AC3** — Given a foreign, anonymous or revoked actor, when they attempt the same operation or continuation, then no private result or unauthorized mutation is disclosed. -- [ ] **US-108-AC4** — Given response loss or cancellation, when the actor inspects original work, then actual effects and uncertainty remain attributable without a fresh blind command. -- [ ] **US-108-AC5** — Given the same business inputs on another supported surface or cohort, when the journey runs, then meaning and authority are preserved; unsupported required behavior refuses explicitly. - -## Edge Cases - -- Empty permitted data returns an authorized empty state, not hidden counts. -- Dependency failure exposes a safe outcome; a scripted replacement is not selected. -- Query and inspection do not mutate business records or retry uncertain commands. - -## Test Scenarios - -| Scenario | AC ID | Input / State | Action | Expected Result | -| --- | --- | --- | --- | --- | -| Main journey | US-108-AC1 | fabricated inbox item with one durable message identity | classify then approve its disposition | one attributable disposition and a settled delivery outcome | -| Business invariant | US-108-AC2 | Same original fixture | redeliver after processing response loss | consumer observes original business result and does not apply the disposition twice | -| Current authority | US-108-AC3 | Fixture foreign actor | Attempt and continue work | Safe denial without disclosure | -| Lost response | US-108-AC4 | Original possibly effective attempt | Observe original identity | Actual or uncertain outcome, no blind replay | -| Cohort parity | US-108-AC5 | Same semantic inputs | Exercise supported client/host | Same meaning or explicit refusal | - -## Dependencies - -Local PRD FR-1–4; SDK CONTRACT-003/004/005/011. Native platform model/action -contracts must be selected before executable app construction. Corpus tags: -tables,messaging,agents,models,actions. Their presence requests support and grants no authority. - -## Out of Scope - -No exactly-once external side-effect guarantee or autonomous high-impact decision. Full platform implementation is not authorized by this app story. diff --git a/docs/helix/reference-apps/model-triage/specs/03-test/test-plan.md b/docs/helix/reference-apps/model-triage/specs/03-test/test-plan.md deleted file mode 100644 index 7642ab0..0000000 --- a/docs/helix/reference-apps/model-triage/specs/03-test/test-plan.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -ddx: - id: TP-108 - type: test-plan - activity: test - authoring: - home: repo - links: - - id: US-108 - kind: informed_by ---- - -# AI-assisted inbox triage: conformance allocation - -## Strategy - -**Goal**: Qualify MA-008's full authorized journey and distinct business invariant. -**Out of scope**: No exactly-once external side-effect guarantee or autonomous high-impact decision. -Use shared runner obligations from SDK CONTRACT-011 and preserve the independent -story expectations. No app result may be inferred from inventory validation. - -## Framework Selection & Cost - -| Layer | Framework | Justification | CI Time Impact | Maintenance Burden | -| --- | --- | --- | --- | --- | -| Inventory | Existing stdlib corpus checker | Exact scope/fixture integrity without app loading | Measured by shared command; no estimate supplied | Shared | -| Native actions | Qualified UMF/existing provider conformance | Reuse native ORM/graph semantics rather than duplicate them | Unknown; Erik owns budget | One shared runner, app data | -| UI journey | Real TypeScript client/browser harness | Authored UI requires independent observable journeys | Unknown; harness selection precedes app build | App acceptance scenarios | -| Model behavior where requested | Deterministic scripted API plus separate live API cut | Reproducible rules and actual integration prove different properties | Unknown | Fixture/model cohort scoped | - -## Critical Paths (P0) - -1. Story FR-1/2: one attributable disposition and a settled delivery outcome; invariant: Delivery retries cannot repeat an accepted business disposition; a model suggestion cannot grant write authority. -2. Story FR-3: unauthorized, stale, duplicate and uncertain work never loses its - actual authority or outcome boundary. -3. Story FR-4: exact supported client/cohort preserves business meaning and safe - diagnostics, including current identity on continuation. - -## Acceptance Criteria Layer Allocation - -| AC class / source | Story Test Plan | Primary Layer | Why this layer | -| --- | --- | --- | --- | -| US-108 main business and invariant classes | App story test plan at build handoff | Public client/host/native provider journey | Only full path proves business result | -| US-108 permission/recovery classes | Same app story test plan | Native integration | Current authority and durable effects cross boundaries | -| US-108 surface/candidate classes | Same app story test plan | Real browser plus separate CLI parity observation | TypeScript and server behavior require distinct observations | - -The build handoff must author the per-criterion story test plan and native model/ -technical design from installed HELIX templates before executable app code. -No preselected test function or framework is fabricated before that contract exists. - -## Secondary Paths (P1-P2) - -Optional UI polish cannot weaken required denial, uncertainty or accessibility -behavior. There is no optional escape from an active P0 criterion. - -## Test Data Strategy - -Use `../../fixtures.json` and the story's independent Given/When/Then examples. -Create isolated native namespaces with explicit PostgreSQL 18/Truss bindings and -scoped local identity. No production snapshot, credentials or inferred grants. -Every generated/native input retains its app/model/refinement identity. - -## Known Gaps - -Complete app execution requires qualified host/client, native model artifacts, -selected integrations and a trusted evidence runner. These are qualification -blockers, not accepted runtime risk or passing skips. SDK component storage -checks qualify only their own boundary. TypeScript UI is authored, not generated -from a declarative UI model. UI harness selection belongs to the app build design. - -## Build Commands - -From the SDK repository root: - -```sh -python scripts/check_micro_apps.py -python scripts/check_micro_apps.py --require-execution -``` - -The first command verifies inventory only; the second must refuse absent complete -app execution evidence. SDK platform dependencies are explicit file references: -`../../../../02-design/contracts/CONTRACT-003-composition.md`, -`../../../../02-design/contracts/CONTRACT-004-host-profiles.md`, -`../../../../02-design/contracts/CONTRACT-005-ux-builder-binding.md`, and -`../../../../02-design/contracts/CONTRACT-011-micro-app-conformance.md`. - -**Blocking gate**: Every active story criterion and shared obligation must have -trusted passing evidence for exact inputs before this app is called qualified. -No test-function ceiling increase; parameterize cases in shared machinery. - -## Diagnostic Test Strategy - -Exercise actual safe host audit and required telemetry across client, host and -providers, including a real receiver, refusal, retries, capture loss and shutdown. -A mocked exporter or parsed JSON is not receiver qualification. Erik supplies -workload and diagnostic overhead budgets before production qualification. diff --git a/docs/helix/reference-apps/scheduled-digest/.helix.yml b/docs/helix/reference-apps/scheduled-digest/.helix.yml deleted file mode 100644 index 64c9b50..0000000 --- a/docs/helix/reference-apps/scheduled-digest/.helix.yml +++ /dev/null @@ -1,12 +0,0 @@ -{ - "flows": [ - { - "id": "helix", - "root": "specs/" - } - ], - "x-batten-app": { - "id": "MA-010", - "workflow": "../../04-build/batten-app-workflow.md" - } -} diff --git a/docs/helix/reference-apps/scheduled-digest/AGENTS.md b/docs/helix/reference-apps/scheduled-digest/AGENTS.md deleted file mode 100644 index f88d79e..0000000 --- a/docs/helix/reference-apps/scheduled-digest/AGENTS.md +++ /dev/null @@ -1,19 +0,0 @@ -# Working on Scheduled operational digest - -Read this directory's `.helix.yml` and engage the installed HELIX skill. This is -application MA-010; governed artifacts belong only in `specs/`. Start with -`specs/01-frame/prd.md`, then the story and test plan. Follow -[the Batten app workflow](../../04-build/batten-app-workflow.md), using templates, -prompts and metadata from the installed HELIX catalog. Do not vendor the catalog. - -Reference app rules are fabricated conformance defaults, not real business policy. -UMF owns models/actions and typed persistence; PostgreSQL 18 and Truss own native -storage/execution. UI is application-authored TypeScript through the public host -client, with room for ux-builder. No direct database/provider access in the UI. -Read applicable SDK contracts through explicit file paths; local artifact IDs -resolve inside this app scope. App specs do not authorize SDK or upstream edits. - -Build only after a scoped app implementation instruction and qualified integration -closure. No credentials, production data, migrations, applies, commits or pushes -without their applicable authorization. Never replace a required failing positive -case with a skip, mock result or changed expected outcome. diff --git a/docs/helix/reference-apps/scheduled-digest/fixtures.json b/docs/helix/reference-apps/scheduled-digest/fixtures.json deleted file mode 100644 index ab6859c..0000000 --- a/docs/helix/reference-apps/scheduled-digest/fixtures.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "application": "MA-010", - "record": { - "id": "fabricated-scheduled-digest-record", - "owner": "actor-a", - "state": "scheduled" - }, - "actors": { - "permitted": "actor-a", - "foreign": "actor-b", - "independent_reviewer": "actor-c" - } -} diff --git a/docs/helix/reference-apps/scheduled-digest/specs/01-frame/features/FEAT-110-business-journey.md b/docs/helix/reference-apps/scheduled-digest/specs/01-frame/features/FEAT-110-business-journey.md deleted file mode 100644 index 760902e..0000000 --- a/docs/helix/reference-apps/scheduled-digest/specs/01-frame/features/FEAT-110-business-journey.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -ddx: - id: FEAT-110 - type: feature-specification - activity: frame - authoring: - home: repo - links: - - id: scheduled-digest.prd - kind: derived_from ---- - -# FEAT-110: Governed business journey - -**Feature ID**: FEAT-110 -**Priority**: P0 -**Owner**: Erik LaBianca -**Covered PRD Subsystem(s)**: Governed business journey -**Covered PRD Requirements**: FR-1, FR-2, FR-3, FR-4 -**Cross-Subsystem Rationale**: None; one app-specific journey. - -## Overview - -The app must complete its PRD's business journey through authorized platform -operations and preserve its independently stated business invariant. - -## Ideal Future State - -The actor can rely on the final result or safely reconcile original uncertain -work across supported surfaces, without rebuilding integration or policy. - -## Problem Statement - -Passing component calls do not prove this app's domain outcome. The PRD defines -its users, concepts and rule; the story owns its observable acceptance criteria. - -## Requirements - -- FR-1 must complete the specific app journey in the PRD. -- FR-2 must enforce the PRD's distinct business invariant. -- FR-3 must preserve current permission and actual/uncertain effects on failure. -- FR-4 must preserve meaning and attribution across qualified surfaces/cohorts. - -### Non-Functional Requirements - -No private provider access or client-derived authority. Bounded native work and -safe diagnostics follow SDK CONTRACT-011; Erik supplies production workload and -latency/cost budgets. No numeric operating target is assumed. - -## User Stories - -[US-110](../user-stories/US-110-journey.md) owns the acceptance criteria. - -## Edge Cases and Error Handling - -Foreign/revoked actors, changed inputs, interrupted commands and unavailable -providers retain the story's explicit safe outcomes. No silent scripted replacement. - -## Constraints and Assumptions - -Fabricated business defaults, native UMF data/actions, PostgreSQL 18/Truss when -required, and authored TypeScript UI. Exact platform subset needs qualification. - -## Dependencies - -Local PRD FR-1–4 and SDK CONTRACT-003/004/005/011 through explicit file references -in the app test plan. The app has no authority to modify those shared contracts. - -## Out of Scope - -New platform engines, privileged UI-side data access, production policy or deployment. diff --git a/docs/helix/reference-apps/scheduled-digest/specs/01-frame/prd.md b/docs/helix/reference-apps/scheduled-digest/specs/01-frame/prd.md deleted file mode 100644 index e99f387..0000000 --- a/docs/helix/reference-apps/scheduled-digest/specs/01-frame/prd.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -ddx: - id: scheduled-digest.prd - type: prd - activity: frame - authoring: - home: repo ---- - -# Scheduled operational digest - -## Summary - -MA-010 is a fabricated enterprise reference app for a schedule owner and authorized recipient. It exercises -schedule a bounded report, execute a due occurrence, publish its artifact and inspect delivery status. Its purpose is to qualify a useful business journey -through Batten's platform integrations, rather than introduce a new engine. - -## Problem and Goals - -### Problem - -Users need an attributable business result across data, permission and failure -boundaries. A successful component call alone cannot establish this workflow. - -### Goals - -- Complete the stated journey while preserving current access and original identity. -- Detect the app-specific business invariant: One logical schedule occurrence has one business publication identity despite competing ticks or delivery retries. -- Reproduce denied, stale, duplicate, cancelled and uncertain outcomes independently - of the host implementation. - -### Non-Goals - -No email vendor, universal scheduler or delivery-time guarantee is assumed. - -## Users and Scope - -The schedule owner and authorized recipient roles are assumed reference roles selected for this corpus, not -validated research personas. Erik owns real user validation and policy changes. -Business concepts: Schedule, DigestRun, ReportReference. All records and actors are fabricated. - -## Requirements - -### Must Have (P0) - -- Complete the journey and enforce its app-specific business invariant. -- Apply shared authority, lifecycle and evidence obligations without disclosure. -- Qualify required native integrations and real UI outcomes before a support claim. - -## Functional Requirements - -### Subsystem: Governed business journey - -Feature owner: FEAT-110. - -- **FR-1** — Schedule a bounded report, execute a due occurrence, publish its artifact and inspect delivery status. -- **FR-2** — One logical schedule occurrence has one business publication identity despite competing ticks or delivery retries. -- **FR-3** — Permission loss, stale inputs and interrupted work must preserve - authorized visibility, actual effects and the original uncertain outcome. -- **FR-4** — Supported surfaces and candidate cohorts must preserve the same - business semantics with attributable decisions and safe diagnostics. - -## Acceptance Test Sketches - -| Requirement | Scenario | Input | Expected Output | -| --- | --- | --- | --- | -| FR-1 | Main journey | fabricated schedule occurrence and scoped report rows | one attributable occurrence and a permitted report reference | -| FR-2 | Business boundary | compete for the same occurrence then lose one response | original run and possible delivery outcome remain observable without a second business publication | -| FR-3 | Foreign or revoked actor | Original fixture with changed authority | Safe refusal; no hidden data or new business effect | -| FR-4 | Alternate client/cohort | Same app and business inputs | Same authorized outcome or explicit unsupported refusal | - -## Technical Context - -Integration requirements: tables,jobs,storage,messaging. These are corpus tags, not installable -module names or a claim that every adapter exists. Use UMF typed access with -PostgreSQL 18 for tables and Truss for graphs. Initial UI is a TypeScript browser -app under SDK ADR-015 and CONTRACT-005. No frontend framework is selected here. -Platform contracts are explicit dependencies in the test plan; original native -model/action packages require exact source and cohort qualification before build. - -## Constraints, Assumptions, Dependencies - -- Shared obligations in SDK CONTRACT-011 apply in full. -- Fixture states and role separation are conformance defaults, not production rules. -- Same local PostgreSQL instance does not imply one transaction across all services. -- Native authoring, host/client and required provider integrations precede app execution. - -## Risks - -| Risk | Probability | Impact | Mitigation | -| --- | --- | --- | --- | -| Fixture mistaken for a running app | Unmeasured | False support claim | Separate inventory from full execution qualification | -| UI or hook bypasses policy | Unmeasured | Unauthorized outcome | Public host boundary and server-side current authority checks | -| Backend changes business meaning | Unmeasured | Invalid result | Independent expectations and candidate-cohort replay | - -## Open Questions - -Erik supplies workload, latency/cost limits, real retention rules and production -policy. Those values block production qualification, not fabricated specification. - -## Success Criteria - -The governing story's positive and negative criteria pass through exact installed -native integrations and real client/host paths, with safe required telemetry. -The corpus inventory alone establishes none of those execution claims. diff --git a/docs/helix/reference-apps/scheduled-digest/specs/01-frame/user-stories/US-110-journey.md b/docs/helix/reference-apps/scheduled-digest/specs/01-frame/user-stories/US-110-journey.md deleted file mode 100644 index 14ee987..0000000 --- a/docs/helix/reference-apps/scheduled-digest/specs/01-frame/user-stories/US-110-journey.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -ddx: - id: US-110 - type: user-stories - activity: frame - authoring: - home: repo - links: - - id: scheduled-digest.prd - kind: derived_from ---- - -# US-110: Complete the scheduled operational digest journey - -**Feature**: FEAT-110 — Governed business journey -**Feature Requirements**: Reference-app business journey. -**PRD Requirements**: FR-1, FR-2, FR-3, FR-4. -**Priority**: P0. - -## Story - -**As a** schedule owner and authorized recipient -**I want** to complete the governed business journey -**So that** I can rely on its authorized result and recover safely after interruption. - -## Context - -This is application MA-010. Business rules below are explicit fabricated defaults. -They remain independent of whichever platform implementation is being qualified. - -## Walkthrough - -1. The actor opens permitted work and inspects its current state and revision. -2. The actor follows the journey: Schedule a bounded report, execute a due occurrence, publish its artifact and inspect delivery status. -3. The host checks current authority and original operation identity. -4. The actor observes the result, or reconciles the original uncertain attempt. - -## Acceptance Criteria - -- [ ] **US-110-AC1** — Given fabricated schedule occurrence and scoped report rows, when the actor performs the journey, then one attributable occurrence and a permitted report reference. -- [ ] **US-110-AC2** — Given the app's business invariant, when actors compete for the same occurrence then lose one response, then original run and possible delivery outcome remain observable without a second business publication. -- [ ] **US-110-AC3** — Given a foreign, anonymous or revoked actor, when they attempt the same operation or continuation, then no private result or unauthorized mutation is disclosed. -- [ ] **US-110-AC4** — Given response loss or cancellation, when the actor inspects original work, then actual effects and uncertainty remain attributable without a fresh blind command. -- [ ] **US-110-AC5** — Given the same business inputs on another supported surface or cohort, when the journey runs, then meaning and authority are preserved; unsupported required behavior refuses explicitly. - -## Edge Cases - -- Empty permitted data returns an authorized empty state, not hidden counts. -- Dependency failure exposes a safe outcome; a scripted replacement is not selected. -- Query and inspection do not mutate business records or retry uncertain commands. - -## Test Scenarios - -| Scenario | AC ID | Input / State | Action | Expected Result | -| --- | --- | --- | --- | --- | -| Main journey | US-110-AC1 | fabricated schedule occurrence and scoped report rows | execute due work and publish its digest artifact | one attributable occurrence and a permitted report reference | -| Business invariant | US-110-AC2 | Same original fixture | compete for the same occurrence then lose one response | original run and possible delivery outcome remain observable without a second business publication | -| Current authority | US-110-AC3 | Fixture foreign actor | Attempt and continue work | Safe denial without disclosure | -| Lost response | US-110-AC4 | Original possibly effective attempt | Observe original identity | Actual or uncertain outcome, no blind replay | -| Cohort parity | US-110-AC5 | Same semantic inputs | Exercise supported client/host | Same meaning or explicit refusal | - -## Dependencies - -Local PRD FR-1–4; SDK CONTRACT-003/004/005/011. Native platform model/action -contracts must be selected before executable app construction. Corpus tags: -tables,jobs,storage,messaging. Their presence requests support and grants no authority. - -## Out of Scope - -No email vendor, universal scheduler or delivery-time guarantee is assumed. Full platform implementation is not authorized by this app story. diff --git a/docs/helix/reference-apps/scheduled-digest/specs/03-test/test-plan.md b/docs/helix/reference-apps/scheduled-digest/specs/03-test/test-plan.md deleted file mode 100644 index f4adb1d..0000000 --- a/docs/helix/reference-apps/scheduled-digest/specs/03-test/test-plan.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -ddx: - id: TP-110 - type: test-plan - activity: test - authoring: - home: repo - links: - - id: US-110 - kind: informed_by ---- - -# Scheduled operational digest: conformance allocation - -## Strategy - -**Goal**: Qualify MA-010's full authorized journey and distinct business invariant. -**Out of scope**: No email vendor, universal scheduler or delivery-time guarantee is assumed. -Use shared runner obligations from SDK CONTRACT-011 and preserve the independent -story expectations. No app result may be inferred from inventory validation. - -## Framework Selection & Cost - -| Layer | Framework | Justification | CI Time Impact | Maintenance Burden | -| --- | --- | --- | --- | --- | -| Inventory | Existing stdlib corpus checker | Exact scope/fixture integrity without app loading | Measured by shared command; no estimate supplied | Shared | -| Native actions | Qualified UMF/existing provider conformance | Reuse native ORM/graph semantics rather than duplicate them | Unknown; Erik owns budget | One shared runner, app data | -| UI journey | Real TypeScript client/browser harness | Authored UI requires independent observable journeys | Unknown; harness selection precedes app build | App acceptance scenarios | -| Model behavior where requested | Deterministic scripted API plus separate live API cut | Reproducible rules and actual integration prove different properties | Unknown | Fixture/model cohort scoped | - -## Critical Paths (P0) - -1. Story FR-1/2: one attributable occurrence and a permitted report reference; invariant: One logical schedule occurrence has one business publication identity despite competing ticks or delivery retries. -2. Story FR-3: unauthorized, stale, duplicate and uncertain work never loses its - actual authority or outcome boundary. -3. Story FR-4: exact supported client/cohort preserves business meaning and safe - diagnostics, including current identity on continuation. - -## Acceptance Criteria Layer Allocation - -| AC class / source | Story Test Plan | Primary Layer | Why this layer | -| --- | --- | --- | --- | -| US-110 main business and invariant classes | App story test plan at build handoff | Public client/host/native provider journey | Only full path proves business result | -| US-110 permission/recovery classes | Same app story test plan | Native integration | Current authority and durable effects cross boundaries | -| US-110 surface/candidate classes | Same app story test plan | Real browser plus separate CLI parity observation | TypeScript and server behavior require distinct observations | - -The build handoff must author the per-criterion story test plan and native model/ -technical design from installed HELIX templates before executable app code. -No preselected test function or framework is fabricated before that contract exists. - -## Secondary Paths (P1-P2) - -Optional UI polish cannot weaken required denial, uncertainty or accessibility -behavior. There is no optional escape from an active P0 criterion. - -## Test Data Strategy - -Use `../../fixtures.json` and the story's independent Given/When/Then examples. -Create isolated native namespaces with explicit PostgreSQL 18/Truss bindings and -scoped local identity. No production snapshot, credentials or inferred grants. -Every generated/native input retains its app/model/refinement identity. - -## Known Gaps - -Complete app execution requires qualified host/client, native model artifacts, -selected integrations and a trusted evidence runner. These are qualification -blockers, not accepted runtime risk or passing skips. SDK component storage -checks qualify only their own boundary. TypeScript UI is authored, not generated -from a declarative UI model. UI harness selection belongs to the app build design. - -## Build Commands - -From the SDK repository root: - -```sh -python scripts/check_micro_apps.py -python scripts/check_micro_apps.py --require-execution -``` - -The first command verifies inventory only; the second must refuse absent complete -app execution evidence. SDK platform dependencies are explicit file references: -`../../../../02-design/contracts/CONTRACT-003-composition.md`, -`../../../../02-design/contracts/CONTRACT-004-host-profiles.md`, -`../../../../02-design/contracts/CONTRACT-005-ux-builder-binding.md`, and -`../../../../02-design/contracts/CONTRACT-011-micro-app-conformance.md`. - -**Blocking gate**: Every active story criterion and shared obligation must have -trusted passing evidence for exact inputs before this app is called qualified. -No test-function ceiling increase; parameterize cases in shared machinery. - -## Diagnostic Test Strategy - -Exercise actual safe host audit and required telemetry across client, host and -providers, including a real receiver, refusal, retries, capture loss and shutdown. -A mocked exporter or parsed JSON is not receiver qualification. Erik supplies -workload and diagnostic overhead budgets before production qualification. diff --git a/docs/helix/reference-apps/service-handoff/.helix.yml b/docs/helix/reference-apps/service-handoff/.helix.yml deleted file mode 100644 index bd16225..0000000 --- a/docs/helix/reference-apps/service-handoff/.helix.yml +++ /dev/null @@ -1,12 +0,0 @@ -{ - "flows": [ - { - "id": "helix", - "root": "specs/" - } - ], - "x-batten-app": { - "id": "MA-012", - "workflow": "../../04-build/batten-app-workflow.md" - } -} diff --git a/docs/helix/reference-apps/service-handoff/AGENTS.md b/docs/helix/reference-apps/service-handoff/AGENTS.md deleted file mode 100644 index 0d4e919..0000000 --- a/docs/helix/reference-apps/service-handoff/AGENTS.md +++ /dev/null @@ -1,19 +0,0 @@ -# Working on Cross-application service handoff - -Read this directory's `.helix.yml` and engage the installed HELIX skill. This is -application MA-012; governed artifacts belong only in `specs/`. Start with -`specs/01-frame/prd.md`, then the story and test plan. Follow -[the Batten app workflow](../../04-build/batten-app-workflow.md), using templates, -prompts and metadata from the installed HELIX catalog. Do not vendor the catalog. - -Reference app rules are fabricated conformance defaults, not real business policy. -UMF owns models/actions and typed persistence; PostgreSQL 18 and Truss own native -storage/execution. UI is application-authored TypeScript through the public host -client, with room for ux-builder. No direct database/provider access in the UI. -Read applicable SDK contracts through explicit file paths; local artifact IDs -resolve inside this app scope. App specs do not authorize SDK or upstream edits. - -Build only after a scoped app implementation instruction and qualified integration -closure. No credentials, production data, migrations, applies, commits or pushes -without their applicable authorization. Never replace a required failing positive -case with a skip, mock result or changed expected outcome. diff --git a/docs/helix/reference-apps/service-handoff/fixtures.json b/docs/helix/reference-apps/service-handoff/fixtures.json deleted file mode 100644 index 363369d..0000000 --- a/docs/helix/reference-apps/service-handoff/fixtures.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "application": "MA-012", - "record": { - "id": "fabricated-service-handoff-record", - "owner": "actor-a", - "state": "prepared" - }, - "actors": { - "permitted": "actor-a", - "foreign": "actor-b", - "independent_reviewer": "actor-c" - } -} diff --git a/docs/helix/reference-apps/service-handoff/specs/01-frame/features/FEAT-112-business-journey.md b/docs/helix/reference-apps/service-handoff/specs/01-frame/features/FEAT-112-business-journey.md deleted file mode 100644 index ff0b1be..0000000 --- a/docs/helix/reference-apps/service-handoff/specs/01-frame/features/FEAT-112-business-journey.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -ddx: - id: FEAT-112 - type: feature-specification - activity: frame - authoring: - home: repo - links: - - id: service-handoff.prd - kind: derived_from ---- - -# FEAT-112: Governed business journey - -**Feature ID**: FEAT-112 -**Priority**: P0 -**Owner**: Erik LaBianca -**Covered PRD Subsystem(s)**: Governed business journey -**Covered PRD Requirements**: FR-1, FR-2, FR-3, FR-4 -**Cross-Subsystem Rationale**: None; one app-specific journey. - -## Overview - -The app must complete its PRD's business journey through authorized platform -operations and preserve its independently stated business invariant. - -## Ideal Future State - -The actor can rely on the final result or safely reconcile original uncertain -work across supported surfaces, without rebuilding integration or policy. - -## Problem Statement - -Passing component calls do not prove this app's domain outcome. The PRD defines -its users, concepts and rule; the story owns its observable acceptance criteria. - -## Requirements - -- FR-1 must complete the specific app journey in the PRD. -- FR-2 must enforce the PRD's distinct business invariant. -- FR-3 must preserve current permission and actual/uncertain effects on failure. -- FR-4 must preserve meaning and attribution across qualified surfaces/cohorts. - -### Non-Functional Requirements - -No private provider access or client-derived authority. Bounded native work and -safe diagnostics follow SDK CONTRACT-011; Erik supplies production workload and -latency/cost budgets. No numeric operating target is assumed. - -## User Stories - -[US-112](../user-stories/US-112-journey.md) owns the acceptance criteria. - -## Edge Cases and Error Handling - -Foreign/revoked actors, changed inputs, interrupted commands and unavailable -providers retain the story's explicit safe outcomes. No silent scripted replacement. - -## Constraints and Assumptions - -Fabricated business defaults, native UMF data/actions, PostgreSQL 18/Truss when -required, and authored TypeScript UI. Exact platform subset needs qualification. - -## Dependencies - -Local PRD FR-1–4 and SDK CONTRACT-003/004/005/011 through explicit file references -in the app test plan. The app has no authority to modify those shared contracts. - -## Out of Scope - -New platform engines, privileged UI-side data access, production policy or deployment. diff --git a/docs/helix/reference-apps/service-handoff/specs/01-frame/prd.md b/docs/helix/reference-apps/service-handoff/specs/01-frame/prd.md deleted file mode 100644 index 8299f4e..0000000 --- a/docs/helix/reference-apps/service-handoff/specs/01-frame/prd.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -ddx: - id: service-handoff.prd - type: prd - activity: frame - authoring: - home: repo ---- - -# Cross-application service handoff - -## Summary - -MA-012 is a fabricated enterprise reference app for a requesting user and receiving service owner. It exercises -discover a permitted service, bind its exact interface, submit a request and observe receiving progress. Its purpose is to qualify a useful business journey -through Batten's platform integrations, rather than introduce a new engine. - -## Problem and Goals - -### Problem - -Users need an attributable business result across data, permission and failure -boundaries. A successful component call alone cannot establish this workflow. - -### Goals - -- Complete the stated journey while preserving current access and original identity. -- Detect the app-specific business invariant: Discovery is non-authorizing; receiving work requires current independent consumer and provider authority. -- Reproduce denied, stale, duplicate, cancelled and uncertain outcomes independently - of the host implementation. - -### Non-Goals - -No ambient service discovery or automatic authority propagation. - -## Users and Scope - -The requesting user and receiving service owner roles are assumed reference roles selected for this corpus, not -validated research personas. Erik owns real user validation and policy changes. -Business concepts: ServiceRequirement, Binding, HandoffRequest. All records and actors are fabricated. - -## Requirements - -### Must Have (P0) - -- Complete the journey and enforce its app-specific business invariant. -- Apply shared authority, lifecycle and evidence obligations without disclosure. -- Qualify required native integrations and real UI outcomes before a support claim. - -## Functional Requirements - -### Subsystem: Governed business journey - -Feature owner: FEAT-112. - -- **FR-1** — Discover a permitted service, bind its exact interface, submit a request and observe receiving progress. -- **FR-2** — Discovery is non-authorizing; receiving work requires current independent consumer and provider authority. -- **FR-3** — Permission loss, stale inputs and interrupted work must preserve - authorized visibility, actual effects and the original uncertain outcome. -- **FR-4** — Supported surfaces and candidate cohorts must preserve the same - business semantics with attributable decisions and safe diagnostics. - -## Acceptance Test Sketches - -| Requirement | Scenario | Input | Expected Output | -| --- | --- | --- | --- | -| FR-1 | Main journey | fabricated requester app and an admitted receiving export | one attributable request with preserved causal identity and receiver-scoped authority | -| FR-2 | Business boundary | revoke the binding or change the provider interface before invocation | handoff refuses without choosing another provider or replaying the command | -| FR-3 | Foreign or revoked actor | Original fixture with changed authority | Safe refusal; no hidden data or new business effect | -| FR-4 | Alternate client/cohort | Same app and business inputs | Same authorized outcome or explicit unsupported refusal | - -## Technical Context - -Integration requirements: graphs,services,messaging,actions. These are corpus tags, not installable -module names or a claim that every adapter exists. Use UMF typed access with -PostgreSQL 18 for tables and Truss for graphs. Initial UI is a TypeScript browser -app under SDK ADR-015 and CONTRACT-005. No frontend framework is selected here. -Platform contracts are explicit dependencies in the test plan; original native -model/action packages require exact source and cohort qualification before build. - -## Constraints, Assumptions, Dependencies - -- Shared obligations in SDK CONTRACT-011 apply in full. -- Fixture states and role separation are conformance defaults, not production rules. -- Same local PostgreSQL instance does not imply one transaction across all services. -- Native authoring, host/client and required provider integrations precede app execution. - -## Risks - -| Risk | Probability | Impact | Mitigation | -| --- | --- | --- | --- | -| Fixture mistaken for a running app | Unmeasured | False support claim | Separate inventory from full execution qualification | -| UI or hook bypasses policy | Unmeasured | Unauthorized outcome | Public host boundary and server-side current authority checks | -| Backend changes business meaning | Unmeasured | Invalid result | Independent expectations and candidate-cohort replay | - -## Open Questions - -Erik supplies workload, latency/cost limits, real retention rules and production -policy. Those values block production qualification, not fabricated specification. - -## Success Criteria - -The governing story's positive and negative criteria pass through exact installed -native integrations and real client/host paths, with safe required telemetry. -The corpus inventory alone establishes none of those execution claims. diff --git a/docs/helix/reference-apps/service-handoff/specs/01-frame/user-stories/US-112-journey.md b/docs/helix/reference-apps/service-handoff/specs/01-frame/user-stories/US-112-journey.md deleted file mode 100644 index 22be3a3..0000000 --- a/docs/helix/reference-apps/service-handoff/specs/01-frame/user-stories/US-112-journey.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -ddx: - id: US-112 - type: user-stories - activity: frame - authoring: - home: repo - links: - - id: service-handoff.prd - kind: derived_from ---- - -# US-112: Complete the cross-application service handoff journey - -**Feature**: FEAT-112 — Governed business journey -**Feature Requirements**: Reference-app business journey. -**PRD Requirements**: FR-1, FR-2, FR-3, FR-4. -**Priority**: P0. - -## Story - -**As a** requesting user and receiving service owner -**I want** to complete the governed business journey -**So that** I can rely on its authorized result and recover safely after interruption. - -## Context - -This is application MA-012. Business rules below are explicit fabricated defaults. -They remain independent of whichever platform implementation is being qualified. - -## Walkthrough - -1. The actor opens permitted work and inspects its current state and revision. -2. The actor follows the journey: Discover a permitted service, bind its exact interface, submit a request and observe receiving progress. -3. The host checks current authority and original operation identity. -4. The actor observes the result, or reconciles the original uncertain attempt. - -## Acceptance Criteria - -- [ ] **US-112-AC1** — Given fabricated requester app and an admitted receiving export, when the actor performs the journey, then one attributable request with preserved causal identity and receiver-scoped authority. -- [ ] **US-112-AC2** — Given the app's business invariant, when actors revoke the binding or change the provider interface before invocation, then handoff refuses without choosing another provider or replaying the command. -- [ ] **US-112-AC3** — Given a foreign, anonymous or revoked actor, when they attempt the same operation or continuation, then no private result or unauthorized mutation is disclosed. -- [ ] **US-112-AC4** — Given response loss or cancellation, when the actor inspects original work, then actual effects and uncertainty remain attributable without a fresh blind command. -- [ ] **US-112-AC5** — Given the same business inputs on another supported surface or cohort, when the journey runs, then meaning and authority are preserved; unsupported required behavior refuses explicitly. - -## Edge Cases - -- Empty permitted data returns an authorized empty state, not hidden counts. -- Dependency failure exposes a safe outcome; a scripted replacement is not selected. -- Query and inspection do not mutate business records or retry uncertain commands. - -## Test Scenarios - -| Scenario | AC ID | Input / State | Action | Expected Result | -| --- | --- | --- | --- | --- | -| Main journey | US-112-AC1 | fabricated requester app and an admitted receiving export | resolve and invoke its exact approved interface | one attributable request with preserved causal identity and receiver-scoped authority | -| Business invariant | US-112-AC2 | Same original fixture | revoke the binding or change the provider interface before invocation | handoff refuses without choosing another provider or replaying the command | -| Current authority | US-112-AC3 | Fixture foreign actor | Attempt and continue work | Safe denial without disclosure | -| Lost response | US-112-AC4 | Original possibly effective attempt | Observe original identity | Actual or uncertain outcome, no blind replay | -| Cohort parity | US-112-AC5 | Same semantic inputs | Exercise supported client/host | Same meaning or explicit refusal | - -## Dependencies - -Local PRD FR-1–4; SDK CONTRACT-003/004/005/011. Native platform model/action -contracts must be selected before executable app construction. Corpus tags: -graphs,services,messaging,actions. Their presence requests support and grants no authority. - -## Out of Scope - -No ambient service discovery or automatic authority propagation. Full platform implementation is not authorized by this app story. diff --git a/docs/helix/reference-apps/service-handoff/specs/03-test/test-plan.md b/docs/helix/reference-apps/service-handoff/specs/03-test/test-plan.md deleted file mode 100644 index fca0e74..0000000 --- a/docs/helix/reference-apps/service-handoff/specs/03-test/test-plan.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -ddx: - id: TP-112 - type: test-plan - activity: test - authoring: - home: repo - links: - - id: US-112 - kind: informed_by ---- - -# Cross-application service handoff: conformance allocation - -## Strategy - -**Goal**: Qualify MA-012's full authorized journey and distinct business invariant. -**Out of scope**: No ambient service discovery or automatic authority propagation. -Use shared runner obligations from SDK CONTRACT-011 and preserve the independent -story expectations. No app result may be inferred from inventory validation. - -## Framework Selection & Cost - -| Layer | Framework | Justification | CI Time Impact | Maintenance Burden | -| --- | --- | --- | --- | --- | -| Inventory | Existing stdlib corpus checker | Exact scope/fixture integrity without app loading | Measured by shared command; no estimate supplied | Shared | -| Native actions | Qualified UMF/existing provider conformance | Reuse native ORM/graph semantics rather than duplicate them | Unknown; Erik owns budget | One shared runner, app data | -| UI journey | Real TypeScript client/browser harness | Authored UI requires independent observable journeys | Unknown; harness selection precedes app build | App acceptance scenarios | -| Model behavior where requested | Deterministic scripted API plus separate live API cut | Reproducible rules and actual integration prove different properties | Unknown | Fixture/model cohort scoped | - -## Critical Paths (P0) - -1. Story FR-1/2: one attributable request with preserved causal identity and receiver-scoped authority; invariant: Discovery is non-authorizing; receiving work requires current independent consumer and provider authority. -2. Story FR-3: unauthorized, stale, duplicate and uncertain work never loses its - actual authority or outcome boundary. -3. Story FR-4: exact supported client/cohort preserves business meaning and safe - diagnostics, including current identity on continuation. - -## Acceptance Criteria Layer Allocation - -| AC class / source | Story Test Plan | Primary Layer | Why this layer | -| --- | --- | --- | --- | -| US-112 main business and invariant classes | App story test plan at build handoff | Public client/host/native provider journey | Only full path proves business result | -| US-112 permission/recovery classes | Same app story test plan | Native integration | Current authority and durable effects cross boundaries | -| US-112 surface/candidate classes | Same app story test plan | Real browser plus separate CLI parity observation | TypeScript and server behavior require distinct observations | - -The build handoff must author the per-criterion story test plan and native model/ -technical design from installed HELIX templates before executable app code. -No preselected test function or framework is fabricated before that contract exists. - -## Secondary Paths (P1-P2) - -Optional UI polish cannot weaken required denial, uncertainty or accessibility -behavior. There is no optional escape from an active P0 criterion. - -## Test Data Strategy - -Use `../../fixtures.json` and the story's independent Given/When/Then examples. -Create isolated native namespaces with explicit PostgreSQL 18/Truss bindings and -scoped local identity. No production snapshot, credentials or inferred grants. -Every generated/native input retains its app/model/refinement identity. - -## Known Gaps - -Complete app execution requires qualified host/client, native model artifacts, -selected integrations and a trusted evidence runner. These are qualification -blockers, not accepted runtime risk or passing skips. SDK component storage -checks qualify only their own boundary. TypeScript UI is authored, not generated -from a declarative UI model. UI harness selection belongs to the app build design. - -## Build Commands - -From the SDK repository root: - -```sh -python scripts/check_micro_apps.py -python scripts/check_micro_apps.py --require-execution -``` - -The first command verifies inventory only; the second must refuse absent complete -app execution evidence. SDK platform dependencies are explicit file references: -`../../../../02-design/contracts/CONTRACT-003-composition.md`, -`../../../../02-design/contracts/CONTRACT-004-host-profiles.md`, -`../../../../02-design/contracts/CONTRACT-005-ux-builder-binding.md`, and -`../../../../02-design/contracts/CONTRACT-011-micro-app-conformance.md`. - -**Blocking gate**: Every active story criterion and shared obligation must have -trusted passing evidence for exact inputs before this app is called qualified. -No test-function ceiling increase; parameterize cases in shared machinery. - -## Diagnostic Test Strategy - -Exercise actual safe host audit and required telemetry across client, host and -providers, including a real receiver, refusal, retries, capture loss and shutdown. -A mocked exporter or parsed JSON is not receiver qualification. Erik supplies -workload and diagnostic overhead budgets before production qualification. diff --git a/docs/helix/reference-apps/service-intake/.helix.yml b/docs/helix/reference-apps/service-intake/.helix.yml deleted file mode 100644 index a31f41f..0000000 --- a/docs/helix/reference-apps/service-intake/.helix.yml +++ /dev/null @@ -1,12 +0,0 @@ -{ - "flows": [ - { - "id": "helix", - "root": "specs/" - } - ], - "x-batten-app": { - "id": "MA-002", - "workflow": "../../04-build/batten-app-workflow.md" - } -} diff --git a/docs/helix/reference-apps/service-intake/AGENTS.md b/docs/helix/reference-apps/service-intake/AGENTS.md deleted file mode 100644 index 77f2d24..0000000 --- a/docs/helix/reference-apps/service-intake/AGENTS.md +++ /dev/null @@ -1,19 +0,0 @@ -# Working on Service intake and routing - -Read this directory's `.helix.yml` and engage the installed HELIX skill. This is -application MA-002; governed artifacts belong only in `specs/`. Start with -`specs/01-frame/prd.md`, then the story and test plan. Follow -[the Batten app workflow](../../04-build/batten-app-workflow.md), using templates, -prompts and metadata from the installed HELIX catalog. Do not vendor the catalog. - -Reference app rules are fabricated conformance defaults, not real business policy. -UMF owns models/actions and typed persistence; PostgreSQL 18 and Truss own native -storage/execution. UI is application-authored TypeScript through the public host -client, with room for ux-builder. No direct database/provider access in the UI. -Read applicable SDK contracts through explicit file paths; local artifact IDs -resolve inside this app scope. App specs do not authorize SDK or upstream edits. - -Build only after a scoped app implementation instruction and qualified integration -closure. No credentials, production data, migrations, applies, commits or pushes -without their applicable authorization. Never replace a required failing positive -case with a skip, mock result or changed expected outcome. diff --git a/docs/helix/reference-apps/service-intake/fixtures.json b/docs/helix/reference-apps/service-intake/fixtures.json deleted file mode 100644 index 3410c2d..0000000 --- a/docs/helix/reference-apps/service-intake/fixtures.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "application": "MA-002", - "record": { - "id": "fabricated-service-intake-record", - "owner": "actor-a", - "state": "draft" - }, - "actors": { - "permitted": "actor-a", - "foreign": "actor-b", - "independent_reviewer": "actor-c" - } -} diff --git a/docs/helix/reference-apps/service-intake/specs/01-frame/features/FEAT-102-business-journey.md b/docs/helix/reference-apps/service-intake/specs/01-frame/features/FEAT-102-business-journey.md deleted file mode 100644 index 4e0b451..0000000 --- a/docs/helix/reference-apps/service-intake/specs/01-frame/features/FEAT-102-business-journey.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -ddx: - id: FEAT-102 - type: feature-specification - activity: frame - authoring: - home: repo - links: - - id: service-intake.prd - kind: derived_from ---- - -# FEAT-102: Governed business journey - -**Feature ID**: FEAT-102 -**Priority**: P0 -**Owner**: Erik LaBianca -**Covered PRD Subsystem(s)**: Governed business journey -**Covered PRD Requirements**: FR-1, FR-2, FR-3, FR-4 -**Cross-Subsystem Rationale**: None; one app-specific journey. - -## Overview - -The app must complete its PRD's business journey through authorized platform -operations and preserve its independently stated business invariant. - -## Ideal Future State - -The actor can rely on the final result or safely reconcile original uncertain -work across supported surfaces, without rebuilding integration or policy. - -## Problem Statement - -Passing component calls do not prove this app's domain outcome. The PRD defines -its users, concepts and rule; the story owns its observable acceptance criteria. - -## Requirements - -- FR-1 must complete the specific app journey in the PRD. -- FR-2 must enforce the PRD's distinct business invariant. -- FR-3 must preserve current permission and actual/uncertain effects on failure. -- FR-4 must preserve meaning and attribution across qualified surfaces/cohorts. - -### Non-Functional Requirements - -No private provider access or client-derived authority. Bounded native work and -safe diagnostics follow SDK CONTRACT-011; Erik supplies production workload and -latency/cost budgets. No numeric operating target is assumed. - -## User Stories - -[US-102](../user-stories/US-102-journey.md) owns the acceptance criteria. - -## Edge Cases and Error Handling - -Foreign/revoked actors, changed inputs, interrupted commands and unavailable -providers retain the story's explicit safe outcomes. No silent scripted replacement. - -## Constraints and Assumptions - -Fabricated business defaults, native UMF data/actions, PostgreSQL 18/Truss when -required, and authored TypeScript UI. Exact platform subset needs qualification. - -## Dependencies - -Local PRD FR-1–4 and SDK CONTRACT-003/004/005/011 through explicit file references -in the app test plan. The app has no authority to modify those shared contracts. - -## Out of Scope - -New platform engines, privileged UI-side data access, production policy or deployment. diff --git a/docs/helix/reference-apps/service-intake/specs/01-frame/prd.md b/docs/helix/reference-apps/service-intake/specs/01-frame/prd.md deleted file mode 100644 index 76c2081..0000000 --- a/docs/helix/reference-apps/service-intake/specs/01-frame/prd.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -ddx: - id: service-intake.prd - type: prd - activity: frame - authoring: - home: repo ---- - -# Service intake and routing - -## Summary - -MA-002 is a fabricated enterprise reference app for a requester and service coordinator. It exercises -submit an intake form, classify it, route it to a permitted queue and acknowledge assignment. Its purpose is to qualify a useful business journey -through Batten's platform integrations, rather than introduce a new engine. - -## Problem and Goals - -### Problem - -Users need an attributable business result across data, permission and failure -boundaries. A successful component call alone cannot establish this workflow. - -### Goals - -- Complete the stated journey while preserving current access and original identity. -- Detect the app-specific business invariant: Duplicate submission retains the same accepted intake identity and cannot silently create another case. -- Reproduce denied, stale, duplicate, cancelled and uncertain outcomes independently - of the host implementation. - -### Non-Goals - -No arbitrary external ticket connector is assumed. - -## Users and Scope - -The requester and service coordinator roles are assumed reference roles selected for this corpus, not -validated research personas. Erik owns real user validation and policy changes. -Business concepts: Intake, Assignment. All records and actors are fabricated. - -## Requirements - -### Must Have (P0) - -- Complete the journey and enforce its app-specific business invariant. -- Apply shared authority, lifecycle and evidence obligations without disclosure. -- Qualify required native integrations and real UI outcomes before a support claim. - -## Functional Requirements - -### Subsystem: Governed business journey - -Feature owner: FEAT-102. - -- **FR-1** — Submit an intake form, classify it, route it to a permitted queue and acknowledge assignment. -- **FR-2** — Duplicate submission retains the same accepted intake identity and cannot silently create another case. -- **FR-3** — Permission loss, stale inputs and interrupted work must preserve - authorized visibility, actual effects and the original uncertain outcome. -- **FR-4** — Supported surfaces and candidate cohorts must preserve the same - business semantics with attributable decisions and safe diagnostics. - -## Acceptance Test Sketches - -| Requirement | Scenario | Input | Expected Output | -| --- | --- | --- | --- | -| FR-1 | Main journey | fabricated request with a stable submission identity | one intake and one current assignment visible only to permitted users | -| FR-2 | Business boundary | repeat submission after its response is lost | original result is observed without creating another intake | -| FR-3 | Foreign or revoked actor | Original fixture with changed authority | Safe refusal; no hidden data or new business effect | -| FR-4 | Alternate client/cohort | Same app and business inputs | Same authorized outcome or explicit unsupported refusal | - -## Technical Context - -Integration requirements: tables,actions,messaging. These are corpus tags, not installable -module names or a claim that every adapter exists. Use UMF typed access with -PostgreSQL 18 for tables and Truss for graphs. Initial UI is a TypeScript browser -app under SDK ADR-015 and CONTRACT-005. No frontend framework is selected here. -Platform contracts are explicit dependencies in the test plan; original native -model/action packages require exact source and cohort qualification before build. - -## Constraints, Assumptions, Dependencies - -- Shared obligations in SDK CONTRACT-011 apply in full. -- Fixture states and role separation are conformance defaults, not production rules. -- Same local PostgreSQL instance does not imply one transaction across all services. -- Native authoring, host/client and required provider integrations precede app execution. - -## Risks - -| Risk | Probability | Impact | Mitigation | -| --- | --- | --- | --- | -| Fixture mistaken for a running app | Unmeasured | False support claim | Separate inventory from full execution qualification | -| UI or hook bypasses policy | Unmeasured | Unauthorized outcome | Public host boundary and server-side current authority checks | -| Backend changes business meaning | Unmeasured | Invalid result | Independent expectations and candidate-cohort replay | - -## Open Questions - -Erik supplies workload, latency/cost limits, real retention rules and production -policy. Those values block production qualification, not fabricated specification. - -## Success Criteria - -The governing story's positive and negative criteria pass through exact installed -native integrations and real client/host paths, with safe required telemetry. -The corpus inventory alone establishes none of those execution claims. diff --git a/docs/helix/reference-apps/service-intake/specs/01-frame/user-stories/US-102-journey.md b/docs/helix/reference-apps/service-intake/specs/01-frame/user-stories/US-102-journey.md deleted file mode 100644 index f619c1e..0000000 --- a/docs/helix/reference-apps/service-intake/specs/01-frame/user-stories/US-102-journey.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -ddx: - id: US-102 - type: user-stories - activity: frame - authoring: - home: repo - links: - - id: service-intake.prd - kind: derived_from ---- - -# US-102: Complete the service intake and routing journey - -**Feature**: FEAT-102 — Governed business journey -**Feature Requirements**: Reference-app business journey. -**PRD Requirements**: FR-1, FR-2, FR-3, FR-4. -**Priority**: P0. - -## Story - -**As a** requester and service coordinator -**I want** to complete the governed business journey -**So that** I can rely on its authorized result and recover safely after interruption. - -## Context - -This is application MA-002. Business rules below are explicit fabricated defaults. -They remain independent of whichever platform implementation is being qualified. - -## Walkthrough - -1. The actor opens permitted work and inspects its current state and revision. -2. The actor follows the journey: Submit an intake form, classify it, route it to a permitted queue and acknowledge assignment. -3. The host checks current authority and original operation identity. -4. The actor observes the result, or reconciles the original uncertain attempt. - -## Acceptance Criteria - -- [ ] **US-102-AC1** — Given fabricated request with a stable submission identity, when the actor performs the journey, then one intake and one current assignment visible only to permitted users. -- [ ] **US-102-AC2** — Given the app's business invariant, when actors repeat submission after its response is lost, then original result is observed without creating another intake. -- [ ] **US-102-AC3** — Given a foreign, anonymous or revoked actor, when they attempt the same operation or continuation, then no private result or unauthorized mutation is disclosed. -- [ ] **US-102-AC4** — Given response loss or cancellation, when the actor inspects original work, then actual effects and uncertainty remain attributable without a fresh blind command. -- [ ] **US-102-AC5** — Given the same business inputs on another supported surface or cohort, when the journey runs, then meaning and authority are preserved; unsupported required behavior refuses explicitly. - -## Edge Cases - -- Empty permitted data returns an authorized empty state, not hidden counts. -- Dependency failure exposes a safe outcome; a scripted replacement is not selected. -- Query and inspection do not mutate business records or retry uncertain commands. - -## Test Scenarios - -| Scenario | AC ID | Input / State | Action | Expected Result | -| --- | --- | --- | --- | --- | -| Main journey | US-102-AC1 | fabricated request with a stable submission identity | submit then route to a permitted team | one intake and one current assignment visible only to permitted users | -| Business invariant | US-102-AC2 | Same original fixture | repeat submission after its response is lost | original result is observed without creating another intake | -| Current authority | US-102-AC3 | Fixture foreign actor | Attempt and continue work | Safe denial without disclosure | -| Lost response | US-102-AC4 | Original possibly effective attempt | Observe original identity | Actual or uncertain outcome, no blind replay | -| Cohort parity | US-102-AC5 | Same semantic inputs | Exercise supported client/host | Same meaning or explicit refusal | - -## Dependencies - -Local PRD FR-1–4; SDK CONTRACT-003/004/005/011. Native platform model/action -contracts must be selected before executable app construction. Corpus tags: -tables,actions,messaging. Their presence requests support and grants no authority. - -## Out of Scope - -No arbitrary external ticket connector is assumed. Full platform implementation is not authorized by this app story. diff --git a/docs/helix/reference-apps/service-intake/specs/03-test/test-plan.md b/docs/helix/reference-apps/service-intake/specs/03-test/test-plan.md deleted file mode 100644 index cdad638..0000000 --- a/docs/helix/reference-apps/service-intake/specs/03-test/test-plan.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -ddx: - id: TP-102 - type: test-plan - activity: test - authoring: - home: repo - links: - - id: US-102 - kind: informed_by ---- - -# Service intake and routing: conformance allocation - -## Strategy - -**Goal**: Qualify MA-002's full authorized journey and distinct business invariant. -**Out of scope**: No arbitrary external ticket connector is assumed. -Use shared runner obligations from SDK CONTRACT-011 and preserve the independent -story expectations. No app result may be inferred from inventory validation. - -## Framework Selection & Cost - -| Layer | Framework | Justification | CI Time Impact | Maintenance Burden | -| --- | --- | --- | --- | --- | -| Inventory | Existing stdlib corpus checker | Exact scope/fixture integrity without app loading | Measured by shared command; no estimate supplied | Shared | -| Native actions | Qualified UMF/existing provider conformance | Reuse native ORM/graph semantics rather than duplicate them | Unknown; Erik owns budget | One shared runner, app data | -| UI journey | Real TypeScript client/browser harness | Authored UI requires independent observable journeys | Unknown; harness selection precedes app build | App acceptance scenarios | -| Model behavior where requested | Deterministic scripted API plus separate live API cut | Reproducible rules and actual integration prove different properties | Unknown | Fixture/model cohort scoped | - -## Critical Paths (P0) - -1. Story FR-1/2: one intake and one current assignment visible only to permitted users; invariant: Duplicate submission retains the same accepted intake identity and cannot silently create another case. -2. Story FR-3: unauthorized, stale, duplicate and uncertain work never loses its - actual authority or outcome boundary. -3. Story FR-4: exact supported client/cohort preserves business meaning and safe - diagnostics, including current identity on continuation. - -## Acceptance Criteria Layer Allocation - -| AC class / source | Story Test Plan | Primary Layer | Why this layer | -| --- | --- | --- | --- | -| US-102 main business and invariant classes | App story test plan at build handoff | Public client/host/native provider journey | Only full path proves business result | -| US-102 permission/recovery classes | Same app story test plan | Native integration | Current authority and durable effects cross boundaries | -| US-102 surface/candidate classes | Same app story test plan | Real browser plus separate CLI parity observation | TypeScript and server behavior require distinct observations | - -The build handoff must author the per-criterion story test plan and native model/ -technical design from installed HELIX templates before executable app code. -No preselected test function or framework is fabricated before that contract exists. - -## Secondary Paths (P1-P2) - -Optional UI polish cannot weaken required denial, uncertainty or accessibility -behavior. There is no optional escape from an active P0 criterion. - -## Test Data Strategy - -Use `../../fixtures.json` and the story's independent Given/When/Then examples. -Create isolated native namespaces with explicit PostgreSQL 18/Truss bindings and -scoped local identity. No production snapshot, credentials or inferred grants. -Every generated/native input retains its app/model/refinement identity. - -## Known Gaps - -Complete app execution requires qualified host/client, native model artifacts, -selected integrations and a trusted evidence runner. These are qualification -blockers, not accepted runtime risk or passing skips. SDK component storage -checks qualify only their own boundary. TypeScript UI is authored, not generated -from a declarative UI model. UI harness selection belongs to the app build design. - -## Build Commands - -From the SDK repository root: - -```sh -python scripts/check_micro_apps.py -python scripts/check_micro_apps.py --require-execution -``` - -The first command verifies inventory only; the second must refuse absent complete -app execution evidence. SDK platform dependencies are explicit file references: -`../../../../02-design/contracts/CONTRACT-003-composition.md`, -`../../../../02-design/contracts/CONTRACT-004-host-profiles.md`, -`../../../../02-design/contracts/CONTRACT-005-ux-builder-binding.md`, and -`../../../../02-design/contracts/CONTRACT-011-micro-app-conformance.md`. - -**Blocking gate**: Every active story criterion and shared obligation must have -trusted passing evidence for exact inputs before this app is called qualified. -No test-function ceiling increase; parameterize cases in shared machinery. - -## Diagnostic Test Strategy - -Exercise actual safe host audit and required telemetry across client, host and -providers, including a real receiver, refusal, retries, capture loss and shutdown. -A mocked exporter or parsed JSON is not receiver qualification. Erik supplies -workload and diagnostic overhead budgets before production qualification. diff --git a/docs/helix/site/build.py b/docs/helix/site/build.py index 39cb83c..93ebe4c 100644 --- a/docs/helix/site/build.py +++ b/docs/helix/site/build.py @@ -1,9 +1,7 @@ #!/usr/bin/env python3 """Build the Batten design microsite from source-stamped guide pages. Stdlib only.""" -import hashlib import html -import json import re import shutil from pathlib import Path @@ -21,15 +19,9 @@ ("hosting", "Hosting"), ("integrations", "Platform"), ("architecture", "Architecture"), - ("examples", "Examples"), ("about", "About this guide"), ] -PAGES.extend([ - (f"example-{app['slug']}", app["slug"].replace("-", " ").title()) - for app in json.loads( - (ROOT / "docs/helix/reference-apps/catalog.json").read_text() - )["apps"] -]) +PAGES.append(("example-approval-desk", "Approval Desk")) MARK = '' @@ -67,18 +59,14 @@ def markdown(text: str) -> tuple[str, list[tuple[str, str]]]: def sources(text: str) -> str: - refs = re.findall(r"", text) + refs = re.findall(r"", text) rows: list[str] = [] - for path, expected in refs: - value = (ROOT / path).read_text() - digest = hashlib.sha256( - "\n".join(x.rstrip() for x in value.splitlines()).encode() - ).hexdigest()[:16] - if digest != expected: - raise ValueError(f"Stale guide source: {path}") + for path in refs: + if not (ROOT / path).is_file(): + raise ValueError(f"Guide cites a missing source: {path}") label = Path(path).stem.replace("-", " ") rows.append( - f'
  • {html.escape(label)}{digest}
  • ' + f'
  • {html.escape(label)}
  • ' ) return ( '
    Read the design sources ↗
      ' @@ -176,7 +164,6 @@ def home(body: str, provenance: str) -> str:
      explicit capability bindings
      {MARK}batten core+ selected modules
      LocalStandaloneEmbedded

      Same application intent. Different host bindings.

      {strip}

      AVAILABLE NOW / 0.1.0a2

      Run the local approval desk.

      Submit, revise and independently approve requests through native UMF and Weft on PostgreSQL 18. Open the visual app registry and follow decisions through durable receipts and local telemetry.

      Python 3.13 · Local development identities · Fabricated data. This preview qualifies the recorded local cohort; production identity and the complete fleet remain separate work.

      -

      BUSINESS JOURNEYS / EXPLICIT BOUNDARIES

      See the platform through its apps.

      Follow twelve walkthroughs covering approvals, intake, case work, evidence, assisted review, entity graphs, grounded answers, triage, reconciliation, digests, access review and service handoff.

      Start with the runnable approval desk. The remaining specification walkthroughs explain intended behavior and the failure boundaries each app must qualify.

      Explore the example apps ↗

      A DELIBERATE FOUNDATION

      A small core.
      Room to compose.

      01 / NATIVE MEANING

      Build on the platform.

      Use UMF models and actions, Weft queries, Arras ontology and Tether agents through their public boundaries.

      02 / EXPLICIT CAPABILITIES

      Bring what the app needs.

      Select modules independently. Keep optional platform dependencies out of applications that do not use them.

      03 / GOVERNED FLEETS

      Operate a shared fleet.

      Share declarative services with explicit identity, limits and lifecycle. Qualify runtime upgrades against application evidence.

      {explorer()}

      GOOD INTERFACES, BY DESIGN

      Make room
      for the experience.

      ux-builder owns the design workflow, blueprint, components and themes. Batten’s proposed binding connects that experience to native models and governed operations.

      Explore the UI boundary ↗
      Review workspaceILLUSTRATION
      Review queue →ActivitySettings
      REVIEW / FABRICATED EXAMPLE

      A decision, with context.

      ✧ Recommendation

      Review the proposed change before approval.

      Declared actionApproveReviewAuthorityChecked by the host
      Review and confirm ↗
      diff --git a/docs/helix/site/publication-evidence.json b/docs/helix/site/publication-evidence.json deleted file mode 100644 index 1dd7e01..0000000 --- a/docs/helix/site/publication-evidence.json +++ /dev/null @@ -1,59 +0,0 @@ -{ - "date": "2026-11-02", - "source_commit": "23bd2f7", - "pages": 19, - "example_walkthroughs": 12, - "commands": { - "build": ".venv/bin/python docs/helix/site/build.py", - "publication": ".venv/bin/python docs/helix/site/verify.py", - "lint": ".venv/bin/ruff check docs/helix/site", - "typing": ".venv/bin/pyright docs/helix/site" - }, - "results": { - "source_digests": "passed", - "links_assets_fragments_prefix_safety": "passed", - "canonical_and_social_metadata": "passed", - "png_signature_dimensions": "passed", - "lint": "passed", - "strict_typing": "passed" - }, - "chromium": { - "viewports": [ - [ - 1365, - 900 - ], - [ - 390, - 844 - ] - ], - "routes_per_viewport": 19, - "horizontal_overflow": false, - "page_errors": [], - "examples_navigation": "passed", - "architecture_module_control": "passed", - "evidence_directory": ".cache/microsite-release" - }, - "independent_reader": { - "identity": "microsite_release_reader", - "pages": [ - "index", - "about", - "examples", - "example-*" - ], - "result": "passed after qualifying design claims and completing entity-update and settled-delivery steps" - }, - "preview_image": { - "path": "docs/helix/site/assets/social-preview.png", - "width": 1200, - "height": 630, - "sha256": "8298da89b19d6f021769b925243053f23ac97ebb27325c283c446b5ab2f8e6fc" - }, - "limits": [ - "This records local site verification, not SDK qualification.", - "Public deployment and Slackbot fetch must be verified after main deployment.", - "No Slack workspace message was posted or actual in-workspace unfurl rendered." - ] -} diff --git a/docs/helix/site/verification.json b/docs/helix/site/verification.json deleted file mode 100644 index eef5a41..0000000 --- a/docs/helix/site/verification.json +++ /dev/null @@ -1,71 +0,0 @@ -{ - "scope": "Batten documentation microsite only; no SDK/native/deployed support claim", - "guide": "Current explanations undergo an independent reader evaluation; source stamps and review receipts identify exact bodies.", - "checks": [ - "Current strict guide source/link/prose check", - "Current documentor reviewed-body stamps", - "Current stdlib static build and HTML link/anchor/prefix verification" - ], - "assembly": "Custom stdlib static assembly; documentor handles provenance, reader stamps and guide checks. No generated architecture model exists; the visual follows the cited architecture.", - "missing_source_kinds": [ - "complete application runtime", - "native cloud/deployed evidence" - ], - "hosting": "GitHub Pages publication uses the repository workflow; live delivery is verified separately from local microsite QA.", - "inputs": [ - { - "path": "docs/helix/site/build.py", - "sha256": "d8835dea82e82375ce48e6bd952994cc01438b7d0a1043eeefb0963ae975d84d" - }, - { - "path": "docs/helix/site/assets/favicon.svg", - "sha256": "92e2c8ce628aa45a1e9d04e5d1c82fbbfb8c80800ffabe1cb03c08ddfca58f3e" - }, - { - "path": "docs/helix/site/assets/site.css", - "sha256": "d5a0db3966b88126a8583ef91787936b9f08ccd46115ca796e9ffd3f66756636" - }, - { - "path": "docs/helix/site/assets/site.js", - "sha256": "be01ba8b3a3898063704861336f88ace4559764224993182fe42309caf748f9a" - }, - { - "path": "docs/helix/guide/developer/about.md", - "sha256": "e0fb18d706f5cfc9674cddf0c2abfdba0b1c79cc555c967233be1616fe71c3fe" - }, - { - "path": "docs/helix/guide/developer/architecture.md", - "sha256": "e5c75649268feaca3b098fc6495f9ff8165311169d5fbb11555c22934256ae63" - }, - { - "path": "docs/helix/guide/developer/composition.md", - "sha256": "50f1bf74a8e9d390ce75afb76e315adcbbe3cf2e5ab669eb06cfe3a4876fb1ff" - }, - { - "path": "docs/helix/guide/developer/hosting.md", - "sha256": "8d4e69d5d6b35ad753961688d8f14407e73ba26485680df5d5714522bff2a8b1" - }, - { - "path": "docs/helix/guide/developer/index.md", - "sha256": "1138ecfcf342894a5602e291a93f232511399734b6c722fa3b9f344cad9aac7f" - }, - { - "path": "docs/helix/guide/developer/integrations.md", - "sha256": "3d634da6794563dd1e03bc5ec71067fb5db88545b4c3ebb2b15ce6e6283d7e72" - }, - { - "path": ".helix.yml", - "sha256": "d40f14904cd12b1a9eb42b9072977dcc1c1c1798e47d9bef2dde7fee3bef70ed" - }, - { - "path": "docs/helix/site/verify.py", - "sha256": "479af98b72b1bf760a1ffd1e357de4fd3af9a7cb2f9475bcab8f3423647f9b98" - }, - { - "path": ".github/workflows/pages.yml", - "sha256": "eaa3f8f4c84e332ad2a74da17f6c722ded602ee89f2134eca065eda86ad3267a" - } - ], - "revision_checks": "Storage conditional/range/multipart and listing design: schema compilation and fabricated positive/negative shape cases passed. Governed artifact validation, independent six-page reader review and source checks passed after refreshing concurrent source changes; static assembly/link checks passed. Browser observations above belong to prior publication; no native backend, new browser or deployment evidence is claimed.", - "prior_browser_observation": "Prior main-revision Chromium interaction and responsive observations are historical; they were not rerun for this local source slice." -} diff --git a/examples/approval-desk/README.md b/examples/approval-desk/README.md index 6f990e0..59a4781 100644 --- a/examples/approval-desk/README.md +++ b/examples/approval-desk/README.md @@ -5,7 +5,7 @@ revision, and let a different person approve or reject it. Alex and Casey are requesters; Blake is an independent reviewer who can also submit requests. All identities and data are fabricated. -From the repository root, with Python 3.13, uv 0.13.7, Node 26.13.0, Bun 1.4.4 and Just installed: +From the repository root, with Python 3.13, uv, Bun and Just installed: ```sh uv sync --frozen --all-packages @@ -31,14 +31,9 @@ migrates tables. Restarting preserves requests and native receipts; local login sessions must be established again. `local.toml` supplies typed limits and port. No application environment variables or cloud credentials are needed. -The assembler downloads the original access dev8 wheel from `umf-v0.5.8` and -Codegen 0.10.8 from `umf-v0.10.8`, verifying each original SHA-256 digest. -Codegen selects exactly Core 0.10.8 through normal dependency resolution. -The SQL compiler is `umf-weft==0.4.57`. Batten -packages are built from this checkout. Dependencies are installed once at -composition time into `.cache/approval-runtime`; serving and calling the app do -not install Python or npm dependencies. Cohort and wheel hashes are recorded in -`.cache/approval-cohort.json`. +`just approval-prepare` bundles the TypeScript app, builds the Batten wheels from +this checkout and installs them with their dependencies into +`.cache/approval-runtime`. Serving and calling the app do not install anything. The installed CLI uses the same host, identity, business operations and native tables as the browser: @@ -48,29 +43,21 @@ tables as the browser: ``` The authoritative declaration is -[approval.umf.json](../../docs/helix/reference-apps/approval-desk/specs/02-design/models/approval.umf.json). +[approval.umf.json](model/approval.umf.json). Original UMF owns records, row permissions, queries, conditional commands and receipts; Weft owns SQL planning. App procedural hooks validate public inputs and map outcomes through Batten's table port. The UI is an authored TypeScript DOM application; it does not claim a declarative UI engine or ux-builder integration. -Verify the installed native path separately from the fast gate: +Browser scenarios (Playwright, real PostgreSQL 18 through pgserver): ```sh node node_modules/playwright/cli.js install chromium just approval-test -just check ``` -The two browser scenarios are JavaScript Playwright tests; Python Playwright, -pyee and the V8 compiler dependency are absent from this cohort. Oxlint enforces -the same four shape limits alongside TypeScript 7 compilation. - -This preview selects one record table, bounded queries (up to the model's declared -page size), one local host and this exact original platform cohort. Loopback stub -login is a development facility. Local redacted OpenTelemetry capture is not an -OTLP receiver qualification or fleet-deployment claim. The complete micro-app -conformance gate still refuses until its full execution obligations are met. +This preview has one record table, bounded queries, one local host and loopback +stub login, which is a development facility. It is not a production deployment. For UI or procedural-hook edits after the initial platform preparation, stop the local host, run `just approval-refresh`, then `just approval`. This rebuilds only diff --git a/docs/helix/reference-apps/approval-desk/specs/02-design/models/approval.umf.json b/examples/approval-desk/model/approval.umf.json similarity index 100% rename from docs/helix/reference-apps/approval-desk/specs/02-design/models/approval.umf.json rename to examples/approval-desk/model/approval.umf.json diff --git a/examples/approval-desk/pyproject.toml b/examples/approval-desk/pyproject.toml index b5798e8..ad870c9 100644 --- a/examples/approval-desk/pyproject.toml +++ b/examples/approval-desk/pyproject.toml @@ -17,6 +17,6 @@ batten-approval = "approval_desk.cli:main" packages = ["src/approval_desk"] [tool.hatch.build.targets.wheel.force-include] -"../../docs/helix/reference-apps/approval-desk/specs/02-design/models/approval.umf.json" = "approval_desk/models/approval.umf.json" +"model/approval.umf.json" = "approval_desk/models/approval.umf.json" "../../.cache/approval-ui" = "approval_desk/web" "local.toml" = "approval_desk/local.toml" diff --git a/justfile b/justfile index 80f3219..1965190 100644 --- a/justfile +++ b/justfile @@ -1,12 +1,12 @@ lint: - uv run python scripts/quality.py --lint + uv run python scripts/check.py --lint test: uv run pytest bun run test:native check: - uv run python scripts/quality.py + uv run python scripts/check.py # Build original pinned platform SDKs and install the isolated application cohort. approval-prepare: diff --git a/playwright.config.ts b/playwright.config.ts index 1dbc483..ff81a7d 100644 --- a/playwright.config.ts +++ b/playwright.config.ts @@ -1,12 +1,7 @@ import {defineConfig} from '@playwright/test'; -import {readFileSync} from 'node:fs'; -import {createHash} from 'node:crypto'; - -const sources = ['playwright.config.ts', 'tests/apps/approval.spec.ts', 'tests/apps/fixtures.ts', 'tests/apps/host.ts', 'tests/apps/native_probe.py', 'package.json', 'bun.lock', 'uv.lock', '.cache/approval-cohort.json']; export default defineConfig({ testDir: './tests/apps', - metadata: {sourceHashes: Object.fromEntries(sources.map(path => [path, createHash('sha256').update(readFileSync(path)).digest('hex')]))}, testMatch: '**/*.spec.ts', fullyParallel: false, workers: 1, diff --git a/pyproject.toml b/pyproject.toml index 4c90613..15f0fcf 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ requires-python = ">=3.13,<3.14" dependencies = [] [dependency-groups] -dev = ["ruff==0.17.3", "pyright==1.1.414", "pytest==9.2.0", "pytest-asyncio==1.4.1.post1", "hatchling==1.33.0", "build==1.6.1", "pydantic==2.14.2", "umf-core==0.10.8", "psycopg[binary]==3.3.7", "pgserver-pg18==18.6.1", "opentelemetry-sdk==1.45.2", "umf-weft==0.4.57", "opentelemetry-instrumentation-psycopg==0.66b2"] +dev = ["ruff==0.17.3", "pyright==1.1.414", "pytest==9.2.0", "pytest-asyncio==1.4.1.post1", "hatchling==1.33.0", "build==1.6.1", "pydantic==2.14.2", "umf-core==0.10.8", "umf-codegen==0.10.8", "umf-access==0.1.0.dev8", "psycopg[binary]==3.3.7", "pgserver-pg18==18.6.1", "opentelemetry-sdk==1.45.2", "umf-weft==0.4.57", "opentelemetry-instrumentation-psycopg==0.66b2"] [tool.uv] package = false diff --git a/scripts/boundary_checks.py b/scripts/boundary_checks.py index c06fa68..a784afc 100644 --- a/scripts/boundary_checks.py +++ b/scripts/boundary_checks.py @@ -4,8 +4,6 @@ import ast import io -import json -import subprocess import sys import tokenize from pathlib import Path @@ -111,11 +109,10 @@ def suppressions(path: Path) -> None: raise ValueError(f"{path}: rule suppression") -def inspect(root: Path, paths: list[Path], inventory: dict[str, list[str]]) -> int: +def inspect(root: Path, paths: list[Path], inventory: dict[str, list[str]]) -> None: python = [p for p in paths if p.suffix == ".py"] trees = {module(p, root): ast.parse(p.read_text()) for p in python} graph: dict[str, set[str]] = {} - count = 0 for path in paths: maximum = 488 if "tests" in path.parts else 500 if len(path.read_text().splitlines()) > maximum: @@ -139,33 +136,4 @@ def inspect(root: Path, paths: list[Path], inventory: dict[str, list[str]]) -> i ): if declared is None or sorted(declared) != sorted(inventory.get(name, [])): raise ValueError(f"missing or mismatched public inventory: {name}") - count += sum( - isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef)) - and n.name.startswith("test_") - for n in ast.walk(tree) - ) - count += browser_count(paths) cycles(graph) - return count - - -def browser_count(paths: list[Path]) -> int: - browser = [p for p in paths if p.suffix in {".js", ".mjs", ".ts"}] - if browser: - result = subprocess.run( - [ - "node", - str(Path(__file__).with_name("browser_census.mjs")), - *map(str, browser), - ], - check=False, - capture_output=True, - text=True, - ) - if result.returncode: - raise ValueError(result.stderr) - registered = json.loads(result.stdout)["count"] - if type(registered) is not int: - raise ValueError("invalid browser census") - return registered - return 0 diff --git a/scripts/browser_census.mjs b/scripts/browser_census.mjs deleted file mode 100644 index d416017..0000000 --- a/scripts/browser_census.mjs +++ /dev/null @@ -1,84 +0,0 @@ -import {readFileSync} from 'node:fs'; -import {relative} from 'node:path'; -import {parseSync} from 'oxc-parser'; - -const configuration = new Set(['extend', 'describe', 'use', 'setTimeout', 'slow', 'info', 'step', 'beforeAll', 'afterAll', 'beforeEach', 'afterEach']); -const forbidden = new Set(['skip', 'only', 'fixme']); -function callPath(node) { - if (!node) return ''; - if (node.type === 'Identifier') return node.name; - if (node.type === 'MemberExpression') return `${callPath(node.object)}.${node.property.name ?? node.property.value}`; - if (node.type === 'CallExpression') return callPath(node.callee); - return ''; -} -function bindingFor(node, bindings) { - const path = callPath(node); - return [...bindings].find(name => path === name || path.startsWith(name + '.')) ?? ''; -} -function bindImport(binding, source, tests, assertions) { - const imported = binding.imported?.name; - if (['test', 'it'].includes(imported)) tests.add(binding.local.name); - if (['expect', 'assert'].includes(imported) || source.startsWith('node:assert')) assertions.add(binding.local.name); - const framework = ['@playwright/test', 'node:test', 'bun:test'].includes(source); - if (framework && binding.type === 'ImportDefaultSpecifier') tests.add(binding.local.name); - if (framework && binding.type === 'ImportNamespaceSpecifier') { - for (const name of ['test', 'it']) tests.add(`${binding.local.name}.${name}`); - assertions.add(`${binding.local.name}.expect`); - } -} -function children(node) { - return Object.values(node).flatMap(value => Array.isArray(value) ? value : [value]).filter(value => value && typeof value === 'object' && typeof value.type === 'string'); -} -function isFunction(node) {return /Function(Expression|Declaration)$/.test(node.type) || node.type === 'ArrowFunctionExpression';} -function ownsAssertion(node, assertions) { - return children(node).some(child => { - if (isFunction(child)) return false; - if (child.type === 'CallExpression' && bindingFor(child.callee, assertions)) return true; - return ownsAssertion(child, assertions); - }); -} -function registration(node, tests, parent) { - if (node.type !== 'CallExpression') return false; - if (parent?.callee === node) return false; - const binding = bindingFor(node.callee, tests); - if (!binding) return false; - const modifiers = callPath(node.callee).slice(binding.length).split('.'); - if (modifiers.some(name => forbidden.has(name))) throw new Error('disabled/focused test registration'); - return !modifiers.some(name => configuration.has(name)); -} -function hiddenTest(node, canonical, assertions) { - if (canonical || !isFunction(node)) return false; - if (node.id?.name?.startsWith('test_')) return true; - return ownsAssertion(node.body ?? node, assertions); -} -function bindAliases(node, tests, assertions) { - if (node.type === 'VariableDeclarator' && node.id.type === 'Identifier') { - if (bindingFor(node.init, tests)) tests.add(node.id.name); - if (bindingFor(node.init, assertions)) assertions.add(node.id.name); - } - for (const child of children(node)) bindAliases(child, tests, assertions); -} -function inspect(path) { - const source = readFileSync(path, 'utf8'); - const parsed = parseSync(path, source, {sourceType: 'module'}); - if (parsed.errors.length) throw new Error(`${path}: browser source parse failed: ${JSON.stringify(parsed.errors)}`); - if (parsed.comments.some(comment => /(oxlint|eslint)-disable|@ts-ignore|@ts-nocheck/.test(comment.value))) throw new Error(`${path}: rule suppression`); - const tests = new Set(['test', 'it']); - const assertions = new Set(['expect', 'assert']); - for (const node of parsed.program.body.filter(node => node.type === 'ImportDeclaration')) { - for (const binding of node.specifiers) bindImport(binding, node.source.value, tests, assertions); - } - bindAliases(parsed.program, tests, assertions); - const registrations = []; - const hidden = []; - function visit(node, canonical = false, parent = null) { - const registered = registration(node, tests, parent); - if (registered) registrations.push({file: relative(process.cwd(), path), line: source.slice(0, node.start).split('\n').length}); - if (hiddenTest(node, canonical, assertions)) hidden.push({file: relative(process.cwd(), path), name: node.id?.name ?? ''}); - for (const child of children(node)) visit(child, canonical || registered, node); - } - visit(parsed.program); - return {count: registrations.length + hidden.length, registrations, hidden}; -} -const results = process.argv.slice(2).map(inspect); -process.stdout.write(JSON.stringify({count: results.reduce((sum, result) => sum + result.count, 0), registrations: results.flatMap(result => result.registrations), hidden: results.flatMap(result => result.hidden)}) + '\n'); diff --git a/scripts/quality.py b/scripts/check.py similarity index 69% rename from scripts/quality.py rename to scripts/check.py index 6ccc612..5f9bd74 100644 --- a/scripts/quality.py +++ b/scripts/check.py @@ -1,4 +1,4 @@ -"""One quality recipe shared by local execution, hooks and CI.""" +"""The one check recipe shared by local runs and CI.""" from __future__ import annotations @@ -9,11 +9,10 @@ def main() -> None: parser = argparse.ArgumentParser() - parser.add_argument("--lint", action="store_true") + parser.add_argument("--lint", action="store_true", help="skip pytest") args = parser.parse_args() commands = [ - [sys.executable, "scripts/check_boundaries.py", "--base", "HEAD"], - [sys.executable, "scripts/check_micro_apps.py"], + [sys.executable, "scripts/check_boundaries.py"], ["ruff", "check", "."], ["ruff", "format", "--check", "."], ["pyright"], diff --git a/scripts/check_boundaries.py b/scripts/check_boundaries.py index b5d3926..2d53489 100644 --- a/scripts/check_boundaries.py +++ b/scripts/check_boundaries.py @@ -1,70 +1,19 @@ -"""Common import/export/shape/test-budget gate, including bootstrap evidence.""" +"""Import-boundary, public-API inventory and source-shape check.""" from __future__ import annotations -import argparse import json -import subprocess from pathlib import Path from boundary_checks import inspect from boundary_model import sources -from check_policy import policy - - -def check(root: Path, base: str) -> int: - subprocess.run( - ["git", "rev-parse", "--verify", base], - cwd=root, - check=True, - capture_output=True, - ) - policy(root) - baseline_path = root / "scripts/quality-baseline.json" - baseline = json.loads(baseline_path.read_text()) - inventory = json.loads((root / "scripts/public-api.json").read_text()) - count = inspect(root, sources(root), inventory) - if count > baseline["test_functions"]: - raise ValueError( - f"test count {count} exceeds measured ceiling {baseline['test_functions']}" - ) - prior = subprocess.run( - ["git", "show", f"{base}:scripts/quality-baseline.json"], - cwd=root, - capture_output=True, - text=True, - ) - if prior.returncode == 0: - previous = json.loads(prior.stdout) - if previous == baseline: - parent = subprocess.run( - ["git", "show", f"{base}^:scripts/quality-baseline.json"], - cwd=root, - capture_output=True, - text=True, - ) - if parent.returncode == 0: - previous = json.loads(parent.stdout) - if baseline["test_functions"] > previous["test_functions"]: - raise ValueError("test ceiling increased") - elif ( - baseline["initial_base"] - != subprocess.check_output( - ["git", "rev-parse", base], cwd=root, text=True - ).strip() - ): - raise ValueError("missing accepted baseline") - return count def main() -> None: - parser = argparse.ArgumentParser() - parser.add_argument("--base", required=True) - args = parser.parse_args() root = Path(__file__).resolve().parents[1] - print( - f"Boundary/shape/census checks passed: {check(root, args.base)} behavior functions" - ) + inventory = json.loads((root / "scripts/public-api.json").read_text()) + inspect(root, sources(root), inventory) + print("Import boundaries and public API inventory are consistent.") if __name__ == "__main__": diff --git a/scripts/check_micro_apps.py b/scripts/check_micro_apps.py deleted file mode 100644 index e4cd56c..0000000 --- a/scripts/check_micro_apps.py +++ /dev/null @@ -1,137 +0,0 @@ -"""Validate reference-app inventory, never substitute metadata for app execution.""" - -from __future__ import annotations - -import argparse -import json -import re -from pathlib import Path -from typing import Any, cast - -OBLIGATIONS = { - "AUTH", - "IDENTITY", - "COMMANDS", - "LIFECYCLE", - "LIMITS", - "PARITY", - "OBSERVABILITY", -} -FIELDS = {"id", "slug", "root", "ui", "modules", "story", "obligations"} - - -def inside(root: Path, value: str) -> Path: - path = root / value - if Path(value).is_absolute() or not path.resolve().is_relative_to(root.resolve()): - raise ValueError("corpus path escapes repository") - return path - - -def app(root: Path, value: dict[str, Any], workflow: Path) -> None: - if set(value) != FIELDS or not re.fullmatch(r"MA-\d{3}", value["id"]): - raise ValueError("invalid application inventory fields or ID") - if not re.fullmatch(r"[a-z]+(?:-[a-z]+)*", value["slug"]): - raise ValueError("invalid application slug") - if value["root"] != "docs/helix/reference-apps/" + value["slug"]: - raise ValueError("application root mismatch") - if value["ui"] not in {"typescript", "headless"}: - raise ValueError("invalid application UI delivery") - tags(value) - directory = inside(root, value["root"]) - marker = json.loads((directory / ".helix.yml").read_text()) - if marker["flows"] != [{"id": "helix", "root": "specs/"}]: - raise ValueError("application HELIX scope mismatch") - binding = marker["x-batten-app"] - if ( - binding["id"] != value["id"] - or (directory / binding["workflow"]).resolve() != workflow.resolve() - ): - raise ValueError("application workflow binding mismatch") - documents(directory, value) - - -def tags(value: dict[str, Any]) -> None: - for key in ("modules", "obligations"): - raw: object = value[key] - if not isinstance(raw, list): - raise ValueError("integration/obligation tags must be arrays") - entries = cast(list[object], raw) - if ( - not entries - or any(not isinstance(x, str) or not x for x in entries) - or len(set(entries)) != len(entries) - ): - raise ValueError("invalid or duplicate integration/obligation tags") - if set(value["obligations"]) != OBLIGATIONS: - raise ValueError("missing or unknown shared obligation") - if not re.fullmatch(r"US-\d{3}", value["story"]): - raise ValueError("invalid story identity") - - -def documents(directory: Path, value: dict[str, Any]) -> None: - for path, kind in ( - ("01-frame/prd.md", "prd"), - ( - f"01-frame/features/FEAT-{value['story'].split('-')[1]}-business-journey.md", - "feature-specification", - ), - (f"01-frame/user-stories/{value['story']}-journey.md", "user-stories"), - ("03-test/test-plan.md", "test-plan"), - ): - text = (directory / "specs" / path).read_text() - if not text.startswith("---\n") or f"type: {kind}\n" not in text: - raise ValueError("missing governed application artifact") - story = directory / "specs/01-frame/user-stories" / (value["story"] + "-journey.md") - text = story.read_text() - if any(f"**{value['story']}-AC{i}**" not in text for i in range(1, 6)): - raise ValueError("missing application acceptance criterion") - if "specs/" not in (directory / "AGENTS.md").read_text(): - raise ValueError("missing application scope instructions") - fixture = json.loads((directory / "fixtures.json").read_text()) - if fixture["application"] != value["id"] or not fixture["record"]["id"].startswith( - "fabricated-" - ): - raise ValueError("fixture identity mismatch") - if fixture["actors"]["permitted"] == fixture["actors"]["foreign"]: - raise ValueError("foreign actor is not distinct") - - -def inventory(root: Path) -> int: - catalog = json.loads((root / "docs/helix/reference-apps/catalog.json").read_text()) - if set(catalog) != {"version", "workflow", "apps"} or catalog["version"] != 1: - raise ValueError("invalid corpus version or fields") - workflow = inside(root, catalog["workflow"]) - if not workflow.is_file() or not catalog["apps"]: - raise ValueError("missing workflow or apps") - seen: set[str] = set() - roots: set[str] = set() - for value in catalog["apps"]: - if value["id"] in seen or value["root"] in roots: - raise ValueError("duplicate app identity or root") - app(root, value, workflow) - seen.add(value["id"]) - roots.add(value["root"]) - actual = { - str(path.parent.relative_to(root)) - for path in (root / "docs/helix/reference-apps").glob("*/.helix.yml") - } - if actual != roots: - raise ValueError("unregistered or missing application scope") - return len(seen) - - -def main() -> None: - parser = argparse.ArgumentParser() - parser.add_argument("--require-execution", action="store_true") - args = parser.parse_args() - count = inventory(Path(__file__).resolve().parents[1]) - print(f"Reference-app inventory only: {count} scoped specifications validated") - if args.require_execution: - parser.exit( - 1, - "Complete app execution is unqualified: trusted runner/host/client/provider evidence required\n", - ) - - -if __name__ == "__main__": - main() diff --git a/scripts/check_policy.py b/scripts/check_policy.py deleted file mode 100644 index 101e9ad..0000000 --- a/scripts/check_policy.py +++ /dev/null @@ -1,73 +0,0 @@ -"""Reject disabled quality rules and increases to accepted shape ceilings.""" - -from __future__ import annotations - -import json -import tomllib -from pathlib import Path -from typing import Any, cast - -REQUIRED = { - "E4", - "E7", - "E9", - "F", - "I", - "C901", - "PLR0911", - "PLR0912", - "PLR0915", - "PLR0904", -} -CAPS = { - "max-returns": 6, - "max-branches": 9, - "max-statements": 40, - "max-public-methods": 15, -} - - -def policy(root: Path) -> None: - config: dict[str, Any] = tomllib.loads((root / "pyproject.toml").read_text()) - lint = config["tool"]["ruff"]["lint"] - if not REQUIRED <= set(lint["select"]): - raise ValueError("required lint rules disabled") - if any( - lint.get(key) - for key in ( - "ignore", - "extend-ignore", - "per-file-ignores", - "extend-per-file-ignores", - ) - ): - raise ValueError("lint exceptions are forbidden") - if lint["mccabe"]["max-complexity"] > 10: - raise ValueError("complexity ceiling increased") - if any(lint["pylint"][key] > limit for key, limit in CAPS.items()): - raise ValueError("shape ceiling increased") - if config["tool"]["pyright"]["typeCheckingMode"] != "strict": - raise ValueError("strict typing disabled") - browser_policy(root) - - -def browser_policy(root: Path) -> None: - config = json.loads((root / ".oxlintrc.json").read_text()) - if config.get("overrides") or config.get("ignorePatterns"): - raise ValueError("browser lint exceptions are forbidden") - for name, maximum in { - "complexity": 10, - "max-lines-per-function": 60, - "max-depth": 4, - "max-classes-per-file": 1, - }.items(): - severity, options = config["rules"][name] - limit = ( - cast(dict[str, Any], options).get("max") - if isinstance(options, dict) - else options - ) - if severity != "error" or type(limit) is not int or limit > maximum: - raise ValueError("browser shape ceiling increased or rule disabled") - if config["rules"]["complexity"][1].get("variant") != "classic": - raise ValueError("browser complexity semantics changed") diff --git a/scripts/prepare_approval.py b/scripts/prepare_approval.py index a4a224d..1296ab4 100644 --- a/scripts/prepare_approval.py +++ b/scripts/prepare_approval.py @@ -1,52 +1,23 @@ -"""Assemble an isolated pinned platform cohort, original SDK wheels and app assets.""" +"""Build the approval desk web assets and wheels and install them into .cache/approval-runtime.""" from __future__ import annotations import argparse -import hashlib -import json import subprocess import sys import tomllib from pathlib import Path -UMF_WHEELS = { - "umf_access-0.1.0.dev8-py3-none-any.whl": { - "release": "umf-v0.5.8", - "sha256": "1a21c1ddd59f6b23e9f0b33228280564af0e96bb4d13699b89616d5143e4fd23", - }, - "umf_codegen-0.10.8-py3-none-any.whl": { - "release": "umf-v0.10.8", - "sha256": "0d21acef3171442b818a4ad1dfdbaf99cc0f0f5557e5c670d5ce56243235dbc5", - }, -} +PACKAGES = ("contracts", "runtime", "tables", "asgi", "umf-postgres", "local") +FIND_LINKS = "https://github.com/DocumentDrivenDX/pgserver/releases/expanded_assets/pg18.6-pgv0.8.6-r2" def run(args: list[str], cwd: Path) -> None: subprocess.run(args, cwd=cwd, check=True) -def upstream_wheels(wheels: Path) -> list[str]: - wheels.mkdir(parents=True, exist_ok=True) - urls = { - name: f"https://github.com/DocumentDrivenDX/umf/releases/download/{source['release']}/{name}" - for name, source in UMF_WHEELS.items() - } - result: list[str] = [] - for name, source in UMF_WHEELS.items(): - path = wheels / name - if not path.exists(): - from urllib.request import urlopen - - with urlopen(urls[name], timeout=60) as response: - path.write_bytes(response.read()) - if hashlib.sha256(path.read_bytes()).hexdigest() != source["sha256"]: - raise ValueError(f"upstream wheel digest mismatch: {name}") - result.append(str(path)) - return result - - -def assets(root: Path) -> Path: +def assets(root: Path) -> None: + """Bundle the TypeScript app into .cache/approval-ui, which the app wheel includes.""" target = root / ".cache/approval-ui" target.mkdir(parents=True, exist_ok=True) source = root / "examples/approval-desk/web" @@ -64,132 +35,68 @@ def assets(root: Path) -> Path: ) for name in ("index.html", "style.css", "tokens.css", "thumbnail.svg"): (target / name).write_bytes((source / name).read_bytes()) - return target -def refresh_app(root: Path) -> None: - runtime = root / ".cache/approval-runtime/bin/python" - receipt_path = root / ".cache/approval-cohort.json" - if not runtime.exists() or not receipt_path.exists(): - raise ValueError("prepare the complete platform cohort first") - assets(root) - wheels = root / ".cache/approval-wheels" +def build(root: Path, project: Path, wheels: Path) -> Path: + metadata = tomllib.loads((project / "pyproject.toml").read_text())["project"] run( [ - sys.executable, - "-m", + "uv", "build", - "--no-isolation", "--wheel", - "--outdir", + "--out-dir", str(wheels), - str(root / "examples/approval-desk"), - ], - root, - ) - metadata = tomllib.loads( - (root / "examples/approval-desk/pyproject.toml").read_text() - )["project"] - wheel = ( - wheels - / f"novirhyza_batten_approval_desk-{metadata['version']}-py3-none-any.whl" - ) - run( - [ - "uv", - "pip", - "install", - "--python", - str(runtime), - "--no-deps", - "--reinstall", - str(wheel), + str(project), ], root, ) - receipt = json.loads(receipt_path.read_text()) - receipt["wheels"][wheel.name] = hashlib.sha256(wheel.read_bytes()).hexdigest() - receipt["model_sha256"] = hashlib.sha256( - ( - root - / "docs/helix/reference-apps/approval-desk/specs/02-design/models/approval.umf.json" - ).read_bytes() - ).hexdigest() - receipt_path.write_text(json.dumps(receipt, indent=2, sort_keys=True) + "\n") - print( - "Refreshed installed app; restart the local host to admit its new artifact digest." + name = metadata["name"].replace("-", "_") + return wheels / f"{name}-{metadata['version']}-py3-none-any.whl" + + +def constraints(root: Path, path: Path) -> None: + lock = tomllib.loads((root / "uv.lock").read_text()) + path.write_text( + "\n".join( + p["name"] + "==" + p["version"] + for p in lock["package"] + if "registry" in p.get("source", {}) + ) + + "\n" ) def main() -> None: parser = argparse.ArgumentParser() - parser.add_argument("--app-only", action="store_true") + parser.add_argument( + "--app-only", action="store_true", help="rebuild only the example app" + ) args = parser.parse_args() root = Path(__file__).resolve().parents[1] - if args.app_only: - refresh_app(root) - return - assets(root) - wheels = root / ".cache/approval-wheels" + cache = root / ".cache" + wheels = cache / "approval-wheels" + runtime = cache / "approval-runtime" wheels.mkdir(parents=True, exist_ok=True) - built = upstream_wheels(wheels) - projects = [ - *[ - root / "packages" / ("batten-" + name) - for name in ( - "contracts", - "runtime", - "tables", - "asgi", - "umf-postgres", - "local", - ) - ], - root / "examples/approval-desk", - ] - for project in projects: - metadata = tomllib.loads((project / "pyproject.toml").read_text())["project"] - name = metadata["name"].replace("-", "_") - run( - [ - sys.executable, - "-m", - "build", - "--no-isolation", - "--wheel", - "--outdir", - str(wheels), - str(project), - ], - root, - ) - built.append(str(wheels / f"{name}-{metadata['version']}-py3-none-any.whl")) - run( - [ - "uv", - "pip", - "install", - "--python", - sys.executable, - "--no-deps", - "--reinstall", - *built[:2], - ], - root, + assets(root) + app = root / "examples/approval-desk" + projects = ( + [app] + if args.app_only + else [ + *(root / "packages" / ("batten-" + name) for name in PACKAGES), + app, + ] ) - runtime = root / ".cache/approval-runtime" + built = [str(build(root, project, wheels)) for project in projects] if not (runtime / "bin/python").exists(): run(["uv", "venv", "--python", sys.executable, str(runtime)], root) - constraints = root / ".cache/approval-constraints.txt" - lock = tomllib.loads((root / "uv.lock").read_text()) - constraints.write_text( - "\n".join( - p["name"] + "==" + p["version"] - for p in lock["package"] - if "registry" in p.get("source", {}) - ) - + "\n" - ) + pins = cache / "approval-constraints.txt" + constraints(root, pins) + reinstall = [ + arg + for wheel in built + for arg in ("--reinstall-package", Path(wheel).name.split("-")[0]) + ] run( [ "uv", @@ -197,57 +104,19 @@ def main() -> None: "install", "--python", str(runtime / "bin/python"), + "--prerelease=allow", "--constraint", - str(constraints), + str(pins), "--find-links", str(wheels), "--find-links", - "https://github.com/DocumentDrivenDX/pgserver/releases/expanded_assets/pg18.6-pgv0.8.6-r2", - *[ - argument - for project in projects - for argument in ( - "--reinstall-package", - tomllib.loads((project / "pyproject.toml").read_text())["project"][ - "name" - ], - ) - ], + FIND_LINKS, + *reinstall, *built, ], root, ) - receipt = { - "umf_artifacts": UMF_WHEELS, - "python": ".".join(str(part) for part in sys.version_info[:3]), - "wheels": { - Path(p).name: hashlib.sha256(Path(p).read_bytes()).hexdigest() - for p in built - }, - "model_sha256": hashlib.sha256( - ( - root - / "docs/helix/reference-apps/approval-desk/specs/02-design/models/approval.umf.json" - ).read_bytes() - ).hexdigest(), - "packages": json.loads( - subprocess.check_output( - [ - str(runtime / "bin/python"), - "-I", - "-c", - "import importlib.metadata,json; print(json.dumps({d.metadata['Name']: d.version for d in importlib.metadata.distributions()}))", - ], - text=True, - ) - ), - } - (root / ".cache/approval-cohort.json").write_text( - json.dumps(receipt, indent=2, sort_keys=True) + "\n" - ) - print( - "Prepared original UMF/Weft/PostgreSQL 18 candidate and installed app artifacts; no schema applied." - ) + print("Installed the approval desk into", runtime) if __name__ == "__main__": diff --git a/scripts/quality-baseline.json b/scripts/quality-baseline.json deleted file mode 100644 index 221d8f7..0000000 --- a/scripts/quality-baseline.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "initial_base": "61f4ae1efedb393e339cac99f182bc9b57085907", - "test_functions": 17 -} diff --git a/tests/boundaries/test_boundaries.py b/tests/boundaries/test_boundaries.py new file mode 100644 index 0000000..f97d8ef --- /dev/null +++ b/tests/boundaries/test_boundaries.py @@ -0,0 +1,61 @@ +"""Positive and negative controls for the import-boundary checker.""" + +from __future__ import annotations + +from pathlib import Path + +import pytest +from boundary_checks import inspect + +FORBIDDEN = [ + ("runtime/a.py", "import batten.databricks\n__all__ = []\n"), + ( + "databricks/a.py", + "from batten.storage._values import Hidden\n__all__ = []\n", + ), + ("storage/a.py", "import databricks.sdk\n__all__ = []\n"), + ("runtime/a.py", "import psycopg\n__all__ = []\n"), + ("tables/a.py", "import umf_access\n__all__ = []\n"), + ("storage/a.py", "__all__ = ['unexpected']\n"), + ("storage/a.py", "import praxis.database\n__all__ = []\n"), + ( + "storage/a.py", + "from os import getenv as read_setting\nread_setting('X')\n__all__ = []\n", + ), + ( + "storage/a.py", + "import importlib as loader\nloader.import_module('x')\n__all__ = []\n", + ), + ("storage/a.py", "import os # noqa: F401\n__all__ = []\n"), +] + + +def write(tmp_path: Path, name: str, relative: str, text: str) -> Path: + path = tmp_path / name / "packages/example/src/batten" / relative + path.parent.mkdir(parents=True) + path.write_text(text) + return path + + +def test_clean_module_passes(tmp_path: Path) -> None: + path = write(tmp_path, "clean", "contracts/a.py", "__all__ = []\n") + inspect(tmp_path / "clean", [path], {"batten.contracts.a": []}) + + +@pytest.mark.parametrize(("relative", "text"), FORBIDDEN) +def test_forbidden_source_is_rejected(tmp_path: Path, relative: str, text: str) -> None: + path = write(tmp_path, "bad", relative, text) + with pytest.raises(ValueError): + inspect(tmp_path / "bad", [path], {}) + + +def test_import_cycle_is_rejected(tmp_path: Path) -> None: + directory = tmp_path / "cycle/packages/example/src/batten/storage" + directory.mkdir(parents=True) + paths = [directory / "a.py", directory / "b.py"] + paths[0].write_text("from . import b\n__all__ = []\n") + paths[1].write_text("from . import a\n__all__ = []\n") + with pytest.raises(ValueError, match="cycle"): + inspect( + tmp_path / "cycle", paths, {"batten.storage.a": [], "batten.storage.b": []} + ) diff --git a/tests/quality/test_gate.py b/tests/quality/test_gate.py deleted file mode 100644 index 9723fe2..0000000 --- a/tests/quality/test_gate.py +++ /dev/null @@ -1,230 +0,0 @@ -"""Actual boundary-checker positive/negative controls, not an alternative parser.""" - -from __future__ import annotations - -import json -import shutil -import subprocess -from pathlib import Path - -import pytest -from boundary_checks import inspect -from check_boundaries import check -from check_micro_apps import inventory - - -def test_import_cycle_private_and_inventory_controls(tmp_path: Path) -> None: - """@covers US-007-AC3 @covers US-007-AC4""" - fixtures = [ - ("contracts/a.py", "__all__ = []\n", 0), - ("runtime/a.py", "import batten.databricks\n__all__ = []\n", None), - ( - "databricks/a.py", - "from batten.storage._values import Hidden\n__all__ = []\n", - None, - ), - ("storage/a.py", "import databricks.sdk\n__all__ = []\n", None), - ("runtime/a.py", "import psycopg\n__all__ = []\n", None), - ("tables/a.py", "import umf_access\n__all__ = []\n", None), - ("storage/a.py", "__all__ = ['unexpected']\n", None), - ("storage/a.py", "import praxis.database\n__all__ = []\n", None), - ( - "storage/a.py", - "from os import getenv as read_setting\nread_setting('X')\n__all__ = []\n", - None, - ), - ( - "storage/a.py", - "import importlib as loader\nloader.import_module('unknown')\n__all__ = []\n", - None, - ), - ( - "databricks/a.py", - "from databricks.sdk._internal import hidden\n__all__ = []\n", - None, - ), - ( - "runtime/browser.ts", - "import {test} from '@playwright/test'; test('one', () => {});", - 1, - ), - ( - "runtime/alias.ts", - "import {test as scenario} from '@playwright/test'; scenario('one', () => {});", - 1, - ), - ( - "runtime/reassigned.ts", - "import {test} from '@playwright/test'; const scenario = test; scenario('one', () => {});", - 1, - ), - ( - "runtime/hidden.ts", - "import {test, expect as check} from '@playwright/test'; function hidden() {check(1).toBe(1)} test('one', () => hidden());", - 2, - ), - ( - "runtime/skipped.ts", - "import {test} from '@playwright/test'; test.skip('one', () => {});", - None, - ), - ( - "runtime/namespace.ts", - "import * as suite from '@playwright/test'; suite.test('one', () => {});", - 1, - ), - ( - "runtime/namespace-skip.ts", - "import * as suite from '@playwright/test'; suite.test.skip('one', () => {});", - None, - ), - ("runtime/suppressed.ts", "// oxlint-disable\nexport const fixture = 1;", None), - ] - for i, (relative, text, allowed) in enumerate(fixtures): - root = tmp_path / str(i) - path = root / "packages/example/src/batten" / relative - path.parent.mkdir(parents=True) - path.write_text(text) - if allowed is not None: - assert inspect(root, [path], {"batten.contracts.a": []}) == allowed - else: - with pytest.raises(ValueError): - inspect(root, [path], {}) - root, paths = cycle_fixture(tmp_path) - with pytest.raises(ValueError, match="cycle"): - inspect(root, paths, {"batten.storage.a": [], "batten.storage.b": []}) - - repository, baseline, project = baseline_fixture(tmp_path) - with pytest.raises(ValueError, match="missing accepted baseline"): - check(repository, "HEAD") - subprocess.run(["git", "-C", str(repository), "add", "."], check=True) - subprocess.run( - [ - "git", - "-C", - str(repository), - "-c", - "user.name=Fixture", - "-c", - "user.email=fixture@example.invalid", - "commit", - "-qm", - "accepted baseline", - ], - check=True, - ) - baseline.write_text(json.dumps({"initial_base": "wrong", "test_functions": 1})) - with pytest.raises(ValueError, match="ceiling increased"): - check(repository, "HEAD") - - assert inventory(project) > 0 - strict = subprocess.run( - [ - str(project / ".venv/bin/python"), - str(project / "scripts/check_micro_apps.py"), - "--require-execution", - ], - capture_output=True, - text=True, - ) - assert ( - strict.returncode == 1 - and "inventory only" in strict.stdout - and "unqualified" in strict.stderr - ) - for label, text, expected in [ - ("valid", "function valid(value) { return value; }", True), - ( - "complexity", - "function complex(value) { return " - + " || ".join(f"value === {i}" for i in range(11)) - + "; }", - False, - ), - ("lines", "function long() {\n" + "value();\n" * 59 + "}\n", False), - ( - "depth", - "function nested(a) { if(a) { if(a) { if(a) { if(a) { if(a) { call(); } } } } } }", - False, - ), - ("classes", "class First {}\nclass Second {}", False), - ]: - fixture = tmp_path / (label + ".js") - fixture.write_text(text) - result = subprocess.run( - [ - str(project / "node_modules/.bin/oxlint"), - "--config", - str(project / ".oxlintrc.json"), - str(fixture), - ], - capture_output=True, - text=True, - ) - assert (result.returncode == 0) is expected, result.stdout + result.stderr - copied, catalog_path, original = corpus_fixture(tmp_path, project) - for change in ["identity", "scope", "obligation"]: - catalog = json.loads(original) - if change == "identity": - catalog["apps"].append(catalog["apps"][0]) - elif change == "scope": - catalog["apps"][0]["root"] = "../escape" - else: - catalog["apps"][0]["obligations"].remove("AUTH") - catalog_path.write_text(json.dumps(catalog)) - with pytest.raises(ValueError): - inventory(copied) - - -def baseline_fixture(tmp_path: Path) -> tuple[Path, Path, Path]: - repository = tmp_path / "baseline" - repository.mkdir() - subprocess.run(["git", "init", "-q", str(repository)], check=True) - subprocess.run( - [ - "git", - "-C", - str(repository), - "-c", - "user.name=Fixture", - "-c", - "user.email=fixture@example.invalid", - "commit", - "--allow-empty", - "-qm", - "fixture", - ], - check=True, - ) - scripts = repository / "scripts" - scripts.mkdir() - project = Path(__file__).resolve().parents[2] - for name in ("pyproject.toml", ".oxlintrc.json"): - (repository / name).write_text((project / name).read_text()) - (scripts / "public-api.json").write_text("{}") - baseline = scripts / "quality-baseline.json" - baseline.write_text(json.dumps({"initial_base": "wrong", "test_functions": 0})) - return repository, baseline, project - - -def corpus_fixture(tmp_path: Path, project: Path) -> tuple[Path, Path, str]: - copied = tmp_path / "corpus" - shutil.copytree( - project / "docs/helix/reference-apps", copied / "docs/helix/reference-apps" - ) - workflow = copied / "docs/helix/04-build/batten-app-workflow.md" - workflow.parent.mkdir(parents=True) - workflow.write_text("reference workflow") - catalog_path = copied / "docs/helix/reference-apps/catalog.json" - original = catalog_path.read_text() - return copied, catalog_path, original - - -def cycle_fixture(tmp_path: Path) -> tuple[Path, list[Path]]: - root = tmp_path / "cycle" - directory = root / "packages/example/src/batten/storage" - directory.mkdir(parents=True) - paths = [directory / "a.py", directory / "b.py"] - paths[0].write_text("from . import b\n__all__ = []\n") - paths[1].write_text("from . import a\n__all__ = []\n") - return root, paths diff --git a/uv.lock b/uv.lock index 201ba2c..e71a849 100644 --- a/uv.lock +++ b/uv.lock @@ -52,6 +52,8 @@ dev = [ { name = "pytest" }, { name = "pytest-asyncio" }, { name = "ruff" }, + { name = "umf-access" }, + { name = "umf-codegen" }, { name = "umf-core" }, { name = "umf-weft" }, ] @@ -71,6 +73,8 @@ dev = [ { name = "pytest", specifier = "==9.2.0" }, { name = "pytest-asyncio", specifier = "==1.4.1.post1" }, { name = "ruff", specifier = "==0.17.3" }, + { name = "umf-access", specifier = "==0.1.0.dev8" }, + { name = "umf-codegen", specifier = "==0.10.8" }, { name = "umf-core", specifier = "==0.10.8" }, { name = "umf-weft", specifier = "==0.4.57" }, ] @@ -593,6 +597,30 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/0a/66/9a06c2227fedfd4919f0eaaa8b94377d9730882a7e4f95823c9a331ab5e1/tzdata-2026.6-py2.py3-none-any.whl", hash = "sha256:0a10eec6e13ef16b627fabed9a5f2ba61a62b1c67f327305f4e7e412a70b4aec", size = 348210, upload-time = "2026-10-28T09:57:07.276Z" }, ] +[[package]] +name = "umf-access" +version = "0.1.0.dev8" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "pydantic" }, + { name = "typing-extensions" }, +] +wheels = [ + { url = "https://files.pythonhosted.org/packages/df/a2/253e6ae631c8acc7954d5d0d82a96c4d079466361b3f8f5e85dab33723bb/umf_access-0.1.0.dev8-py3-none-any.whl", hash = "sha256:1a21c1ddd59f6b23e9f0b33228280564af0e96bb4d13699b89616d5143e4fd23", size = 580062, upload-time = "2026-10-30T00:25:00.251Z" }, +] + +[[package]] +name = "umf-codegen" +version = "0.10.8" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "umf-core" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/0d/fa/ee03bffb19ab1d3e5b7e97117603bced108f0cc5b5abcc99c6faf4e411f6/umf_codegen-0.10.8.tar.gz", hash = "sha256:f094d73900004debf70516ab5f7e18fb84c564ba5861e305ae29fe021464c52d", size = 53112, upload-time = "2026-11-04T04:23:50.637Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/67/80/42c92c17e5365f6a9c74489eed9fed52b3a31513d1cf90940a0bf05ef947/umf_codegen-0.10.8-py3-none-any.whl", hash = "sha256:0d21acef3171442b818a4ad1dfdbaf99cc0f0f5557e5c670d5ce56243235dbc5", size = 66201, upload-time = "2026-11-04T04:23:49.377Z" }, +] + [[package]] name = "umf-core" version = "0.10.8" From 34492b24448d23f9d6c69d3abfd6bf2fdfb8a457 Mon Sep 17 00:00:00 2001 From: Erik LaBianca Date: Wed, 11 Nov 2026 17:13:35 -0500 Subject: [PATCH 2/7] Add unit tests for contracts, runtime, ASGI, UMF provider and local host Co-Authored-By: Claude Sonnet 5.5 --- docs/helix/01-frame/work-items.jsonl | 29 --- pyproject.toml | 2 +- tests/asgi/test_registry.py | 111 ++++++++++++ tests/asgi/test_routes.py | 178 ++++++++++++++++++ tests/contracts/test_values.py | 43 +++++ tests/local/test_local_runtime.py | 57 ++++++ tests/local/test_local_units.py | 115 ++++++++++++ tests/runtime/test_host.py | 261 +++++++++++++++++++++++++++ tests/umf_postgres/test_compile.py | 43 +++++ tests/umf_postgres/test_provider.py | 102 +++++++++++ uv.lock | 49 +++++ 11 files changed, 960 insertions(+), 30 deletions(-) delete mode 100644 docs/helix/01-frame/work-items.jsonl create mode 100644 tests/asgi/test_registry.py create mode 100644 tests/asgi/test_routes.py create mode 100644 tests/contracts/test_values.py create mode 100644 tests/local/test_local_runtime.py create mode 100644 tests/local/test_local_units.py create mode 100644 tests/runtime/test_host.py create mode 100644 tests/umf_postgres/test_compile.py create mode 100644 tests/umf_postgres/test_provider.py diff --git a/docs/helix/01-frame/work-items.jsonl b/docs/helix/01-frame/work-items.jsonl deleted file mode 100644 index e4f2349..0000000 --- a/docs/helix/01-frame/work-items.jsonl +++ /dev/null @@ -1,29 +0,0 @@ -{"acceptance":"Exercise US-004 refusals and lossless identity/outcome translation; require exact upstream executor/native evidence before a positive execution support claim; never synthesize rollback or retry.","created_at":"2026-10-30T00:35:18.700464Z","dependencies":[{"issue_id":"batten-0b5cad5d","depends_on_id":"batten-916449b0","type":"blocks","created_at":"2026-10-30T00:35:18Z"},{"issue_id":"batten-0b5cad5d","depends_on_id":"batten-9a5d7122","type":"blocks","created_at":"2026-10-30T00:35:18Z"}],"description":"US-004; CONTRACT-003/004. UMF owns declarations and executor obligations. Missing upstream support is an explicit affected-component refusal.","execution_authorized":false,"id":"batten-0b5cad5d","issue_type":"task","labels":["area:api","composition","review-required"],"notes":"UMF owns saga semantics; this remains an integration task. Preserve exact native executor/profile/receipt behavior, no Batten saga engine. Reference app workflows may not replace missing upstream semantics with unrestricted procedural orchestration.","parent":"batten-26f7cebc","priority":0,"schema_version":1,"status":"open","title":"Bind qualified UMF saga capabilities without new semantics","updated_at":"2026-11-02T17:44:09.96276Z"} -{"acceptance":"Review CONTRACT-003/004, native schema basis and US-001/002/004; preserve all original scope and authority boundaries. Implementation requires explicit build authorization.","created_at":"2026-10-30T00:35:08.525785Z","dependencies":[{"issue_id":"batten-26f7cebc","depends_on_id":"batten-389b9109","type":"blocks","created_at":"2026-10-30T00:35:08Z"}],"description":"Govern docs/helix/01-frame/features/FEAT-009-composition-and-hosting.md and PRD FR-34–38; independent capability, hosting and placement axes. UMF owns saga semantics.","execution_authorized":false,"id":"batten-26f7cebc","issue_type":"epic","labels":["area:api","composition","review-required"],"priority":0,"schema_version":1,"status":"open","title":"FEAT-009: Composition and hosting","updated_at":"2026-10-30T00:35:08.525785Z"} -{"acceptance":"Exercise all US-002 criteria: same app/different bindings, drift before effects, reverse owned cleanup with borrowed preservation, retained shutdown uncertainty and unsupported identity/placement refusal.","created_at":"2026-10-30T00:35:15.623845Z","dependencies":[{"issue_id":"batten-2b9e6014","depends_on_id":"batten-916449b0","type":"blocks","created_at":"2026-10-30T00:35:15Z"}],"description":"US-002; CONTRACT-004 and CONTRACT-001. Keep application bytes equal and ownership/identity/placement explicit. Standalone profile shares contract; deployed support requires separate qualification.","execution_authorized":false,"id":"batten-2b9e6014","issue_type":"task","labels":["area:api","composition","review-required"],"parent":"batten-26f7cebc","priority":0,"schema_version":1,"status":"open","title":"Bind local and embedded profiles through public lifecycle","updated_at":"2026-10-30T00:35:15.623845Z"} -{"acceptance":"Document-review, triage and knowledge journeys prove permission-filtered inputs, bounded calls, provenance, unavailable API and human approval; no new agent loop.","created_at":"2026-11-02T17:39:45.900313Z","dependencies":[{"issue_id":"batten-341346a4","depends_on_id":"batten-2b9e6014","type":"blocks","created_at":"2026-11-02T17:39:45Z"}],"description":"Bind Tether through public agent/model APIs with host-owned aliases, budgets and scoped tools; reuse qualified platform search/retrieval. Local host accepts explicit model API. Scripted fixtures and live model API evidence remain separate.","execution_authorized":false,"id":"batten-341346a4","issue_type":"task","labels":["integration","reference-apps"],"parent":"batten-f27c8039","priority":1,"schema_version":1,"status":"open","title":"Integrate Tether model gateway and scoped retrieval","updated_at":"2026-11-02T17:39:45.900313Z"} -{"acceptance":"Owner reviews the complete PRD, audit, architecture, distribution/API/versioning proposals and boundary/quality contracts; records the disposition of affected open decisions; authorizes the next phase explicitly.","created_at":"2026-10-29T21:38:50.425072Z","description":"Review docs/helix/README.md and its artifact packet. Resolve or explicitly bound the owner decisions in docs/helix/01-frame/decision-points.md. Migration planning and product/checker code require explicit owner authorization after this review.","execution_authorized":false,"id":"batten-389b9109","issue_type":"epic","labels":["area:docs","review-required"],"notes":"Owner authorized the composition/hosting requirements, contracts and ddx packet. Review docs/helix/README.md including FEAT-009, the FEAT-002 ux-builder binding, CONTRACT-003/004/005 and ADR-008/009. This is not authorization for migration, product/checker code, deployment or publication. Original open policy decisions remain bounded.","priority":0,"schema_version":1,"status":"open","title":"Review Batten requirements, module boundaries, and public host API","updated_at":"2026-10-30T00:35:07.467895Z"} -{"acceptance":"A TypeScript app uses public client and scoped services locally with no private host import, client-derived authority or startup migration.","created_at":"2026-11-02T17:39:44.608471Z","dependencies":[{"issue_id":"batten-39cb6fe0","depends_on_id":"batten-2b9e6014","type":"blocks","created_at":"2026-11-02T17:39:44Z"}],"description":"Provide the CONTRACT-005 client/host bridge, explicit local-only stub identity and PostgreSQL 18 pgserver configuration. Bind original invocation identity, current server authority, lifecycle, navigation and downloads. Browser has no direct provider credentials.","execution_authorized":false,"id":"batten-39cb6fe0","issue_type":"task","labels":["integration","reference-apps"],"parent":"batten-ff2246f4","priority":1,"schema_version":1,"status":"open","title":"Deliver public TypeScript client and local development host","updated_at":"2026-11-02T17:39:44.608471Z"} -{"acceptance":"Evidence-based scope matrix; reference app specs and fixtures with isolated HELIX bindings; reusable workflow and conformance contract; common-gate corpus checks with negative controls; no fabricated app execution or cloud qualification.","created_at":"2026-11-02T17:30:48.309601Z","description":"Owner requests Batten scope evaluation, independently HELIX-scoped enterprise reference applications, shared conformance allocation and a reusable Batten app authoring workflow. Preserve native UMF/ux-builder ownership and distinguish inventory validation from app execution.","execution_authorized":true,"id":"batten-4192222e","issue_type":"task","notes":"Scope evaluation, twelve isolated app specs/fixtures, shared HELIX workflow, TypeScript UI ruling and ordered native integration queue complete. Nine integration tasks queued; existing host/admission/saga/ux-builder tasks retained. Common quality gate: 17 behavior functions, 20 cases passed; twelve app inventories and strict execution refusal verified; 60 artifacts validate; six guide pages independently approved. No complete app/runtime qualification claim. Future integration builds remain separately authorized; changes uncommitted.","priority":1,"schema_version":1,"status":"closed","title":"Define enterprise micro-app corpus and HELIX app workflow","updated_at":"2026-11-02T17:49:07.302021Z"} -{"acceptance":"PR is merged with all required CI checks passing; tag runtime-v0.1.0a1 on the merge commit; publish a GitHub prerelease containing seven Batten wheels, the two exact original UMF dependency wheels, qualified cohort and native/browser receipts, constraints and lock, SHA256SUMS, installation instructions, and the final rebuilt 19-page static microsite archive; verify asset hashes and installation instructions; no PyPI distribution is created.","created_at":"2026-11-02T22:57:48.536996Z","description":"Commit and integrate the approval desk/runtime and app registry; qualify the latest compatible published dependency cohort; publish the initial GitHub runtime prerelease with exact wheels, receipts, checksums, installation instructions and static microsite artifact. No PyPI upload.","id":"batten-4da8e46a","issue_type":"task","labels":["release","runtime"],"owner":"erik","priority":0,"schema_version":1,"status":"in_progress","title":"Cut initial Batten local runtime prerelease","updated_at":"2026-11-02T22:58:01.50007Z"} -{"acceptance":"Complete-app qualification runs positive/negative public client-host-native-provider journeys; missing integrations, stale evidence and deliberately broken adapters fail.","created_at":"2026-11-02T17:39:46.542287Z","dependencies":[{"issue_id":"batten-5fa3e526","depends_on_id":"batten-916449b0","type":"blocks","created_at":"2026-11-02T17:39:46Z"},{"issue_id":"batten-5fa3e526","depends_on_id":"batten-a77dd24d","type":"blocks","created_at":"2026-11-02T17:44:01Z"},{"issue_id":"batten-5fa3e526","depends_on_id":"batten-39cb6fe0","type":"blocks","created_at":"2026-11-02T17:44:02Z"}],"description":"Reuse UMF action semantics and existing qualified verification tooling. Supply independent app oracle, exact input/cohort evidence and negative controls. Server action properties and actual TypeScript browser journeys are distinct; no declarative UI generator claim. Preserve decreasing test-function ceiling.","execution_authorized":false,"id":"batten-5fa3e526","issue_type":"task","labels":["integration","reference-apps"],"parent":"batten-7449118b","priority":1,"schema_version":1,"status":"open","title":"Integrate native action CLI and reference-app conformance runner","updated_at":"2026-11-02T17:44:02.802074Z"} -{"acceptance":"Observe real browser/server outcomes for every US-003 criterion, including accessible state recovery, keyboard confirmation, revocation/download denial, original uncertain invocation and independent upstream lint/audit.","created_at":"2026-10-30T00:35:16.934968Z","dependencies":[{"issue_id":"batten-6e684a3f","depends_on_id":"batten-2b9e6014","type":"blocks","created_at":"2026-10-30T00:35:16Z"},{"issue_id":"batten-6e684a3f","depends_on_id":"batten-9a5d7122","type":"blocks","created_at":"2026-10-30T00:35:16Z"},{"issue_id":"batten-6e684a3f","depends_on_id":"batten-a77dd24d","type":"blocks","created_at":"2026-11-02T17:44:11Z"},{"issue_id":"batten-6e684a3f","depends_on_id":"batten-39cb6fe0","type":"blocks","created_at":"2026-11-02T17:44:13Z"}],"description":"US-003; CONTRACT-005. Preserve original blueprint/assets, exact UMF targets and server authority across local/embedded hosts. No shell or credential exposure.","execution_authorized":false,"id":"batten-6e684a3f","issue_type":"task","labels":["area:api","composition","review-required"],"notes":"Owner delivery ruling 2026-11-02: initial UI is an authored TypeScript app using the public Batten client. Integrate qualified ux-builder tooling/assets where useful; do not build or wait for a Batten declarative UI compiler. Preserve server authorization and actual browser evidence. ADR-015 and reference approval-desk govern the first slice.","parent":"batten-71704f7a","priority":0,"schema_version":1,"status":"open","title":"Bind ux-builder review queue to the public Batten client","updated_at":"2026-11-02T17:44:13.759468Z"} -{"acceptance":"After owner review, refine FEAT-002 into behavior-level acceptance tied to FR-8 and FR-9; preserve the native public platform and cleanroom boundaries; implementation completion requires exercising evidence for every requirement and the actual boundary/quality gates.","created_at":"2026-10-29T21:38:51.238367Z","dependencies":[{"issue_id":"batten-71704f7a","depends_on_id":"batten-389b9109","type":"blocks","created_at":"2026-10-29T21:38:51Z"}],"description":"Product scope is governed by docs/helix/01-frame/prd.md (FR-8 and FR-9) and docs/helix/01-frame/feature-registry.md. All specified behavior remains in scope. This is a scope record, not an authorized implementation or migration sequence. Wait for owner review before elaborating or coding.","execution_authorized":false,"id":"batten-71704f7a","issue_type":"epic","labels":["area:ui","area:api","review-required"],"priority":0,"schema_version":1,"status":"open","title":"FEAT-002: Operations and interfaces","updated_at":"2026-10-29T21:38:51.238367Z"} -{"acceptance":"After owner review, refine FEAT-007 into behavior-level acceptance tied to FR-29 through FR-31; preserve the native public platform and cleanroom boundaries; implementation completion requires exercising evidence for every requirement and the actual boundary/quality gates.","created_at":"2026-10-29T21:38:53.229868Z","dependencies":[{"issue_id":"batten-7449118b","depends_on_id":"batten-389b9109","type":"blocks","created_at":"2026-10-29T21:38:53Z"}],"description":"Product scope is governed by docs/helix/01-frame/prd.md (FR-29 through FR-31) and docs/helix/01-frame/feature-registry.md. All specified behavior remains in scope. This is a scope record, not an authorized implementation or migration sequence. Wait for owner review before elaborating or coding.","execution_authorized":false,"id":"batten-7449118b","issue_type":"epic","labels":["area:cli","area:docs","review-required"],"priority":0,"schema_version":1,"status":"open","title":"FEAT-007: Author tooling and qualification","updated_at":"2026-10-29T21:38:53.229868Z"} -{"acceptance":"Specifications integrated on main; real quality scaffold and negative controls precede source; native STO acceptance, installed artifact closure and full common quality recipe pass; no cloud or full-runtime qualification claims.","created_at":"2026-10-30T01:46:32.191025Z","description":"Owner authorized specification integration and local-first source implementation. Governed by US-006, SD-001/TD-006, CONTRACT-002/006/100 and docs/helix/04-build/implementation-plan.md. Preserve optional storage wheel and adapter-managed POSIX authority.","execution_authorized":true,"id":"batten-780deb3b","issue_type":"task","notes":"Owner authorized commit and merge on 2026-10-30. Local storage implementation complete; full quality recipe rerun passes 17 behavior functions / 20 cases, strict typing, import/shape/export rules, ESLint and isolated wheel installation. Specifications integrated at 61f4ae1. Source and verification are being integrated from codex/local-object-storage into main; no full runtime, Databricks or deployed-service qualification claim.","priority":0,"schema_version":1,"status":"closed","title":"Implement qualified local object storage and modularity gates","updated_at":"2026-10-30T16:33:16.956178Z"} -{"acceptance":"After owner review, refine FEAT-001 into behavior-level acceptance tied to FR-1 through FR-7; preserve the native public platform and cleanroom boundaries; implementation completion requires exercising evidence for every requirement and the actual boundary/quality gates.","created_at":"2026-10-29T21:38:50.840083Z","dependencies":[{"issue_id":"batten-8c7aceaa","depends_on_id":"batten-389b9109","type":"blocks","created_at":"2026-10-29T21:38:50Z"}],"description":"Product scope is governed by docs/helix/01-frame/prd.md (FR-1 through FR-7) and docs/helix/01-frame/feature-registry.md. All specified behavior remains in scope. This is a scope record, not an authorized implementation or migration sequence. Wait for owner review before elaborating or coding.","execution_authorized":false,"id":"batten-8c7aceaa","issue_type":"epic","labels":["area:api","review-required"],"priority":0,"schema_version":1,"status":"open","title":"FEAT-001: Declaration and admission","updated_at":"2026-10-29T21:38:50.840083Z"} -{"acceptance":"Evidence-library reconciles row/blob publication using original outcome identity; local and exact Volumes evidence remain distinct.","created_at":"2026-11-02T17:39:47.68106Z","dependencies":[{"issue_id":"batten-8dd09b19","depends_on_id":"batten-2b9e6014","type":"blocks","created_at":"2026-11-02T17:39:47Z"},{"issue_id":"batten-8dd09b19","depends_on_id":"batten-a77dd24d","type":"blocks","created_at":"2026-11-02T17:44:05Z"}],"description":"Reuse completed stdlib local provider through host scope injection and separately integrate public Databricks Files/Volumes APIs in its optional module. Qualify exact conditional/range/upload cohort; never emulate unsupported remote guarantees.","execution_authorized":false,"id":"batten-8dd09b19","issue_type":"task","labels":["integration","reference-apps"],"parent":"batten-f27c8039","priority":1,"schema_version":1,"status":"open","title":"Integrate scoped storage bindings and Databricks Volumes adapter","updated_at":"2026-11-02T17:44:05.804819Z"} -{"acceptance":"Exercise all US-001 criteria with canonical citations: deterministic graph and safe refusal, relevant unknown preservation, handler admission and headless wheel imports. Record observed results and ratchet outcome.","created_at":"2026-10-30T00:35:14.306736Z","dependencies":[{"issue_id":"batten-916449b0","depends_on_id":"batten-d1cac24b","type":"blocks","created_at":"2026-10-30T00:35:13Z"}],"description":"US-001; CONTRACT-003. Use trusted validated metadata projections and actual installed wheel closures; no provider/application import during assessment.","execution_authorized":false,"id":"batten-916449b0","issue_type":"task","labels":["area:api","composition","review-required"],"parent":"batten-26f7cebc","priority":0,"schema_version":1,"status":"open","title":"Build effect-free application composition assessment","updated_at":"2026-10-30T00:35:14.306736Z"} -{"acceptance":"Document exact supported public APIs and cohort, original source hashes and limitations; prove supported bindings or record explicit upstream gaps without fallback engines or blueprint copies.","created_at":"2026-10-30T00:35:11.390076Z","dependencies":[{"issue_id":"batten-9a5d7122","depends_on_id":"batten-389b9109","type":"blocks","created_at":"2026-10-30T00:35:11Z"}],"description":"Resolve public reference/extension APIs and ux-builder design-first/blueprint/client integration surfaces. Pin exact artifacts and record independent evidence; do not install or execute during this design packet.","execution_authorized":false,"id":"batten-9a5d7122","issue_type":"task","labels":["area:api","composition","review-required"],"parent":"batten-26f7cebc","priority":0,"schema_version":1,"status":"open","title":"Qualify public UMF and ux-builder composition cohort","updated_at":"2026-10-30T00:35:11.390076Z"} -{"acceptance":"Approval desk runs through public host and native pgserver PostgreSQL 18 with current identity, stale-write and denied-row proof.","created_at":"2026-11-02T17:39:43.391544Z","dependencies":[{"issue_id":"batten-a77dd24d","depends_on_id":"batten-2b9e6014","type":"blocks","created_at":"2026-11-02T17:39:43Z"}],"description":"Use UMF typed persistence/ORM over PostgreSQL 18; no Batten ORM or SQL compiler. Qualify person/delegated principals, row policies, typed read/action/bulk, transactions, schema lifecycle and installed artifacts. Reuse existing UMF native tests and add only Batten boundary outcomes.","execution_authorized":false,"id":"batten-a77dd24d","issue_type":"task","labels":["integration","reference-apps"],"parent":"batten-d7d0bc66","priority":1,"schema_version":1,"status":"open","title":"Integrate UMF PostgreSQL table ORM with Batten scopes","updated_at":"2026-11-02T17:39:43.391544Z"} -{"acceptance":"Runnable local PostgreSQL 18 approval app with native policy, independent approver and stale revision refusal, original outcome observation, real browser/native evidence and passing modularity/quality gates. Record exact candidate dependencies and unsupported qualification boundaries.","created_at":"2026-11-02T19:10:33.869691Z","description":"Owner authorized first reference app build after corpus push. Implement bounded public host/client and optional UMF PostgreSQL adapter; original native model, explicit local setup and authored TypeScript UI. Governing US-101, app build plan and ADR-016. Do not replace native ORM or touch production infrastructure.","execution_authorized":true,"id":"batten-b6c932f2","issue_type":"task","notes":"Built the local approval app and visual runtime registry using installed modular Batten wheels, original UMF/Weft and PostgreSQL 18. Native/browser suite: 2 passed; fast gate: 18 passed; function ceiling: 17. Exact source/wheel hashes and scope are in approval-desk specs/03-test/local-execution.json. Registry navigation, thumbnails, scoped cookies, stale/self/foreign/revoked behavior, actual lost-response receipt recovery and restart/CLI parity verified. Broad integration and full-corpus/OTLP qualifications remain separate. Implementation is uncommitted; earlier spec packet 27f0876 is pushed.","parent":"batten-71704f7a","priority":0,"schema_version":1,"status":"closed","title":"Build local approval desk through native UMF tables and TypeScript","updated_at":"2026-11-02T21:13:35.423795Z"} -{"acceptance":"After owner review, refine FEAT-004 into behavior-level acceptance tied to FR-18 through FR-22; preserve the native public platform and cleanroom boundaries; implementation completion requires exercising evidence for every requirement and the actual boundary/quality gates.","created_at":"2026-10-29T21:38:52.044978Z","dependencies":[{"issue_id":"batten-bfc427db","depends_on_id":"batten-389b9109","type":"blocks","created_at":"2026-10-29T21:38:51Z"}],"description":"Product scope is governed by docs/helix/01-frame/prd.md (FR-18 through FR-22) and docs/helix/01-frame/feature-registry.md. All specified behavior remains in scope. This is a scope record, not an authorized implementation or migration sequence. Wait for owner review before elaborating or coding.","execution_authorized":false,"id":"batten-bfc427db","issue_type":"epic","labels":["area:api","area:infra","review-required"],"priority":0,"schema_version":1,"status":"open","title":"FEAT-004: Workers and background execution","updated_at":"2026-10-29T21:38:52.044978Z"} -{"acceptance":"Observed allowed and forbidden import, cycle/private access and shape controls; same local/hook/CI gate; first reviewed suite establishes the measured count and future downward-only ceiling.","created_at":"2026-10-30T00:35:09.789138Z","dependencies":[{"issue_id":"batten-d1cac24b","depends_on_id":"batten-389b9109","type":"blocks","created_at":"2026-10-30T00:35:09Z"}],"description":"Implement CONTRACT-002 after explicit build authorization, including new UMF/hosting/optional UX boundaries. No source implementation is authorized by this work item.","execution_authorized":false,"id":"batten-d1cac24b","issue_type":"task","labels":["area:api","composition","review-required"],"parent":"batten-7449118b","priority":0,"schema_version":1,"status":"open","title":"Establish actual boundary, shape and measured test gates","updated_at":"2026-10-30T00:35:09.789138Z"} -{"acceptance":"After owner review, refine FEAT-003 into behavior-level acceptance tied to FR-10 through FR-17; preserve the native public platform and cleanroom boundaries; implementation completion requires exercising evidence for every requirement and the actual boundary/quality gates.","created_at":"2026-10-29T21:38:51.636641Z","dependencies":[{"issue_id":"batten-d7d0bc66","depends_on_id":"batten-389b9109","type":"blocks","created_at":"2026-10-29T21:38:51Z"}],"description":"Product scope is governed by docs/helix/01-frame/prd.md (FR-10 through FR-17) and docs/helix/01-frame/feature-registry.md. All specified behavior remains in scope. This is a scope record, not an authorized implementation or migration sequence. Wait for owner review before elaborating or coding.","execution_authorized":false,"id":"batten-d7d0bc66","issue_type":"epic","labels":["area:data","area:api","review-required"],"priority":0,"schema_version":1,"status":"open","title":"FEAT-003: Native data and identity","updated_at":"2026-10-29T21:38:51.636641Z"} -{"acceptance":"After owner review, refine FEAT-005 into behavior-level acceptance tied to FR-23 and FR-24; preserve the native public platform and cleanroom boundaries; implementation completion requires exercising evidence for every requirement and the actual boundary/quality gates.","created_at":"2026-10-29T21:38:52.440048Z","dependencies":[{"issue_id":"batten-e0ce2fd9","depends_on_id":"batten-389b9109","type":"blocks","created_at":"2026-10-29T21:38:52Z"}],"description":"Product scope is governed by docs/helix/01-frame/prd.md (FR-23 and FR-24) and docs/helix/01-frame/feature-registry.md. All specified behavior remains in scope. This is a scope record, not an authorized implementation or migration sequence. Wait for owner review before elaborating or coding.","execution_authorized":false,"id":"batten-e0ce2fd9","issue_type":"epic","labels":["area:infra","area:cli","review-required"],"priority":0,"schema_version":1,"status":"open","title":"FEAT-005: Artifact delivery and lifecycle","updated_at":"2026-10-29T21:38:52.440048Z"} -{"acceptance":"Intake and triage cases prove competing consumers, retry identity, fan-out, crash/revocation recovery and no false exactly-once effect claim.","created_at":"2026-11-02T17:39:45.308058Z","dependencies":[{"issue_id":"batten-e3665458","depends_on_id":"batten-2b9e6014","type":"blocks","created_at":"2026-11-02T17:39:45Z"}],"description":"Implement CONTRACT-007 delivery/settlement through PostgreSQL 18 using available qualified platform primitives; audit existing project support before writing new machinery. No new broker by default. Preserve uncertain outcomes and independent consumer authority.","execution_authorized":false,"id":"batten-e3665458","issue_type":"task","labels":["integration","reference-apps"],"parent":"batten-bfc427db","priority":1,"schema_version":1,"status":"open","title":"Integrate PostgreSQL 18 durable messaging","updated_at":"2026-11-02T17:39:45.308058Z"} -{"acceptance":"Service-handoff proves exact authorized export binding, hidden export denial, independent receiver authority and drift/revocation refusal.","created_at":"2026-11-02T17:39:47.124877Z","dependencies":[{"issue_id":"batten-e50731a9","depends_on_id":"batten-916449b0","type":"blocks","created_at":"2026-11-02T17:39:47Z"},{"issue_id":"batten-e50731a9","depends_on_id":"batten-2b9e6014","type":"blocks","created_at":"2026-11-02T17:39:47Z"},{"issue_id":"batten-e50731a9","depends_on_id":"batten-e7af34e7","type":"blocks","created_at":"2026-11-02T17:44:03Z"},{"issue_id":"batten-e50731a9","depends_on_id":"batten-e3665458","type":"blocks","created_at":"2026-11-02T17:44:04Z"}],"description":"Reuse native UMF service ontology, Truss graph foundation and public Arras discovery under CONTRACT-009. Exact references and current grants bind independently of discovery. No core ontology branches.","execution_authorized":false,"id":"batten-e50731a9","issue_type":"task","labels":["integration","reference-apps"],"parent":"batten-26f7cebc","priority":1,"schema_version":1,"status":"open","title":"Integrate Arras service discovery and cross-app binding","updated_at":"2026-11-02T17:44:04.624365Z"} -{"acceptance":"Entity-directory and case relationship journeys pass native Truss with hidden endpoint/count refusal and exact installed cohort evidence.","created_at":"2026-11-02T17:39:43.990209Z","dependencies":[{"issue_id":"batten-e7af34e7","depends_on_id":"batten-2b9e6014","type":"blocks","created_at":"2026-11-02T17:39:43Z"}],"description":"Use public UMF typed graph access and Truss; preserve original model identities, native policy/transaction limits and Weft ownership. Do not rebuild graph ORM or ontology engine. Sharing pgserver with tables does not prove shared transaction semantics.","execution_authorized":false,"id":"batten-e7af34e7","issue_type":"task","labels":["integration","reference-apps"],"parent":"batten-d7d0bc66","priority":1,"schema_version":1,"status":"open","title":"Integrate UMF Truss graph ORM with Batten scopes","updated_at":"2026-11-02T17:39:43.990209Z"} -{"acceptance":"Scheduled digest and reconciliation prove competing ticks, bounded work, cancellation, durable run identity and separate job deployment authority.","created_at":"2026-11-02T17:39:48.268041Z","dependencies":[{"issue_id":"batten-edc84420","depends_on_id":"batten-2b9e6014","type":"blocks","created_at":"2026-11-02T17:39:48Z"},{"issue_id":"batten-edc84420","depends_on_id":"batten-0b5cad5d","type":"blocks","created_at":"2026-11-02T17:44:15Z"}],"description":"Bind existing platform execution/job interfaces; Batten owns permission/lifecycle glue and safe outcome translation. Use UMF actions and upstream sagas. No second workflow runtime.","execution_authorized":false,"id":"batten-edc84420","issue_type":"task","labels":["integration","reference-apps"],"parent":"batten-bfc427db","priority":1,"schema_version":1,"status":"open","title":"Integrate platform workers scheduled jobs and attribution","updated_at":"2026-11-02T17:44:15.514372Z"} -{"acceptance":"After owner review, refine FEAT-006 into behavior-level acceptance tied to FR-25 through FR-28; preserve the native public platform and cleanroom boundaries; implementation completion requires exercising evidence for every requirement and the actual boundary/quality gates.","created_at":"2026-10-29T21:38:52.833955Z","dependencies":[{"issue_id":"batten-f27c8039","depends_on_id":"batten-389b9109","type":"blocks","created_at":"2026-10-29T21:38:52Z"}],"description":"Product scope is governed by docs/helix/01-frame/prd.md (FR-25 through FR-28) and docs/helix/01-frame/feature-registry.md. All specified behavior remains in scope. This is a scope record, not an authorized implementation or migration sequence. Wait for owner review before elaborating or coding.","execution_authorized":false,"id":"batten-f27c8039","issue_type":"epic","labels":["area:api","area:infra","review-required"],"priority":0,"schema_version":1,"status":"open","title":"FEAT-006: Platform resources and diagnostics","updated_at":"2026-10-29T21:38:52.833955Z"} -{"acceptance":"After owner review, refine FEAT-008 into behavior-level acceptance tied to FR-32 and FR-33; preserve the native public platform and cleanroom boundaries; implementation completion requires exercising evidence for every requirement and the actual boundary/quality gates.","created_at":"2026-10-29T21:38:53.686585Z","dependencies":[{"issue_id":"batten-ff2246f4","depends_on_id":"batten-389b9109","type":"blocks","created_at":"2026-10-29T21:38:53Z"}],"description":"Product scope is governed by docs/helix/01-frame/prd.md (FR-32 and FR-33) and docs/helix/01-frame/feature-registry.md. All specified behavior remains in scope. This is a scope record, not an authorized implementation or migration sequence. Wait for owner review before elaborating or coding.","execution_authorized":false,"id":"batten-ff2246f4","issue_type":"epic","labels":["area:api","area:infra","review-required"],"priority":0,"schema_version":1,"status":"open","title":"FEAT-008: Host embedding and compatibility","updated_at":"2026-10-29T21:38:53.686585Z"} diff --git a/pyproject.toml b/pyproject.toml index 15f0fcf..182561a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ requires-python = ">=3.13,<3.14" dependencies = [] [dependency-groups] -dev = ["ruff==0.17.3", "pyright==1.1.414", "pytest==9.2.0", "pytest-asyncio==1.4.1.post1", "hatchling==1.33.0", "build==1.6.1", "pydantic==2.14.2", "umf-core==0.10.8", "umf-codegen==0.10.8", "umf-access==0.1.0.dev8", "psycopg[binary]==3.3.7", "pgserver-pg18==18.6.1", "opentelemetry-sdk==1.45.2", "umf-weft==0.4.57", "opentelemetry-instrumentation-psycopg==0.66b2"] +dev = ["ruff==0.17.3", "pyright==1.1.414", "pytest==9.2.0", "pytest-asyncio==1.4.1.post1", "hatchling==1.33.0", "build==1.6.1", "pydantic==2.14.2", "umf-core==0.10.8", "httpx2==2.16.0", "umf-codegen==0.10.8", "umf-access==0.1.0.dev8", "psycopg[binary]==3.3.7", "pgserver-pg18==18.6.1", "opentelemetry-sdk==1.45.2", "umf-weft==0.4.57", "opentelemetry-instrumentation-psycopg==0.66b2"] [tool.uv] package = false diff --git a/tests/asgi/test_registry.py b/tests/asgi/test_registry.py new file mode 100644 index 0000000..3c94e58 --- /dev/null +++ b/tests/asgi/test_registry.py @@ -0,0 +1,111 @@ +"""App registry: listing, routing and the loopback/origin guard.""" + +from __future__ import annotations + +import pytest +from batten.asgi import AppListing, create_registry +from starlette.applications import Starlette +from starlette.requests import Request +from starlette.responses import PlainTextResponse +from starlette.routing import Route +from starlette.testclient import TestClient + +ORIGIN = "http://127.0.0.1:8820" +LOOPBACK = ("127.0.0.1", 50000) + + +def listing(slug: str, title: str = "Title") -> AppListing: + return AppListing(slug, title, "A fabricated app.", "thumb.svg") + + +def child(text: str) -> Starlette: + async def home(request: Request) -> PlainTextResponse: + return PlainTextResponse(text) + + async def post(request: Request) -> PlainTextResponse: + return PlainTextResponse("posted") + + return Starlette(routes=[Route("/", home), Route("/post", post, methods=["POST"])]) + + +def registry() -> Starlette: + return create_registry( + ( + (listing("alpha", "Alpha "), child("alpha home")), + (listing("beta", "Beta"), child("beta home")), + ), + origin=ORIGIN, + ) + + +def client(app: Starlette, *, host: str = "127.0.0.1:8820") -> TestClient: + return TestClient(app, base_url="http://" + host, client=LOOPBACK) + + +def test_index_lists_every_app_and_escapes_titles() -> None: + with client(registry()) as http: + page = http.get("/") + assert page.status_code == 200 + assert "2 registered" in page.text + assert 'href="/apps/alpha/"' in page.text and 'href="/apps/beta/"' in page.text + assert "Alpha <desk>" in page.text and "" not in page.text + + +def test_each_app_is_mounted_under_its_slug_and_the_stylesheet_is_served() -> None: + with client(registry()) as http: + assert http.get("/apps/alpha/").text == "alpha home" + assert http.get("/apps/beta/").text == "beta home" + assert http.get("/apps/gamma/").status_code == 404 + assert http.get("/_batten/registry.css").status_code == 200 + + +def test_responses_carry_security_headers() -> None: + with client(registry()) as http: + headers = http.get("/").headers + assert "default-src 'self'" in headers["content-security-policy"] + assert headers["cache-control"] == "no-store" + assert headers["x-content-type-options"] == "nosniff" + + +def test_cross_origin_and_missing_origin_posts_are_refused() -> None: + with client(registry()) as http: + assert http.post("/apps/alpha/post").status_code == 403 + bad = http.post("/apps/alpha/post", headers={"origin": "http://evil.example"}) + assert bad.status_code == 403 + good = http.post("/apps/alpha/post", headers={"origin": ORIGIN}) + assert (good.status_code, good.text) == (200, "posted") + + +def test_wrong_host_header_and_non_loopback_peer_are_refused() -> None: + with client(registry(), host="localhost:8820") as http: + assert http.get("/").status_code == 403 + remote = TestClient(registry(), base_url=ORIGIN, client=("10.0.0.5", 1)) + with remote as http: + assert http.get("/").status_code == 403 + + +def test_duplicate_slugs_and_non_loopback_origin_are_rejected() -> None: + with pytest.raises(ValueError, match="duplicate"): + create_registry( + ((listing("a"), child("x")), (listing("a"), child("y"))), origin=ORIGIN + ) + with pytest.raises(ValueError, match="loopback"): + create_registry((), origin="http://example.com") + + +@pytest.mark.parametrize( + ("slug", "title", "description", "thumbnail"), + [ + ("Bad Slug", "t", "d", "a.svg"), + ("ok", "", "d", "a.svg"), + ("ok", "t" * 81, "d", "a.svg"), + ("ok", "t", "d" * 301, "a.svg"), + ("ok", "t", "d", "../escape.svg"), + ("ok", "t", "d", "thumb.exe"), + ], +) +def test_invalid_listings_are_rejected( + slug: str, title: str, description: str, thumbnail: str +) -> None: + with pytest.raises(ValueError): + AppListing(slug, title, description, thumbnail) diff --git a/tests/asgi/test_routes.py b/tests/asgi/test_routes.py new file mode 100644 index 0000000..22c11bc --- /dev/null +++ b/tests/asgi/test_routes.py @@ -0,0 +1,178 @@ +"""Operation endpoints and local sessions over a real Host with fake services.""" + +from __future__ import annotations + +from collections.abc import AsyncGenerator +from contextlib import asynccontextmanager +from pathlib import Path + +import pytest +from batten.asgi import create_app +from batten.contracts import ( + Actor, + ArtifactRef, + HostConfig, + HostServices, + Operation, + OperationCall, + OperationOutcome, +) +from batten.runtime import create_host +from starlette.testclient import TestClient + +ORIGIN = "http://127.0.0.1:8820" +ARTIFACT = ArtifactRef("app", "digest") +JSON = {"origin": ORIGIN} +SECOND_KEY = "fedcba9876543210fedcba9876543210" + + +class Sessions: + def __init__(self) -> None: + self.cookies: dict[str, str] = {} + + def resolve(self, cookie: str | None) -> Actor | None: + subject = self.cookies.get(cookie or "") + return Actor(subject, cookie) if subject else None + + def login(self, subject: str) -> str | None: + if subject != "alex": + return None + self.cookies["cookie-1"] = subject + return "cookie-1" + + def logout(self, cookie: str | None) -> None: + self.cookies.pop(cookie or "", None) + + def profile(self, actor: Actor) -> dict[str, object]: + return {"id": actor.subject, "name": "Alex"} + + +class Allow: + async def check(self, actor: Actor, operation: str) -> bool: + return True + + +class Quiet: + @asynccontextmanager + async def scope( + self, actor: Actor, operation: str, invocation: str + ) -> AsyncGenerator[None, None]: + yield + + async def capture( + self, actor: Actor, operation: str, invocation: str, status: str, mutation: bool + ) -> None: + return None + + +class Echo: + async def prepare(self) -> None: + return None + + async def invoke(self, call: OperationCall) -> OperationOutcome: + return OperationOutcome( + "succeeded", "x", {"operation": call.operation, "inputs": dict(call.inputs)} + ) + + async def aclose(self) -> None: + return None + + +@pytest.fixture +def http(tmp_path: Path) -> TestClient: + (tmp_path / "index.html").write_text("

      app

      ") + host = create_host( + HostConfig(ARTIFACT, (Operation("echo", False),), 2, 1.0), + HostServices(Allow(), Quiet(), Echo(), "owned"), + ) + app = create_app(host, Sessions(), tmp_path, origin=ORIGIN, max_body_bytes=64) + return TestClient(app, base_url=ORIGIN, client=("127.0.0.1", 1)) + + +def login(http: TestClient) -> None: + assert ( + http.post( + "/api/local-session", json={"actor": "alex"}, headers=JSON + ).status_code + == 200 + ) + + +def test_create_app_requires_a_loopback_origin_and_a_body_bound(tmp_path: Path) -> None: + host = create_host( + HostConfig(ARTIFACT, (), 1, 1.0), HostServices(Allow(), Quiet(), Echo()) + ) + with pytest.raises(ValueError): + create_app( + host, Sessions(), tmp_path, origin="http://example.com", max_body_bytes=1 + ) + with pytest.raises(ValueError): + create_app(host, Sessions(), tmp_path, origin=ORIGIN, max_body_bytes=0) + + +def test_login_session_and_logout(http: TestClient) -> None: + with http: + assert http.get("/").text == "

      app

      " + assert http.get("/api/session").json() == {"actor": None} + denied = http.post( + "/api/local-session", json={"actor": "mallory"}, headers=JSON + ) + assert denied.status_code == 403 + login(http) + assert http.get("/api/session").json()["actor"] == { + "id": "alex", + "name": "Alex", + } + assert http.post("/api/logout", headers=JSON).status_code == 200 + assert http.get("/api/session").json() == {"actor": None} + + +def test_operations_require_a_session(http: TestClient) -> None: + with http: + outcome = http.post("/api/operations/echo", json={"inputs": {}}, headers=JSON) + assert (outcome.status_code, outcome.json()["code"]) == (403, "denied") + + +def test_operation_runs_through_the_host(http: TestClient) -> None: + with http: + login(http) + body = {"inputs": {"n": 1}, "key": SECOND_KEY} + outcome = http.post("/api/operations/echo", json=body, headers=JSON) + assert outcome.status_code == 200 + assert outcome.json()["status"] == "succeeded" + assert outcome.json()["invocation"] == SECOND_KEY + assert outcome.json()["result"] == {"operation": "echo", "inputs": {"n": 1}} + unknown = http.post("/api/operations/other", json={"inputs": {}}, headers=JSON) + assert (unknown.status_code, unknown.json()["code"]) == (403, "not_admitted") + + +@pytest.mark.parametrize( + "payload", + [ + {"inputs": "text"}, + {"nothing": 1}, + {"inputs": {}, "extra": 1}, + {"inputs": {}, "key": 5}, + {"inputs": {}, "phase": "other"}, + ], +) +def test_malformed_operation_requests_are_invalid( + http: TestClient, payload: dict[str, object] +) -> None: + with http: + login(http) + outcome = http.post("/api/operations/echo", json=payload, headers=JSON) + assert outcome.status_code == 400 + + +def test_oversized_and_non_json_bodies_are_rejected(http: TestClient) -> None: + with http: + login(http) + big = {"inputs": {"text": "x" * 200}} + assert ( + http.post("/api/operations/echo", json=big, headers=JSON).status_code == 400 + ) + text = http.post("/api/operations/echo", content="{}", headers=JSON) + assert text.status_code == 400 + array = http.post("/api/operations/echo", json=[1], headers=JSON) + assert array.status_code == 400 diff --git a/tests/contracts/test_values.py b/tests/contracts/test_values.py new file mode 100644 index 0000000..bc1e1f6 --- /dev/null +++ b/tests/contracts/test_values.py @@ -0,0 +1,43 @@ +"""Value types shared by every host and provider.""" + +from __future__ import annotations + +from dataclasses import FrozenInstanceError + +import pytest +from batten.contracts import ( + Actor, + ArtifactRef, + HostConfig, + Operation, + OperationCall, + OperationOutcome, +) + + +def test_values_are_immutable_and_compare_by_content() -> None: + artifact = ArtifactRef("app", "d1") + assert artifact == ArtifactRef("app", "d1") + assert artifact != ArtifactRef("app", "d2") + assert len({artifact, ArtifactRef("app", "d1")}) == 1 + with pytest.raises(FrozenInstanceError): + setattr(artifact, "digest", "d2") + + +def test_actor_session_is_not_printed() -> None: + actor = Actor("alex", "secret-cookie") + assert "secret-cookie" not in repr(actor) + assert Actor("alex").session is None + + +def test_call_defaults_to_an_unkeyed_invoke() -> None: + call = OperationCall("submit", {"summary": "x"}, Actor("alex")) + assert (call.key, call.phase) == (None, "invoke") + + +def test_outcome_code_is_optional_and_config_keeps_operation_order() -> None: + assert OperationOutcome("succeeded", "k", {}).code is None + operations = (Operation("read", False), Operation("write", True)) + config = HostConfig(ArtifactRef("a", "d"), operations, 2, 1.5) + assert [op.id for op in config.operations] == ["read", "write"] + assert [op.mutation for op in config.operations] == [False, True] diff --git a/tests/local/test_local_runtime.py b/tests/local/test_local_runtime.py new file mode 100644 index 0000000..c6e7793 --- /dev/null +++ b/tests/local/test_local_runtime.py @@ -0,0 +1,57 @@ +"""LocalRuntime against a real pgserver cluster (nightly).""" + +from __future__ import annotations + +import socket +from pathlib import Path + +import pytest +from approval_desk.cli import application +from batten.contracts import OperationCall +from batten.hosting.local import LocalRuntime, LocalSettings + +pytestmark = pytest.mark.integration + +ROOT = Path(__file__).resolve().parents[2] +MODEL = ROOT / "examples/approval-desk/model/approval.umf.json" + + +def free_port() -> int: + with socket.socket() as probe: + probe.bind(("127.0.0.1", 0)) + return int(probe.getsockname()[1]) + + +def runtime(tmp_path: Path) -> LocalRuntime: + assets = tmp_path / "assets" + assets.mkdir(exist_ok=True) + (assets / "index.html").write_text("

      app

      ") + (assets / "thumbnail.svg").write_text("") + settings = LocalSettings(tmp_path / "data", free_port(), 4, 60.0, 16384, 16, 600.0) + return LocalRuntime(application(MODEL, assets), settings) + + +async def test_initialize_open_call_and_close(tmp_path: Path) -> None: + local = runtime(tmp_path) + await local.initialize() + assert (tmp_path / "data/deployment.json").is_file() + await local.open() + try: + await local.host.start() + assert await local.host.admit(local.application.artifact) + cookie = local.identities.login("alex") + actor = local.identities.resolve(cookie) + assert actor is not None + outcome = await local.host.invoke(OperationCall("list", {}, actor)) + assert outcome.status == "succeeded" + finally: + await local.aclose() + assert await local.host.readiness() == "closed" + + +async def test_reinitializing_an_existing_data_directory_is_refused( + tmp_path: Path, +) -> None: + (tmp_path / "data").mkdir() + with pytest.raises(ValueError, match="already exists"): + await runtime(tmp_path).initialize() diff --git a/tests/local/test_local_units.py b/tests/local/test_local_units.py new file mode 100644 index 0000000..20e495e --- /dev/null +++ b/tests/local/test_local_units.py @@ -0,0 +1,115 @@ +"""Local settings, stub identities and audit capture; no database needed.""" + +from __future__ import annotations + +import json +import time +from pathlib import Path +from typing import Any + +import pytest +from batten.contracts import Actor +from batten.hosting.local import LocalSettings +from batten.hosting.local._identity import LocalIdentities +from batten.hosting.local._observations import LocalObservations + +PEOPLE = { + "alex": {"profile": {"name": "Alex"}, "operations": ["list", "submit"]}, + "blake": {"profile": {"name": "Blake"}, "operations": ["list", "decide"]}, +} + + +def settings(tmp_path: Path, **overrides: Any) -> LocalSettings: + values: dict[str, Any] = { + "data": tmp_path, + "port": 8820, + "max_concurrency": 4, + "timeout_seconds": 30.0, + "max_body_bytes": 1024, + "max_sessions": 8, + "session_ttl_seconds": 60.0, + } + values.update(overrides) + return LocalSettings(**values) + + +def test_valid_settings_are_accepted(tmp_path: Path) -> None: + assert settings(tmp_path).port == 8820 + + +@pytest.mark.parametrize( + "bad", + [ + {"port": 80}, + {"port": 70000}, + {"port": "8820"}, + {"max_concurrency": 0}, + {"max_body_bytes": -1}, + {"max_sessions": 0}, + {"timeout_seconds": 0.0}, + {"timeout_seconds": float("inf")}, + {"session_ttl_seconds": float("nan")}, + {"data": Path("relative/data")}, + ], +) +def test_invalid_settings_are_rejected(tmp_path: Path, bad: dict[str, Any]) -> None: + with pytest.raises(ValueError): + settings(tmp_path, **bad) + + +def test_login_resolves_to_the_actor_and_logout_ends_the_session() -> None: + people = LocalIdentities(PEOPLE, max_sessions=4, ttl_seconds=60) + cookie = people.login("alex") + assert cookie is not None + actor = people.resolve(cookie) + assert actor is not None and actor == Actor("alex", cookie) + assert people.profile(actor) == {"name": "Alex", "id": "alex"} + people.logout(cookie) + assert people.resolve(cookie) is None + assert people.resolve(None) is None + + +def test_unknown_and_revoked_subjects_cannot_log_in() -> None: + people = LocalIdentities(PEOPLE, max_sessions=4, ttl_seconds=60) + assert people.login("mallory") is None + cookie = people.login("blake") + people.revoke("blake") + assert people.resolve(cookie) is None + assert people.login("blake") is None + + +def test_session_cap_and_expiry() -> None: + people = LocalIdentities(PEOPLE, max_sessions=1, ttl_seconds=0.05) + assert people.login("alex") is not None + assert people.login("blake") is None + time.sleep(0.1) + assert people.login("blake") is not None + + +async def test_operation_checks_follow_the_session_and_the_grant() -> None: + people = LocalIdentities(PEOPLE, max_sessions=4, ttl_seconds=60) + cookie = people.login("alex") + actor = Actor("alex", cookie) + assert await people.check(actor, "submit") + assert not await people.check(actor, "decide") + assert not await people.check(Actor("blake", cookie), "list") + assert not await people.check(Actor("alex", "forged"), "list") + + +async def test_capture_appends_a_redacted_audit_frame(tmp_path: Path) -> None: + observations = LocalObservations(tmp_path, "app-1", timeout_ms=1000) + actor = Actor("alex", "secret-cookie") + await observations.capture(actor, "submit", "inv-1", "succeeded", True) + await observations.aclose() + (line,) = (tmp_path / "audit.jsonl").read_text().splitlines() + frame = json.loads(line) + assert frame == { + "type": "audit", + "application": "app-1", + "actor": "alex", + "operation": "submit", + "invocation": "inv-1", + "status": "succeeded", + "mutation": True, + } + assert "secret-cookie" not in line diff --git a/tests/runtime/test_host.py b/tests/runtime/test_host.py new file mode 100644 index 0000000..c15b9dc --- /dev/null +++ b/tests/runtime/test_host.py @@ -0,0 +1,261 @@ +"""Host lifecycle, admission, outcomes and bounded concurrency, with fake services.""" + +from __future__ import annotations + +import asyncio +from collections.abc import AsyncGenerator +from contextlib import asynccontextmanager + +import pytest +from batten.contracts import ( + Actor, + ArtifactRef, + HostConfig, + HostServices, + Operation, + OperationCall, + OperationOutcome, +) +from batten.runtime import Host, create_host + +ARTIFACT = ArtifactRef("app-1", "digest-1") +ALEX = Actor("alex", "session-1") +KEY = "0123456789abcdef0123456789abcdef" +OPERATIONS = (Operation("read", False), Operation("write", True)) + + +class Identity: + def __init__(self) -> None: + self.allowed = True + self.after_run = True + self.calls = 0 + + async def check(self, actor: Actor, operation: str) -> bool: + self.calls += 1 + # The first check admits the call; a later one models revocation mid-flight. + return self.allowed if self.calls == 1 else self.after_run + + +class Observations: + def __init__(self) -> None: + self.events: list[tuple[str, str]] = [] + self.fail = False + + @asynccontextmanager + async def scope( + self, actor: Actor, operation: str, invocation: str + ) -> AsyncGenerator[None, None]: + yield + + async def capture( + self, actor: Actor, operation: str, invocation: str, status: str, mutation: bool + ) -> None: + if self.fail: + raise OSError("sink down") + self.events.append((operation, status)) + + +class Execution: + def __init__(self) -> None: + self.prepared = 0 + self.closed = 0 + self.fail_prepare = False + self.error: Exception | None = None + self.delay = 0.0 + self.running = 0 + self.peak = 0 + + async def prepare(self) -> None: + self.prepared += 1 + if self.fail_prepare: + raise RuntimeError("cannot prepare") + + async def invoke(self, call: OperationCall) -> OperationOutcome: + self.running += 1 + self.peak = max(self.peak, self.running) + try: + await asyncio.sleep(self.delay) + if self.error is not None: + raise self.error + return OperationOutcome("succeeded", "ignored", {"echo": call.operation}) + finally: + self.running -= 1 + + async def aclose(self) -> None: + self.closed += 1 + + +class Fixture: + def __init__( + self, + *, + max_concurrency: int = 2, + timeout: float = 1.0, + ownership: str = "owned", + ) -> None: + self.identity, self.observations = Identity(), Observations() + self.execution = Execution() + self.host = Host( + HostConfig(ARTIFACT, OPERATIONS, max_concurrency, timeout), + HostServices(self.identity, self.observations, self.execution, ownership), + ) + + async def running(self) -> Host: + await self.host.start() + assert await self.host.admit(ARTIFACT) + return self.host + + +def call(operation: str, key: str | None = None) -> OperationCall: + return OperationCall(operation, {}, ALEX, key) + + +@pytest.mark.parametrize(("concurrency", "timeout"), [(0, 1.0), (1, 0.0), (1, -1.0)]) +def test_non_positive_limits_are_rejected(concurrency: int, timeout: float) -> None: + with pytest.raises(ValueError, match="limits"): + Fixture(max_concurrency=concurrency, timeout=timeout) + + +def test_duplicate_operations_and_unknown_ownership_are_rejected() -> None: + services = HostServices(Identity(), Observations(), Execution()) + with pytest.raises(ValueError): + create_host( + HostConfig(ARTIFACT, (*OPERATIONS, OPERATIONS[0]), 1, 1.0), services + ) + with pytest.raises(ValueError): + Fixture(ownership="shared") + + +async def test_invoke_before_admission_is_refused() -> None: + fixture = Fixture() + await fixture.host.start() + outcome = await fixture.host.invoke(call("read")) + assert (outcome.status, outcome.code) == ("denied", "not_admitted") + assert not await fixture.host.admit(ArtifactRef("app-1", "other")) + assert await fixture.host.readiness() == "running" + + +async def test_successful_call_keeps_the_caller_key_and_records_both_phases() -> None: + host = await Fixture().running() + outcome = await host.invoke(call("read", KEY)) + assert (outcome.status, outcome.invocation) == ("succeeded", KEY) + assert dict(outcome.result) == {"echo": "read"} + observations = host.services.observations + assert isinstance(observations, Observations) + assert observations.events == [("read", "started"), ("read", "succeeded")] + + +async def test_unknown_operation_malformed_key_and_denied_actor_are_refused() -> None: + fixture = Fixture() + host = await fixture.running() + unknown = await host.invoke(call("delete")) + assert (unknown.status, unknown.code) == ("denied", "not_admitted") + malformed = await host.invoke(call("read", "NOT A KEY")) + assert (malformed.status, malformed.code) == ("invalid", "invalid_key") + fixture.identity.allowed = False + denied = await host.invoke(call("read")) + assert (denied.status, denied.code) == ("denied", "denied") + assert fixture.execution.peak == 0 + + +@pytest.mark.parametrize( + ("operation", "status"), [("read", "denied"), ("write", "uncertain")] +) +async def test_authority_revoked_during_a_call(operation: str, status: str) -> None: + fixture = Fixture() + fixture.identity.after_run = False + outcome = await (await fixture.running()).invoke(call(operation)) + assert (outcome.status, outcome.code) == (status, "authority_revoked") + + +@pytest.mark.parametrize( + ("operation", "status"), [("read", "unavailable"), ("write", "uncertain")] +) +async def test_provider_failure_never_claims_a_mutation_failed( + operation: str, status: str +) -> None: + fixture = Fixture() + fixture.execution.error = RuntimeError("database gone") + outcome = await (await fixture.running()).invoke(call(operation)) + assert (outcome.status, outcome.code) == (status, "provider_unavailable") + + +@pytest.mark.parametrize( + ("operation", "status"), [("read", "unavailable"), ("write", "uncertain")] +) +async def test_timeout(operation: str, status: str) -> None: + fixture = Fixture(timeout=0.05) + fixture.execution.delay = 1.0 + outcome = await (await fixture.running()).invoke(call(operation)) + assert (outcome.status, outcome.code) == (status, "timeout") + + +async def test_unavailable_observation_sink_stops_the_call() -> None: + fixture = Fixture() + host = await fixture.running() + fixture.observations.fail = True + outcome = await host.invoke(call("write")) + assert (outcome.status, outcome.code) == ("unavailable", "capture_unavailable") + assert fixture.execution.peak == 0 + + +async def test_concurrency_is_bounded_by_the_configured_limit() -> None: + fixture = Fixture(max_concurrency=2) + fixture.execution.delay = 0.05 + fixture.identity.after_run = True + host = await fixture.running() + outcomes = await asyncio.gather(*(host.invoke(call("read")) for _ in range(5))) + statuses = sorted(o.status for o in outcomes) + assert statuses == [ + "succeeded", + "succeeded", + "unavailable", + "unavailable", + "unavailable", + ] + assert {o.code for o in outcomes if o.status == "unavailable"} == {"limit_exceeded"} + assert fixture.execution.peak == 2 + + +async def test_close_reports_state_refuses_later_calls_and_honours_ownership() -> None: + owned, borrowed = Fixture(ownership="owned"), Fixture(ownership="borrowed") + for fixture in (owned, borrowed): + host = await fixture.running() + report = await host.aclose() + assert (report.state, report.retained_resources) == ("closed", ("app-1",)) + refused = await host.invoke(call("read")) + assert (refused.status, refused.code) == ("denied", "not_admitted") + assert (await host.aclose()).state == "closed" + assert (owned.execution.closed, borrowed.execution.closed) == (1, 0) + + +async def test_async_with_starts_and_closes_and_cannot_restart() -> None: + fixture = Fixture() + async with fixture.host as host: + assert await host.readiness() == "running" + await host.start() + assert fixture.execution.prepared == 1 + assert await fixture.host.readiness() == "closed" + with pytest.raises(RuntimeError, match="restart"): + await fixture.host.start() + + +async def test_failed_prepare_closes_the_host_and_propagates() -> None: + fixture = Fixture() + fixture.execution.fail_prepare = True + with pytest.raises(RuntimeError, match="cannot prepare"): + await fixture.host.start() + assert await fixture.host.readiness() == "closed" + assert fixture.execution.closed == 1 + + +async def test_close_cancels_in_flight_calls_and_marks_a_mutation_uncertain() -> None: + fixture = Fixture(timeout=5.0) + fixture.execution.delay = 5.0 + host = await fixture.running() + task = asyncio.create_task(host.invoke(call("write"))) + await asyncio.sleep(0.05) + assert (await host.aclose()).state == "closed" + with pytest.raises(asyncio.CancelledError): + await task + assert fixture.observations.events[-1] == ("write", "uncertain") diff --git a/tests/umf_postgres/test_compile.py b/tests/umf_postgres/test_compile.py new file mode 100644 index 0000000..063f78d --- /dev/null +++ b/tests/umf_postgres/test_compile.py @@ -0,0 +1,43 @@ +"""The approval model compiles with the released umf-codegen, without a database.""" + +from __future__ import annotations + +from pathlib import Path + +import pytest +from approval_desk.cli import application +from batten.umf_postgres.local._deployment import compile_model, raw_binding + +MODEL = ( + Path(__file__).resolve().parents[2] + / "examples/approval-desk/model/approval.umf.json" +) + + +def configuration(tmp_path: Path) -> dict[str, object]: + return dict(application(MODEL, tmp_path).database) + + +def test_approval_model_compiles_to_a_bundle_and_an_initial_plan( + tmp_path: Path, +) -> None: + bundle, plan = compile_model(MODEL, configuration(tmp_path)) + assert bundle["configuration"]["schema"] == "approval_app" + assert bundle["sourceDigest"] and bundle["bundleDigest"] + assert plan["digest"] + + +def test_raw_binding_describes_the_single_request_table(tmp_path: Path) -> None: + bundle, _plan = compile_model(MODEL, configuration(tmp_path)) + binding = raw_binding(bundle) + assert binding["schema"] == "approval_app" + assert binding["modelSha256"] == bundle["sourceDigest"] + (table,) = binding["tables"] + assert table["key"] and table["columns"] + + +def test_an_invalid_model_is_refused(tmp_path: Path) -> None: + broken = tmp_path / "broken.umf.json" + broken.write_text('{"modules": []}') + with pytest.raises(ValueError, match="refused"): + compile_model(broken, configuration(tmp_path)) diff --git a/tests/umf_postgres/test_provider.py b/tests/umf_postgres/test_provider.py new file mode 100644 index 0000000..78fa4d6 --- /dev/null +++ b/tests/umf_postgres/test_provider.py @@ -0,0 +1,102 @@ +"""UmfTableProvider adapts the table port to the UMF access contract.""" + +from __future__ import annotations + +from collections.abc import Mapping + +import pytest +from batten.contracts import Actor +from batten.tables import TablePort +from batten.umf_postgres import AuthenticatedTransport, create_umf_provider +from umf_access.unified import SessionIdentity + + +class Transport: + def __init__(self, sent: list[dict[str, object]]) -> None: + self.sent = sent + + async def execute(self, request: dict[str, object]) -> dict[str, object]: + self.sent.append(request) + return {"ok": True} + + +class Binding: + schema = "approval_app" + module = "approval" + + def __init__(self) -> None: + self.identities: list[SessionIdentity] = [] + self.sent: list[dict[str, object]] = [] + + def for_identity(self, identity: SessionIdentity) -> AuthenticatedTransport: + self.identities.append(identity) + return Transport(self.sent) + + +class Authority: + def __init__(self, allowed: bool) -> None: + self.allowed = allowed + self.checked: list[tuple[str, str]] = [] + + async def check(self, actor: Actor, operation: str) -> bool: + self.checked.append((actor.subject, operation)) + return self.allowed + + +async def run(port: TablePort, **overrides: object) -> Mapping[str, object]: + options: dict[str, object] = {"key": "k1", "phase": "invoke", "mutation": True} + options.update(overrides) + return await port.execute( + Actor("alex"), + "submit_request", + {"summary": "x"}, + key=str(options["key"]), + phase=str(options["phase"]), + mutation=bool(options["mutation"]), + ) + + +async def test_prepare_builds_the_binding_once_and_close_drops_it() -> None: + built: list[Binding] = [] + + def factory() -> Binding: + built.append(Binding()) + return built[-1] + + provider = create_umf_provider(factory, Authority(True)) + await provider.prepare() + await provider.prepare() + assert len(built) == 1 + await provider.aclose() + with pytest.raises(RuntimeError, match="not prepared"): + await run(provider) + + +async def test_execute_sends_the_original_access_request_as_the_person() -> None: + binding, authority = Binding(), Authority(True) + provider = create_umf_provider(lambda: binding, authority) + await provider.prepare() + assert await run(provider) == {"ok": True} + assert authority.checked == [("alex", "tables.submit_request")] + assert binding.identities == [SessionIdentity("person", "alex")] + assert binding.sent == [ + { + "contract": "umf.access/1", + "schema": "approval_app", + "kind": "table", + "module": "approval", + "operation": "submit_request", + "call": {"kind": "single", "inputs": {"summary": "x"}}, + "phase": "invoke", + "mutation": True, + "idempotency_key": "k1", + } + ] + + +async def test_denied_actor_never_reaches_the_native_binding() -> None: + binding = Binding() + provider = create_umf_provider(lambda: binding, Authority(False)) + await provider.prepare() + assert await run(provider) == {"error": {"code": "DENIED"}} + assert binding.identities == [] and binding.sent == [] diff --git a/uv.lock b/uv.lock index e71a849..a7ff654 100644 --- a/uv.lock +++ b/uv.lock @@ -43,6 +43,7 @@ source = { virtual = "." } dev = [ { name = "build" }, { name = "hatchling" }, + { name = "httpx2" }, { name = "opentelemetry-instrumentation-psycopg" }, { name = "opentelemetry-sdk" }, { name = "pgserver-pg18" }, @@ -64,6 +65,7 @@ dev = [ dev = [ { name = "build", specifier = "==1.6.1" }, { name = "hatchling", specifier = "==1.33.0" }, + { name = "httpx2", specifier = "==2.16.0" }, { name = "opentelemetry-instrumentation-psycopg", specifier = "==0.66b2" }, { name = "opentelemetry-sdk", specifier = "==1.45.2" }, { name = "pgserver-pg18", specifier = "==18.6.1" }, @@ -145,6 +147,44 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/32/64/4afe5dd77b2939a93e8c9513f8082dbd049ecba9c1484a379a0f6ae29d6b/hatchling-1.33.0-py3-none-any.whl", hash = "sha256:415290b84f464d2884303fca8974d38e7b85579069fab02a15db0828fbb1446d", size = 78750, upload-time = "2026-10-28T02:27:29.033Z" }, ] +[[package]] +name = "httpcore2" +version = "2.16.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "h11" }, + { name = "truststore" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/c0/61/afa9d6b7452f9eca73f73d45324eb0bb52f098fd5e6049bf6b8263be9b4e/httpcore2-2.16.0.tar.gz", hash = "sha256:c72cd0413563b17e1cd8354677dff887466f8ec2551679759e93126534428643", size = 69886, upload-time = "2026-10-21T07:09:45.31Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/af/c2/ce417c397afa5181f0e3c6ff01a4d01639414e1adef08730d97571297151/httpcore2-2.16.0-py3-none-any.whl", hash = "sha256:5c4358319f2602d984ad93182c9fee5160f22e9da7babdda870a5e7c4e2dc34f", size = 85070, upload-time = "2026-10-21T07:09:42.802Z" }, +] + +[[package]] +name = "httpx2" +version = "2.16.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "anyio", marker = "sys_platform != 'emscripten'" }, + { name = "httpcore2", marker = "sys_platform != 'emscripten'" }, + { name = "httpx2-jsfetch", marker = "sys_platform == 'emscripten'" }, + { name = "idna" }, + { name = "truststore", marker = "sys_platform != 'emscripten'" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/43/73/5ca2cedf5e4e50423d1c258877865a6b62793633b561c58499f8aeb33b7e/httpx2-2.16.0.tar.gz", hash = "sha256:0d54c98128e8f2ff7fbbde0fca8c359e5f032edeaaaac443cdb7f31f685bcd7f", size = 103116, upload-time = "2026-10-21T07:09:46.348Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/7b/3d/2e4bc4fd1ef9770871669adb348d612a6e4786b303a23f9935b81c48dd60/httpx2-2.16.0-py3-none-any.whl", hash = "sha256:fd2c5d7909e8d86fe92d53020c310ca0e4e431b838c207c5754b9bbf0308d49a", size = 97880, upload-time = "2026-10-21T07:09:44.01Z" }, +] + +[[package]] +name = "httpx2-jsfetch" +version = "1.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/cd/c4/0e5636363151a2a1795e0a77617168b9ca438e1748ec05fc9b5687f93d64/httpx2_jsfetch-1.0.tar.gz", hash = "sha256:70a0e3eabfef7cce5ad9c629f7d01ca05e418f586646f4ddf14782e4c1454c60", size = 6872, upload-time = "2026-08-07T00:13:07.492Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/9b/43/832f631d32e4f1211caa2ba368317739fe71f0b8530e4c9d15dc454bac2a/httpx2_jsfetch-1.0-py3-none-any.whl", hash = "sha256:cb916b707601e69a07721aabc8f3f6659be3a6893bc1ff5c6f9e02241df2da32", size = 6382, upload-time = "2026-08-07T00:13:06.567Z" }, +] + [[package]] name = "idna" version = "3.20" @@ -567,6 +607,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/30/81/0da8afb52a71d0a4f2bd3152357b1a441e393b286374802b9d3addab4ab5/trove_classifiers-2026.9.21.13-py3-none-any.whl", hash = "sha256:8b1ff4f9c191b1040b71c37f1e445ab99732911e3cd91de52838453a854d7a17", size = 14232, upload-time = "2026-09-21T13:29:06.123Z" }, ] +[[package]] +name = "truststore" +version = "0.10.5" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/ee/9f/c5201d42a484c061e528825fc8e2d565f5abd50a4ced6fb7d29c4ec99b2b/truststore-0.10.5.tar.gz", hash = "sha256:30d36967ccaded5cbb38d602c433f53600036c79d502f4533a49b60a03bbefcd", size = 28091, upload-time = "2026-10-12T22:27:31.808Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/51/e9/3a7820be2bb0fe53b6bc9c3be26d3d1158004e4c3ab953aa6840b955b1e9/truststore-0.10.5-py3-none-any.whl", hash = "sha256:9aaaedaefaf06d8b206278cf8b5012bc897f485a874503501e12d776df78951c", size = 19017, upload-time = "2026-10-12T22:27:30.377Z" }, +] + [[package]] name = "typing-extensions" version = "4.16.0" From 364ec157b61d1fc4e1fc823823aa2897d953e708 Mon Sep 17 00:00:00 2001 From: Erik LaBianca Date: Wed, 11 Nov 2026 17:14:50 -0500 Subject: [PATCH 3/7] CI: replace quality.yml with ci.yml; add tree size guard Linux-only: unit/lint/type/boundary checks on push and PR; native PostgreSQL integration and Playwright scenarios on push to main, nightly and dispatch. Co-Authored-By: Claude Sonnet 5.5 --- .github/workflows/ci.yml | 65 ++++++++++++++++++++++++++++++ .github/workflows/quality.yml | 54 ------------------------- scripts/check_tree_size.py | 39 ++++++++++++++++++ tests/boundaries/test_tree_size.py | 18 +++++++++ 4 files changed, 122 insertions(+), 54 deletions(-) create mode 100644 .github/workflows/ci.yml delete mode 100644 .github/workflows/quality.yml create mode 100644 scripts/check_tree_size.py create mode 100644 tests/boundaries/test_tree_size.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..1793e42 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,65 @@ +name: CI + +on: + push: + branches: [main] + pull_request: + schedule: + - cron: '17 5 * * *' + workflow_dispatch: + workflow_call: + +permissions: + contents: read + +concurrency: + group: ci-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + check: + runs-on: ubuntu-24.04 + timeout-minutes: 15 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: astral-sh/setup-uv@v6 + - uses: oven-sh/setup-bun@v2 + - run: uv sync --frozen --all-packages --python 3.13 + - run: bun install --frozen-lockfile + - name: Boundaries, lint, types and unit tests + run: uv run python scripts/check.py + - name: Tree size guard + run: python3 scripts/check_tree_size.py + + # Native PostgreSQL (pgserver) and browser tests; slower, so not on pull requests. + native: + if: github.event_name != 'pull_request' + runs-on: ubuntu-24.04 + timeout-minutes: 30 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: astral-sh/setup-uv@v6 + - uses: oven-sh/setup-bun@v2 + - run: uv sync --frozen --all-packages --python 3.13 + - run: bun install --frozen-lockfile + - name: Build and install the approval desk + run: uv run python scripts/prepare_approval.py + - name: Integration tests + run: uv run pytest -m integration + - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 + with: + node-version: '26.13.0' + - run: node node_modules/playwright/cli.js install --with-deps chromium + - name: Browser scenarios + run: bun run test:native + - uses: actions/upload-artifact@v4 + if: always() + with: + name: test-results + path: .cache/browser-results.json + retention-days: 14 + if-no-files-found: ignore diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml deleted file mode 100644 index 3b58819..0000000 --- a/.github/workflows/quality.yml +++ /dev/null @@ -1,54 +0,0 @@ -name: SDK quality -# PR tier: install + prepare + quality.py (fast smoke, one runner). -# Native browser approval-app test (heavy) runs on tags, dispatch, weekly, -# or on a PR labelled `ci:full`. -on: - push: - tags: ['v*'] - pull_request: - types: [opened, synchronize, reopened, labeled] - schedule: - - cron: '17 5 * * 1' - workflow_dispatch: -permissions: - contents: read -concurrency: - group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} -env: - FULL: ${{ github.event_name != 'pull_request' || contains(github.event.pull_request.labels.*.name, 'ci:full') }} -jobs: - check: - # a bare `labeled` event for an unrelated label should not run anything - if: github.event.action != 'labeled' || github.event.label.name == 'ci:full' - timeout-minutes: 30 - runs-on: ubuntu-24.04 - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 - with: - fetch-depth: 0 - - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 - with: - python-version: '3.13' - - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 - with: - node-version: '26.13.0' - - name: Install build tooling - run: python -m pip install uv==0.13.7 - - name: Set up Bun - run: npm install --global bun@1.4.4 - - name: Install selected development tools - run: | - uv sync --frozen --all-packages - bun install --frozen-lockfile - - name: Assemble pinned optional SDK and application artifacts - run: uv run python scripts/prepare_approval.py - - name: Run common quality recipe and behaviors - run: | - uv run python scripts/quality.py - - name: Install native browser - if: env.FULL == 'true' - run: node node_modules/playwright/cli.js install --with-deps chromium - - name: Exercise installed native approval app - if: env.FULL == 'true' - run: bun run test:native diff --git a/scripts/check_tree_size.py b/scripts/check_tree_size.py new file mode 100644 index 0000000..f16826e --- /dev/null +++ b/scripts/check_tree_size.py @@ -0,0 +1,39 @@ +"""Keep large generated files (evidence, binaries, receipts) out of git.""" + +from __future__ import annotations + +import subprocess +from pathlib import Path + +MAX_FILE_BYTES = 1_000_000 +MAX_TREE_BYTES = 3_000_000 + + +def problems(sizes: dict[str, int]) -> list[str]: + found = [ + f"{path}: {size} bytes exceeds the {MAX_FILE_BYTES} byte file limit" + for path, size in sorted(sizes.items()) + if size > MAX_FILE_BYTES + ] + total = sum(sizes.values()) + if total > MAX_TREE_BYTES: + found.append(f"tracked tree is {total} bytes; limit is {MAX_TREE_BYTES}") + return found + + +def main() -> None: + root = Path(__file__).resolve().parents[1] + names = subprocess.run( + ["git", "ls-files"], cwd=root, check=True, capture_output=True, text=True + ).stdout.splitlines() + sizes = { + name: (root / name).stat().st_size for name in names if (root / name).is_file() + } + found = problems(sizes) + if found: + raise SystemExit("\n".join(found)) + print(f"{len(sizes)} tracked files, {sum(sizes.values())} bytes: within limits.") + + +if __name__ == "__main__": + main() diff --git a/tests/boundaries/test_tree_size.py b/tests/boundaries/test_tree_size.py new file mode 100644 index 0000000..768c452 --- /dev/null +++ b/tests/boundaries/test_tree_size.py @@ -0,0 +1,18 @@ +"""The size guard flags oversized files and an oversized tree.""" + +from __future__ import annotations + +from check_tree_size import MAX_FILE_BYTES, MAX_TREE_BYTES, problems + + +def test_small_tree_passes() -> None: + assert problems({"a.py": 10, "uv.lock": 100_000}) == [] + + +def test_large_file_and_large_tree_are_reported() -> None: + (message,) = problems({"evidence/run.json": MAX_FILE_BYTES + 1}) + assert "evidence/run.json" in message + many = { + f"f{i}": MAX_FILE_BYTES for i in range(MAX_TREE_BYTES // MAX_FILE_BYTES + 1) + } + assert any("tracked tree" in text for text in problems(many)) From 8072127d6e1cba3a603119c6d72a88937d68482c Mon Sep 17 00:00:00 2001 From: Erik LaBianca Date: Wed, 11 Nov 2026 17:15:24 -0500 Subject: [PATCH 4/7] CI: run the native job on pull requests too Co-Authored-By: Claude Sonnet 5.5 --- .github/workflows/ci.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1793e42..76e4a80 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -33,9 +33,8 @@ jobs: - name: Tree size guard run: python3 scripts/check_tree_size.py - # Native PostgreSQL (pgserver) and browser tests; slower, so not on pull requests. + # Native PostgreSQL (pgserver) and browser tests; runs on every PR so the stack is exercised before merge. native: - if: github.event_name != 'pull_request' runs-on: ubuntu-24.04 timeout-minutes: 30 steps: From e296a23fb8fe6232540e4ed7378adc01563f5310 Mon Sep 17 00:00:00 2001 From: Erik LaBianca Date: Wed, 11 Nov 2026 17:38:20 -0500 Subject: [PATCH 5/7] Collapse 7 packages into 3 plus the example; one version 0.1.0a3; Python 3.11-3.13 novirhyza-batten (contracts, runtime, tables, asgi), novirhyza-batten-storage, novirhyza-batten-local (local host + umf_postgres), plus the approval desk. Import paths are unchanged. Dependency ranges replace exact pins; the old package names were never on PyPI. Co-Authored-By: Claude Sonnet 5.5 --- examples/approval-desk/pyproject.toml | 11 +- packages/batten-asgi/pyproject.toml | 14 -- packages/batten-contracts/LICENSE-APACHE | 202 ------------------ packages/batten-contracts/LICENSE-MIT | 21 -- packages/batten-contracts/NOTICE | 5 - packages/batten-contracts/pyproject.toml | 14 -- packages/batten-local/pyproject.toml | 20 +- .../src/batten/umf_postgres/__init__.py | 0 .../src/batten/umf_postgres/local/__init__.py | 0 .../batten/umf_postgres/local/_deployment.py | 0 .../src/batten/umf_postgres}/py.typed | 0 packages/batten-runtime/LICENSE-APACHE | 202 ------------------ packages/batten-runtime/LICENSE-MIT | 21 -- packages/batten-runtime/NOTICE | 5 - packages/batten-runtime/pyproject.toml | 14 -- packages/batten-storage/pyproject.toml | 2 +- packages/batten-tables/LICENSE-APACHE | 202 ------------------ packages/batten-tables/LICENSE-MIT | 21 -- packages/batten-tables/NOTICE | 5 - packages/batten-tables/pyproject.toml | 14 -- packages/batten-umf-postgres/LICENSE-APACHE | 202 ------------------ packages/batten-umf-postgres/LICENSE-MIT | 21 -- packages/batten-umf-postgres/NOTICE | 5 - packages/batten-umf-postgres/pyproject.toml | 17 -- .../{batten-asgi => batten}/LICENSE-APACHE | 0 packages/{batten-asgi => batten}/LICENSE-MIT | 0 packages/{batten-asgi => batten}/NOTICE | 0 packages/batten/pyproject.toml | 19 ++ .../src/batten/asgi/__init__.py | 0 .../src/batten/asgi/_ports.py | 0 .../src/batten/asgi/_registry.py | 0 .../src/batten/asgi/_routes.py | 0 .../src/batten/asgi/assets/registry.css | 0 .../src/batten/asgi}/py.typed | 0 .../src/batten/contracts/__init__.py | 0 .../src/batten/contracts}/py.typed | 0 .../src/batten/runtime/__init__.py | 0 .../src/batten/runtime}/py.typed | 0 .../src/batten/tables/__init__.py | 0 .../src/batten/tables}/py.typed | 0 pyproject.toml | 17 +- scripts/check_versions.py | 38 ++++ scripts/prepare_approval.py | 9 +- tests/storage/test_distribution.py | 4 +- uv.lock | 160 ++++++++++---- 45 files changed, 216 insertions(+), 1049 deletions(-) delete mode 100644 packages/batten-asgi/pyproject.toml delete mode 100644 packages/batten-contracts/LICENSE-APACHE delete mode 100644 packages/batten-contracts/LICENSE-MIT delete mode 100644 packages/batten-contracts/NOTICE delete mode 100644 packages/batten-contracts/pyproject.toml rename packages/{batten-umf-postgres => batten-local}/src/batten/umf_postgres/__init__.py (100%) rename packages/{batten-umf-postgres => batten-local}/src/batten/umf_postgres/local/__init__.py (100%) rename packages/{batten-umf-postgres => batten-local}/src/batten/umf_postgres/local/_deployment.py (100%) rename packages/{batten-asgi/src/batten/asgi => batten-local/src/batten/umf_postgres}/py.typed (100%) delete mode 100644 packages/batten-runtime/LICENSE-APACHE delete mode 100644 packages/batten-runtime/LICENSE-MIT delete mode 100644 packages/batten-runtime/NOTICE delete mode 100644 packages/batten-runtime/pyproject.toml delete mode 100644 packages/batten-tables/LICENSE-APACHE delete mode 100644 packages/batten-tables/LICENSE-MIT delete mode 100644 packages/batten-tables/NOTICE delete mode 100644 packages/batten-tables/pyproject.toml delete mode 100644 packages/batten-umf-postgres/LICENSE-APACHE delete mode 100644 packages/batten-umf-postgres/LICENSE-MIT delete mode 100644 packages/batten-umf-postgres/NOTICE delete mode 100644 packages/batten-umf-postgres/pyproject.toml rename packages/{batten-asgi => batten}/LICENSE-APACHE (100%) rename packages/{batten-asgi => batten}/LICENSE-MIT (100%) rename packages/{batten-asgi => batten}/NOTICE (100%) create mode 100644 packages/batten/pyproject.toml rename packages/{batten-asgi => batten}/src/batten/asgi/__init__.py (100%) rename packages/{batten-asgi => batten}/src/batten/asgi/_ports.py (100%) rename packages/{batten-asgi => batten}/src/batten/asgi/_registry.py (100%) rename packages/{batten-asgi => batten}/src/batten/asgi/_routes.py (100%) rename packages/{batten-asgi => batten}/src/batten/asgi/assets/registry.css (100%) rename packages/{batten-contracts/src/batten/contracts => batten/src/batten/asgi}/py.typed (100%) rename packages/{batten-contracts => batten}/src/batten/contracts/__init__.py (100%) rename packages/{batten-runtime/src/batten/runtime => batten/src/batten/contracts}/py.typed (100%) rename packages/{batten-runtime => batten}/src/batten/runtime/__init__.py (100%) rename packages/{batten-tables/src/batten/tables => batten/src/batten/runtime}/py.typed (100%) rename packages/{batten-tables => batten}/src/batten/tables/__init__.py (100%) rename packages/{batten-umf-postgres/src/batten/umf_postgres => batten/src/batten/tables}/py.typed (100%) create mode 100644 scripts/check_versions.py diff --git a/examples/approval-desk/pyproject.toml b/examples/approval-desk/pyproject.toml index ad870c9..a3aa445 100644 --- a/examples/approval-desk/pyproject.toml +++ b/examples/approval-desk/pyproject.toml @@ -4,11 +4,16 @@ build-backend = "hatchling.build" [project] name = "novirhyza-batten-approval-desk" -version = "0.1.0a2" -requires-python = ">=3.11,<3.15" +version = "0.1.0a3" +description = "Batten example: a local approval desk on PostgreSQL 18" +requires-python = ">=3.11,<3.14" +authors = [{name = "Synaptiq"}] license = "MIT OR Apache-2.0" license-files = ["LICENSE-MIT", "LICENSE-APACHE", "NOTICE"] -dependencies = ["novirhyza-batten-local==0.1.0a2"] +dependencies = ["novirhyza-batten-local==0.1.0a3"] + +[project.urls] +Repository = "https://github.com/DocumentDrivenDX/batten" [project.scripts] batten-approval = "approval_desk.cli:main" diff --git a/packages/batten-asgi/pyproject.toml b/packages/batten-asgi/pyproject.toml deleted file mode 100644 index b74bdc5..0000000 --- a/packages/batten-asgi/pyproject.toml +++ /dev/null @@ -1,14 +0,0 @@ -[build-system] -requires = ["hatchling==1.33.0"] -build-backend = "hatchling.build" - -[project] -name = "novirhyza-batten-asgi" -version = "0.1.0a2" -requires-python = ">=3.11" -license = "MIT OR Apache-2.0" -license-files = ["LICENSE-MIT", "LICENSE-APACHE", "NOTICE"] -dependencies = ["novirhyza-batten-runtime==0.1.0a2", "starlette==1.10.0", "uvicorn==0.54.0"] - -[tool.hatch.build.targets.wheel] -packages = ["src/batten"] diff --git a/packages/batten-contracts/LICENSE-APACHE b/packages/batten-contracts/LICENSE-APACHE deleted file mode 100644 index d645695..0000000 --- a/packages/batten-contracts/LICENSE-APACHE +++ /dev/null @@ -1,202 +0,0 @@ - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. diff --git a/packages/batten-contracts/LICENSE-MIT b/packages/batten-contracts/LICENSE-MIT deleted file mode 100644 index 68ac2d1..0000000 --- a/packages/batten-contracts/LICENSE-MIT +++ /dev/null @@ -1,21 +0,0 @@ -MIT License - -Copyright (c) 2026 Synaptiq - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. diff --git a/packages/batten-contracts/NOTICE b/packages/batten-contracts/NOTICE deleted file mode 100644 index 88edbfb..0000000 --- a/packages/batten-contracts/NOTICE +++ /dev/null @@ -1,5 +0,0 @@ -Batten -Copyright 2026 Synaptiq - -Licensed under MIT OR Apache-2.0, at your option. -See LICENSE-MIT and LICENSE-APACHE. diff --git a/packages/batten-contracts/pyproject.toml b/packages/batten-contracts/pyproject.toml deleted file mode 100644 index 9bf165b..0000000 --- a/packages/batten-contracts/pyproject.toml +++ /dev/null @@ -1,14 +0,0 @@ -[build-system] -requires = ["hatchling==1.33.0"] -build-backend = "hatchling.build" - -[project] -name = "novirhyza-batten-contracts" -version = "0.1.0a2" -requires-python = ">=3.11" -license = "MIT OR Apache-2.0" -license-files = ["LICENSE-MIT", "LICENSE-APACHE", "NOTICE"] -dependencies = [] - -[tool.hatch.build.targets.wheel] -packages = ["src/batten"] diff --git a/packages/batten-local/pyproject.toml b/packages/batten-local/pyproject.toml index 0203d37..b914603 100644 --- a/packages/batten-local/pyproject.toml +++ b/packages/batten-local/pyproject.toml @@ -4,11 +4,25 @@ build-backend = "hatchling.build" [project] name = "novirhyza-batten-local" -version = "0.1.0a2" -requires-python = ">=3.11,<3.15" +version = "0.1.0a3" +description = "Batten local host: UMF/Weft tables on a pgserver PostgreSQL 18 cluster" +requires-python = ">=3.11,<3.14" license = "MIT OR Apache-2.0" license-files = ["LICENSE-MIT", "LICENSE-APACHE", "NOTICE"] -dependencies = ["novirhyza-batten-asgi==0.1.0a2", "novirhyza-batten-umf-postgres==0.1.0a2", "opentelemetry-sdk==1.45.2", "opentelemetry-instrumentation-psycopg==0.66b2", "pgserver-pg18==18.6.1"] +authors = [{name = "Synaptiq"}] +dependencies = [ + "novirhyza-batten==0.1.0a3", + "umf-access>=0.1.0.dev8,<0.2", + "umf-codegen>=0.10.8,<0.11", + "umf-weft>=0.4.57,<0.5", + "psycopg[binary]>=3.3.7,<4", + "pgserver-pg18>=18.6.1,<19", + "opentelemetry-sdk>=1.45,<2", + "opentelemetry-instrumentation-psycopg>=0.66b2", +] + +[project.urls] +Repository = "https://github.com/DocumentDrivenDX/batten" [tool.hatch.build.targets.wheel] packages = ["src/batten"] diff --git a/packages/batten-umf-postgres/src/batten/umf_postgres/__init__.py b/packages/batten-local/src/batten/umf_postgres/__init__.py similarity index 100% rename from packages/batten-umf-postgres/src/batten/umf_postgres/__init__.py rename to packages/batten-local/src/batten/umf_postgres/__init__.py diff --git a/packages/batten-umf-postgres/src/batten/umf_postgres/local/__init__.py b/packages/batten-local/src/batten/umf_postgres/local/__init__.py similarity index 100% rename from packages/batten-umf-postgres/src/batten/umf_postgres/local/__init__.py rename to packages/batten-local/src/batten/umf_postgres/local/__init__.py diff --git a/packages/batten-umf-postgres/src/batten/umf_postgres/local/_deployment.py b/packages/batten-local/src/batten/umf_postgres/local/_deployment.py similarity index 100% rename from packages/batten-umf-postgres/src/batten/umf_postgres/local/_deployment.py rename to packages/batten-local/src/batten/umf_postgres/local/_deployment.py diff --git a/packages/batten-asgi/src/batten/asgi/py.typed b/packages/batten-local/src/batten/umf_postgres/py.typed similarity index 100% rename from packages/batten-asgi/src/batten/asgi/py.typed rename to packages/batten-local/src/batten/umf_postgres/py.typed diff --git a/packages/batten-runtime/LICENSE-APACHE b/packages/batten-runtime/LICENSE-APACHE deleted file mode 100644 index d645695..0000000 --- a/packages/batten-runtime/LICENSE-APACHE +++ /dev/null @@ -1,202 +0,0 @@ - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. diff --git a/packages/batten-runtime/LICENSE-MIT b/packages/batten-runtime/LICENSE-MIT deleted file mode 100644 index 68ac2d1..0000000 --- a/packages/batten-runtime/LICENSE-MIT +++ /dev/null @@ -1,21 +0,0 @@ -MIT License - -Copyright (c) 2026 Synaptiq - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. diff --git a/packages/batten-runtime/NOTICE b/packages/batten-runtime/NOTICE deleted file mode 100644 index 88edbfb..0000000 --- a/packages/batten-runtime/NOTICE +++ /dev/null @@ -1,5 +0,0 @@ -Batten -Copyright 2026 Synaptiq - -Licensed under MIT OR Apache-2.0, at your option. -See LICENSE-MIT and LICENSE-APACHE. diff --git a/packages/batten-runtime/pyproject.toml b/packages/batten-runtime/pyproject.toml deleted file mode 100644 index e1a20c0..0000000 --- a/packages/batten-runtime/pyproject.toml +++ /dev/null @@ -1,14 +0,0 @@ -[build-system] -requires = ["hatchling==1.33.0"] -build-backend = "hatchling.build" - -[project] -name = "novirhyza-batten-runtime" -version = "0.1.0a2" -requires-python = ">=3.11" -license = "MIT OR Apache-2.0" -license-files = ["LICENSE-MIT", "LICENSE-APACHE", "NOTICE"] -dependencies = ["novirhyza-batten-contracts==0.1.0a2"] - -[tool.hatch.build.targets.wheel] -packages = ["src/batten"] diff --git a/packages/batten-storage/pyproject.toml b/packages/batten-storage/pyproject.toml index 2342f8e..0fe1788 100644 --- a/packages/batten-storage/pyproject.toml +++ b/packages/batten-storage/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "novirhyza-batten-storage" -version = "0.1.0a1" +version = "0.1.0a3" description = "Batten portable object storage and managed local filesystem adapter" requires-python = ">=3.11" license = "MIT OR Apache-2.0" diff --git a/packages/batten-tables/LICENSE-APACHE b/packages/batten-tables/LICENSE-APACHE deleted file mode 100644 index d645695..0000000 --- a/packages/batten-tables/LICENSE-APACHE +++ /dev/null @@ -1,202 +0,0 @@ - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. diff --git a/packages/batten-tables/LICENSE-MIT b/packages/batten-tables/LICENSE-MIT deleted file mode 100644 index 68ac2d1..0000000 --- a/packages/batten-tables/LICENSE-MIT +++ /dev/null @@ -1,21 +0,0 @@ -MIT License - -Copyright (c) 2026 Synaptiq - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. diff --git a/packages/batten-tables/NOTICE b/packages/batten-tables/NOTICE deleted file mode 100644 index 88edbfb..0000000 --- a/packages/batten-tables/NOTICE +++ /dev/null @@ -1,5 +0,0 @@ -Batten -Copyright 2026 Synaptiq - -Licensed under MIT OR Apache-2.0, at your option. -See LICENSE-MIT and LICENSE-APACHE. diff --git a/packages/batten-tables/pyproject.toml b/packages/batten-tables/pyproject.toml deleted file mode 100644 index 76f9f1e..0000000 --- a/packages/batten-tables/pyproject.toml +++ /dev/null @@ -1,14 +0,0 @@ -[build-system] -requires = ["hatchling==1.33.0"] -build-backend = "hatchling.build" - -[project] -name = "novirhyza-batten-tables" -version = "0.1.0a2" -requires-python = ">=3.11" -license = "MIT OR Apache-2.0" -license-files = ["LICENSE-MIT", "LICENSE-APACHE", "NOTICE"] -dependencies = ["novirhyza-batten-contracts==0.1.0a2"] - -[tool.hatch.build.targets.wheel] -packages = ["src/batten"] diff --git a/packages/batten-umf-postgres/LICENSE-APACHE b/packages/batten-umf-postgres/LICENSE-APACHE deleted file mode 100644 index d645695..0000000 --- a/packages/batten-umf-postgres/LICENSE-APACHE +++ /dev/null @@ -1,202 +0,0 @@ - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. diff --git a/packages/batten-umf-postgres/LICENSE-MIT b/packages/batten-umf-postgres/LICENSE-MIT deleted file mode 100644 index 68ac2d1..0000000 --- a/packages/batten-umf-postgres/LICENSE-MIT +++ /dev/null @@ -1,21 +0,0 @@ -MIT License - -Copyright (c) 2026 Synaptiq - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. diff --git a/packages/batten-umf-postgres/NOTICE b/packages/batten-umf-postgres/NOTICE deleted file mode 100644 index 88edbfb..0000000 --- a/packages/batten-umf-postgres/NOTICE +++ /dev/null @@ -1,5 +0,0 @@ -Batten -Copyright 2026 Synaptiq - -Licensed under MIT OR Apache-2.0, at your option. -See LICENSE-MIT and LICENSE-APACHE. diff --git a/packages/batten-umf-postgres/pyproject.toml b/packages/batten-umf-postgres/pyproject.toml deleted file mode 100644 index bbaf35d..0000000 --- a/packages/batten-umf-postgres/pyproject.toml +++ /dev/null @@ -1,17 +0,0 @@ -[build-system] -requires = ["hatchling==1.33.0"] -build-backend = "hatchling.build" - -[project] -name = "novirhyza-batten-umf-postgres" -version = "0.1.0a2" -requires-python = ">=3.11" -license = "MIT OR Apache-2.0" -license-files = ["LICENSE-MIT", "LICENSE-APACHE", "NOTICE"] -dependencies = ["novirhyza-batten-tables==0.1.0a2", "umf-access==0.1.0.dev8", "umf-codegen==0.10.8", "psycopg[binary]==3.3.7", "umf-weft==0.4.57"] - -[project.optional-dependencies] -local = ["pgserver-pg18==18.6.1", "opentelemetry-instrumentation-psycopg==0.66b2"] - -[tool.hatch.build.targets.wheel] -packages = ["src/batten"] diff --git a/packages/batten-asgi/LICENSE-APACHE b/packages/batten/LICENSE-APACHE similarity index 100% rename from packages/batten-asgi/LICENSE-APACHE rename to packages/batten/LICENSE-APACHE diff --git a/packages/batten-asgi/LICENSE-MIT b/packages/batten/LICENSE-MIT similarity index 100% rename from packages/batten-asgi/LICENSE-MIT rename to packages/batten/LICENSE-MIT diff --git a/packages/batten-asgi/NOTICE b/packages/batten/NOTICE similarity index 100% rename from packages/batten-asgi/NOTICE rename to packages/batten/NOTICE diff --git a/packages/batten/pyproject.toml b/packages/batten/pyproject.toml new file mode 100644 index 0000000..5249af3 --- /dev/null +++ b/packages/batten/pyproject.toml @@ -0,0 +1,19 @@ +[build-system] +requires = ["hatchling==1.33.0"] +build-backend = "hatchling.build" + +[project] +name = "novirhyza-batten" +version = "0.1.0a3" +description = "Batten application SDK: operation contracts, host runtime, table port and ASGI transport" +requires-python = ">=3.11" +license = "MIT OR Apache-2.0" +license-files = ["LICENSE-MIT", "LICENSE-APACHE", "NOTICE"] +authors = [{name = "Synaptiq"}] +dependencies = ["starlette>=1.10,<2", "uvicorn>=0.54,<1"] + +[project.urls] +Repository = "https://github.com/DocumentDrivenDX/batten" + +[tool.hatch.build.targets.wheel] +packages = ["src/batten"] diff --git a/packages/batten-asgi/src/batten/asgi/__init__.py b/packages/batten/src/batten/asgi/__init__.py similarity index 100% rename from packages/batten-asgi/src/batten/asgi/__init__.py rename to packages/batten/src/batten/asgi/__init__.py diff --git a/packages/batten-asgi/src/batten/asgi/_ports.py b/packages/batten/src/batten/asgi/_ports.py similarity index 100% rename from packages/batten-asgi/src/batten/asgi/_ports.py rename to packages/batten/src/batten/asgi/_ports.py diff --git a/packages/batten-asgi/src/batten/asgi/_registry.py b/packages/batten/src/batten/asgi/_registry.py similarity index 100% rename from packages/batten-asgi/src/batten/asgi/_registry.py rename to packages/batten/src/batten/asgi/_registry.py diff --git a/packages/batten-asgi/src/batten/asgi/_routes.py b/packages/batten/src/batten/asgi/_routes.py similarity index 100% rename from packages/batten-asgi/src/batten/asgi/_routes.py rename to packages/batten/src/batten/asgi/_routes.py diff --git a/packages/batten-asgi/src/batten/asgi/assets/registry.css b/packages/batten/src/batten/asgi/assets/registry.css similarity index 100% rename from packages/batten-asgi/src/batten/asgi/assets/registry.css rename to packages/batten/src/batten/asgi/assets/registry.css diff --git a/packages/batten-contracts/src/batten/contracts/py.typed b/packages/batten/src/batten/asgi/py.typed similarity index 100% rename from packages/batten-contracts/src/batten/contracts/py.typed rename to packages/batten/src/batten/asgi/py.typed diff --git a/packages/batten-contracts/src/batten/contracts/__init__.py b/packages/batten/src/batten/contracts/__init__.py similarity index 100% rename from packages/batten-contracts/src/batten/contracts/__init__.py rename to packages/batten/src/batten/contracts/__init__.py diff --git a/packages/batten-runtime/src/batten/runtime/py.typed b/packages/batten/src/batten/contracts/py.typed similarity index 100% rename from packages/batten-runtime/src/batten/runtime/py.typed rename to packages/batten/src/batten/contracts/py.typed diff --git a/packages/batten-runtime/src/batten/runtime/__init__.py b/packages/batten/src/batten/runtime/__init__.py similarity index 100% rename from packages/batten-runtime/src/batten/runtime/__init__.py rename to packages/batten/src/batten/runtime/__init__.py diff --git a/packages/batten-tables/src/batten/tables/py.typed b/packages/batten/src/batten/runtime/py.typed similarity index 100% rename from packages/batten-tables/src/batten/tables/py.typed rename to packages/batten/src/batten/runtime/py.typed diff --git a/packages/batten-tables/src/batten/tables/__init__.py b/packages/batten/src/batten/tables/__init__.py similarity index 100% rename from packages/batten-tables/src/batten/tables/__init__.py rename to packages/batten/src/batten/tables/__init__.py diff --git a/packages/batten-umf-postgres/src/batten/umf_postgres/py.typed b/packages/batten/src/batten/tables/py.typed similarity index 100% rename from packages/batten-umf-postgres/src/batten/umf_postgres/py.typed rename to packages/batten/src/batten/tables/py.typed diff --git a/pyproject.toml b/pyproject.toml index 182561a..ff93347 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,7 +1,7 @@ [project] name = "batten-development" -version = "0.1.0a2" -requires-python = ">=3.13,<3.14" +version = "0.1.0a3" +requires-python = ">=3.11,<3.14" dependencies = [] [dependency-groups] @@ -12,13 +12,8 @@ package = false find-links = ["https://github.com/DocumentDrivenDX/pgserver/releases/expanded_assets/pg18.6-pgv0.8.6-r2"] [tool.uv.workspace] -exclude = ["packages/batten-umf-postgres", "packages/batten-local", "examples/approval-desk"] -members = ["packages/batten-storage", "packages/batten-contracts", "packages/batten-runtime", "packages/batten-tables", "packages/batten-asgi"] - -[tool.uv.sources] -novirhyza-batten-contracts = { workspace = true } -novirhyza-batten-runtime = { workspace = true } -novirhyza-batten-tables = { workspace = true } +exclude = ["packages/batten-local", "examples/approval-desk"] +members = ["packages/batten", "packages/batten-storage"] [tool.ruff] target-version = "py311" @@ -43,11 +38,11 @@ typeCheckingMode = "strict" include = ["packages", "scripts", "tests", "docs/helix/site", "examples/approval-desk/src"] venvPath = "." venv = ".venv" -extraPaths = ["packages/batten-storage/src", "packages/batten-contracts/src", "packages/batten-runtime/src", "packages/batten-tables/src", "packages/batten-asgi/src", "packages/batten-umf-postgres/src", "packages/batten-local/src", "scripts", "docs/helix/site", "examples/approval-desk/src"] +extraPaths = ["packages/batten-storage/src", "packages/batten/src", "packages/batten-local/src", "scripts", "docs/helix/site", "examples/approval-desk/src"] [tool.pytest.ini_options] markers = ["integration: requires actual native services and installed browser artifacts"] -pythonpath = ["packages/batten-storage/src", "packages/batten-contracts/src", "packages/batten-runtime/src", "packages/batten-tables/src", "packages/batten-asgi/src", "packages/batten-umf-postgres/src", "packages/batten-local/src", "scripts", "docs/helix/site", "examples/approval-desk/src"] +pythonpath = ["packages/batten-storage/src", "packages/batten/src", "packages/batten-local/src", "scripts", "docs/helix/site", "examples/approval-desk/src"] testpaths = ["tests"] asyncio_mode = "auto" asyncio_default_fixture_loop_scope = "function" diff --git a/scripts/check_versions.py b/scripts/check_versions.py new file mode 100644 index 0000000..01f4cb5 --- /dev/null +++ b/scripts/check_versions.py @@ -0,0 +1,38 @@ +"""Fail unless every distribution has one version, equal to the tag when given.""" + +from __future__ import annotations + +import sys +import tomllib +from pathlib import Path + +PROJECTS = ( + "packages/batten", + "packages/batten-storage", + "packages/batten-local", + "examples/approval-desk", +) + + +def versions(root: Path) -> dict[str, str]: + found: dict[str, str] = {} + for project in PROJECTS: + metadata = tomllib.loads((root / project / "pyproject.toml").read_text()) + found[metadata["project"]["name"]] = metadata["project"]["version"] + return found + + +def main() -> None: + root = Path(__file__).resolve().parents[1] + found = versions(root) + unique = set(found.values()) + if len(unique) != 1: + raise SystemExit(f"versions differ: {found}") + (version,) = unique + if len(sys.argv) > 1 and sys.argv[1] != "v" + version: + raise SystemExit(f"tag {sys.argv[1]} does not match version {version}") + print(version) + + +if __name__ == "__main__": + main() diff --git a/scripts/prepare_approval.py b/scripts/prepare_approval.py index 1296ab4..5e70b40 100644 --- a/scripts/prepare_approval.py +++ b/scripts/prepare_approval.py @@ -8,7 +8,7 @@ import tomllib from pathlib import Path -PACKAGES = ("contracts", "runtime", "tables", "asgi", "umf-postgres", "local") +PACKAGES = ("batten", "batten-local") FIND_LINKS = "https://github.com/DocumentDrivenDX/pgserver/releases/expanded_assets/pg18.6-pgv0.8.6-r2" @@ -71,6 +71,9 @@ def main() -> None: parser.add_argument( "--app-only", action="store_true", help="rebuild only the example app" ) + parser.add_argument( + "--assets-only", action="store_true", help="only bundle the web assets" + ) args = parser.parse_args() root = Path(__file__).resolve().parents[1] cache = root / ".cache" @@ -78,12 +81,14 @@ def main() -> None: runtime = cache / "approval-runtime" wheels.mkdir(parents=True, exist_ok=True) assets(root) + if args.assets_only: + return app = root / "examples/approval-desk" projects = ( [app] if args.app_only else [ - *(root / "packages" / ("batten-" + name) for name in PACKAGES), + *(root / "packages" / name for name in PACKAGES), app, ] ) diff --git a/tests/storage/test_distribution.py b/tests/storage/test_distribution.py index fd5b65a..b9eb4b3 100644 --- a/tests/storage/test_distribution.py +++ b/tests/storage/test_distribution.py @@ -11,7 +11,7 @@ def test_installed_wheel_has_no_platform_dependencies(tmp_path: Path) -> None: root = Path(__file__).resolve().parents[2] wheels = tmp_path / "wheels" - for name in ("storage", "contracts", "runtime", "tables"): + for name in ("batten-storage", "batten"): subprocess.run( [ sys.executable, @@ -21,7 +21,7 @@ def test_installed_wheel_has_no_platform_dependencies(tmp_path: Path) -> None: "--no-isolation", "--outdir", str(wheels), - str(root / "packages" / ("batten-" + name)), + str(root / "packages" / name), ], check=True, capture_output=True, diff --git a/uv.lock b/uv.lock index a7ff654..a76594b 100644 --- a/uv.lock +++ b/uv.lock @@ -1,15 +1,16 @@ version = 1 revision = 5 -requires-python = "==3.13.*" +requires-python = ">=3.11, <3.14" +resolution-markers = [ + "python_full_version >= '3.12' and sys_platform == 'emscripten'", + "python_full_version < '3.12' or sys_platform != 'emscripten'", +] [manifest] members = [ "batten-development", - "novirhyza-batten-asgi", - "novirhyza-batten-contracts", - "novirhyza-batten-runtime", + "novirhyza-batten", "novirhyza-batten-storage", - "novirhyza-batten-tables", ] [[package]] @@ -36,7 +37,7 @@ wheels = [ [[package]] name = "batten-development" -version = "0.1.0a2" +version = "0.1.0a3" source = { virtual = "." } [package.dev-dependencies] @@ -167,9 +168,10 @@ source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "anyio", marker = "sys_platform != 'emscripten'" }, { name = "httpcore2", marker = "sys_platform != 'emscripten'" }, - { name = "httpx2-jsfetch", marker = "sys_platform == 'emscripten'" }, + { name = "httpx2-jsfetch", marker = "python_full_version >= '3.12' and sys_platform == 'emscripten'" }, { name = "idna" }, { name = "truststore", marker = "sys_platform != 'emscripten'" }, + { name = "typing-extensions", marker = "python_full_version < '3.13'" }, ] sdist = { url = "https://files.pythonhosted.org/packages/43/73/5ca2cedf5e4e50423d1c258877865a6b62793633b561c58499f8aeb33b7e/httpx2-2.16.0.tar.gz", hash = "sha256:0d54c98128e8f2ff7fbbde0fca8c359e5f032edeaaaac443cdb7f31f685bcd7f", size = 103116, upload-time = "2026-10-21T07:09:46.348Z" } wheels = [ @@ -213,54 +215,25 @@ wheels = [ ] [[package]] -name = "novirhyza-batten-asgi" -version = "0.1.0a2" -source = { editable = "packages/batten-asgi" } +name = "novirhyza-batten" +version = "0.1.0a3" +source = { editable = "packages/batten" } dependencies = [ - { name = "novirhyza-batten-runtime" }, { name = "starlette" }, { name = "uvicorn" }, ] [package.metadata] requires-dist = [ - { name = "novirhyza-batten-runtime", editable = "packages/batten-runtime" }, - { name = "starlette", specifier = "==1.10.0" }, - { name = "uvicorn", specifier = "==0.54.0" }, + { name = "starlette", specifier = ">=1.10,<2" }, + { name = "uvicorn", specifier = ">=0.54,<1" }, ] -[[package]] -name = "novirhyza-batten-contracts" -version = "0.1.0a2" -source = { editable = "packages/batten-contracts" } - -[[package]] -name = "novirhyza-batten-runtime" -version = "0.1.0a2" -source = { editable = "packages/batten-runtime" } -dependencies = [ - { name = "novirhyza-batten-contracts" }, -] - -[package.metadata] -requires-dist = [{ name = "novirhyza-batten-contracts", editable = "packages/batten-contracts" }] - [[package]] name = "novirhyza-batten-storage" -version = "0.1.0a1" +version = "0.1.0a3" source = { editable = "packages/batten-storage" } -[[package]] -name = "novirhyza-batten-tables" -version = "0.1.0a2" -source = { editable = "packages/batten-tables" } -dependencies = [ - { name = "novirhyza-batten-contracts" }, -] - -[package.metadata] -requires-dist = [{ name = "novirhyza-batten-contracts", editable = "packages/batten-contracts" }] - [[package]] name = "opentelemetry-api" version = "1.45.2" @@ -372,7 +345,13 @@ dependencies = [ { name = "psutil" }, ] wheels = [ + { url = "https://github.com/DocumentDrivenDX/pgserver/releases/download/pg18.6-pgv0.8.6-r2/pgserver_pg18-18.6.1-cp311-cp311-macosx_14_0_arm64.whl" }, + { url = "https://github.com/DocumentDrivenDX/pgserver/releases/download/pg18.6-pgv0.8.6-r2/pgserver_pg18-18.6.1-cp312-cp312-macosx_14_0_arm64.whl" }, { url = "https://github.com/DocumentDrivenDX/pgserver/releases/download/pg18.6-pgv0.8.6-r2/pgserver_pg18-18.6.1-cp313-cp313-macosx_14_0_arm64.whl" }, + { url = "https://github.com/DocumentDrivenDX/pgserver/releases/download/pg18.6-pgv0.8.6-r2/pgserver_pg18-18.6.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl" }, + { url = "https://github.com/DocumentDrivenDX/pgserver/releases/download/pg18.6-pgv0.8.6-r2/pgserver_pg18-18.6.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl" }, + { url = "https://github.com/DocumentDrivenDX/pgserver/releases/download/pg18.6-pgv0.8.6-r2/pgserver_pg18-18.6.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl" }, + { url = "https://github.com/DocumentDrivenDX/pgserver/releases/download/pg18.6-pgv0.8.6-r2/pgserver_pg18-18.6.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl" }, { url = "https://github.com/DocumentDrivenDX/pgserver/releases/download/pg18.6-pgv0.8.6-r2/pgserver_pg18-18.6.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl" }, { url = "https://github.com/DocumentDrivenDX/pgserver/releases/download/pg18.6-pgv0.8.6-r2/pgserver_pg18-18.6.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl" }, ] @@ -422,6 +401,7 @@ name = "psycopg" version = "3.3.7" source = { registry = "https://pypi.org/simple" } dependencies = [ + { name = "typing-extensions", marker = "python_full_version < '3.13'" }, { name = "tzdata", marker = "sys_platform == 'win32'" }, ] sdist = { url = "https://files.pythonhosted.org/packages/77/a3/55c9fb649391fddec8d7ba3005162cd76e8cb3b2eea3dc922684aa0013e4/psycopg-3.3.7.tar.gz", hash = "sha256:6574f23fd79bf129ee0616b49f6e358faf7ae1bf3a362d2ad599cf8f9c3d4935", size = 168912, upload-time = "2026-11-03T03:58:07.876Z" } @@ -439,6 +419,28 @@ name = "psycopg-binary" version = "3.3.7" source = { registry = "https://pypi.org/simple" } wheels = [ + { url = "https://files.pythonhosted.org/packages/06/19/07272d51290a502281fa3f54e76ef95fa72bd05abd913a57f033162d7768/psycopg_binary-3.3.7-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:4f9ec0cc3b327f8ed1e2ba40441dd843be9c82b3ac5dfe75eb00ece02a454ec3", size = 4731229, upload-time = "2026-11-03T03:52:28.922Z" }, + { url = "https://files.pythonhosted.org/packages/a2/a3/beb642b331f1611f7f87c75c5b0803bfa779f6ccd4e79e381961484a20b2/psycopg_binary-3.3.7-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:0734da871182afdefcc9b3fbaf13c70408f47a2de64394208606d8f45c4027ec", size = 4779422, upload-time = "2026-11-03T03:52:34.545Z" }, + { url = "https://files.pythonhosted.org/packages/be/5d/41538a43e0364b8f8fc669056f8f2eeb884a7374c16f65695ee3868113af/psycopg_binary-3.3.7-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:05fa93c416af799f8d0db325e4a58ed0df68ef7ff85a48192b616b4e1be7be26", size = 5616589, upload-time = "2026-11-03T03:52:40.664Z" }, + { url = "https://files.pythonhosted.org/packages/5f/87/c290af551e9b71ef048601fe261e7f91212274fa1fb224619d35818aca33/psycopg_binary-3.3.7-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:652a6029e53635ef3106c726ef3b4c01429a586372dd516fc56e75ab8a2bd934", size = 5330007, upload-time = "2026-11-03T03:52:47.627Z" }, + { url = "https://files.pythonhosted.org/packages/af/e1/efa4ea43b53fcf0f33be16d968851b610fd02c45211306a97fc84446b877/psycopg_binary-3.3.7-cp311-cp311-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c2fa90f30e4a5a1dff00301797ec66b5eba991566291dcc9df6dfb6fd68965e1", size = 6879399, upload-time = "2026-11-03T03:52:57.022Z" }, + { url = "https://files.pythonhosted.org/packages/f3/2e/7d6d734fc4be304b567c47e28c6eca98cdcb30eeb84d8cb352f4bdadb0c0/psycopg_binary-3.3.7-cp311-cp311-manylinux_2_38_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:496da9a6f4f7fcdb8394b1273f9ffc10deb5a95dd2aa6e85212a732bfd9a2424", size = 5110921, upload-time = "2026-11-03T03:53:01.907Z" }, + { url = "https://files.pythonhosted.org/packages/d0/3c/d6e035a73062d3abbb8829bc294ae027eb7f99ca09bc0ddbea1d78627972/psycopg_binary-3.3.7-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:d7434c3fc858d86eb09217bce226274245957299d22e2c7d8fc7b564409d242e", size = 4647372, upload-time = "2026-11-03T03:53:06.633Z" }, + { url = "https://files.pythonhosted.org/packages/4f/f3/8078373f96894d3f4988a3ef924646bcecddce884dfc8f547a6d66cdb517/psycopg_binary-3.3.7-cp311-cp311-musllinux_1_2_ppc64le.whl", hash = "sha256:a07ead8eacaa3b2e130ebf5357035c53fc9bbb623fe5d7c02d83944ffeae5d09", size = 4343403, upload-time = "2026-11-03T03:53:16.037Z" }, + { url = "https://files.pythonhosted.org/packages/3e/4a/236c3be410e3c420249119c0ed7fc0372bd292f35f980efe1ca0825e42fc/psycopg_binary-3.3.7-cp311-cp311-musllinux_1_2_riscv64.whl", hash = "sha256:4e960429b237ccff892a489b9348ade8cf780a103fcea403ddf924e0a07ad671", size = 4058720, upload-time = "2026-11-03T03:53:22.364Z" }, + { url = "https://files.pythonhosted.org/packages/8a/78/50b5b85c16e3526c2e001d0faccf9241e2bf7407cd4ad2a16bd353e4a991/psycopg_binary-3.3.7-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:34e2cff14aafa3d0649b48cd18c447c163e0a3ec7bbfd2e38314cd721f33add7", size = 4363326, upload-time = "2026-11-03T03:53:26.846Z" }, + { url = "https://files.pythonhosted.org/packages/80/95/559b7910fe35a5f63adc7425bcad46c85ee10880dae8096b7789ea6d75ac/psycopg_binary-3.3.7-cp311-cp311-win_amd64.whl", hash = "sha256:cb6fe750879c781d3d3667b6d0f66318071d0245e60b51ad9a00186708978089", size = 3636509, upload-time = "2026-11-03T03:53:31.315Z" }, + { url = "https://files.pythonhosted.org/packages/bb/da/3a41bfb4ca39f601abaa20f8170545b27247df4d4850ee3647a10091c219/psycopg_binary-3.3.7-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:edfd6abb5da972cae50984d41d44cc744a6842ee359b0df24b39fb1524b1e654", size = 4710682, upload-time = "2026-11-03T03:53:37.421Z" }, + { url = "https://files.pythonhosted.org/packages/df/d9/775f908d6af11f0d658526cdd564dc54f03463c53de245cd7e23544c133b/psycopg_binary-3.3.7-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:6d43d35af50c66fd5b0d2537ef20bddee61b68fbfbd24f8c44a0be6f65a68301", size = 4773036, upload-time = "2026-11-03T03:53:44.926Z" }, + { url = "https://files.pythonhosted.org/packages/8f/7f/40944fa341e752bb79410bd2f6542c71e3103a476ff4e88cc780fd53caac/psycopg_binary-3.3.7-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:1a831476577db5e62f1aa3942a60c5088f459f2c14c0e2f4639a823d23b5ffb6", size = 5575526, upload-time = "2026-11-03T03:53:51.59Z" }, + { url = "https://files.pythonhosted.org/packages/df/70/0d68867bdb39834ae5a46d5afa1d12053dd12b061659652294fbaa092f71/psycopg_binary-3.3.7-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:df30e4e2fe7b4f4ae401326f8f24fd572d1f08543b97c2daff9bcb623aebb41f", size = 5300375, upload-time = "2026-11-03T03:53:57.765Z" }, + { url = "https://files.pythonhosted.org/packages/bf/04/4ab0135ff483b6bdcdb7fa2b6c74efec93b0d5bb2e0ffc33b099d9cae98c/psycopg_binary-3.3.7-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:71601439823d28250c28255b2204376a7d686c2ab1259e5b6e0fce70cd2309d5", size = 6852910, upload-time = "2026-11-03T03:54:03.57Z" }, + { url = "https://files.pythonhosted.org/packages/55/80/0d360077293a95f3c2539e2afe054fee657e1dd5278e00f2007b645f7841/psycopg_binary-3.3.7-cp312-cp312-manylinux_2_38_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:c9e740f8f9fda8ac878d11d590a8b802f9b0ebf7a2c4c1fbbd577b5ceaff6694", size = 5073829, upload-time = "2026-11-03T03:54:09.479Z" }, + { url = "https://files.pythonhosted.org/packages/f1/6d/8e1b4186702b55a54a2e8f8fb7b766484659c3298de58eec754b3c801691/psycopg_binary-3.3.7-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:e23fb1b141e9f05724f5bc83177427b3c32ca7f814450721614d23c4b2828cf5", size = 4618943, upload-time = "2026-11-03T03:54:17.659Z" }, + { url = "https://files.pythonhosted.org/packages/8d/cc/34bf9da0ce2103c7bab4de0e2716646448355fceab847620b74d67839819/psycopg_binary-3.3.7-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:d52a488169e52774a9e09d4d0d0082d6f19cb59c58f8308b53bf355ae160a1ac", size = 4302298, upload-time = "2026-11-03T03:54:25.646Z" }, + { url = "https://files.pythonhosted.org/packages/26/38/75b5dca8d42e983d900688dbc9ada57b55ebcc3406cbcea7f1b8c92eac32/psycopg_binary-3.3.7-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:b2cbb774a73d6f12fbc2ab4d2faddd05a043dd623dbd07df59ec42535b00fedf", size = 4020129, upload-time = "2026-11-03T03:54:30.715Z" }, + { url = "https://files.pythonhosted.org/packages/0f/6c/0dfac7abe24a08b98367960535d164544f89eb3eb317e16979db36365dc6/psycopg_binary-3.3.7-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:df59dd2a1aa038856952360bbc72599ed118fe14cef558a499476bf56b0ecb45", size = 4334125, upload-time = "2026-11-03T03:54:36.812Z" }, + { url = "https://files.pythonhosted.org/packages/36/60/f412c2accfb92f8382b812f45990965e4392674a1d0d1648fe743a8fe787/psycopg_binary-3.3.7-cp312-cp312-win_amd64.whl", hash = "sha256:7a1fd4e844630393800a86e55312c77dcdfa12dd7baf02da3230c7147a805793", size = 3619065, upload-time = "2026-11-03T03:54:41.265Z" }, { url = "https://files.pythonhosted.org/packages/ce/ff/936c13638c8b9bd4519d3ad7996e7600b066909156cb1cd6f55b73d2203e/psycopg_binary-3.3.7-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:e0639d06c50c684bb9867fb4c0593b7327525275142c0b620053c55134572773", size = 4715405, upload-time = "2026-11-03T03:54:45.749Z" }, { url = "https://files.pythonhosted.org/packages/7a/19/98a3d8dd5b61478ce242f017b70d68241d151826409ab3f88066ed2ec327/psycopg_binary-3.3.7-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:89b508e50ccfe93a440ce9450c33ff78a3e2462dab369e66ee63e725562421cb", size = 4775846, upload-time = "2026-11-03T03:54:51.138Z" }, { url = "https://files.pythonhosted.org/packages/9d/74/c855489f8be5ee3d8bfd4cee523e036a49b3aa1bfdc6eb5b72c34828fdb2/psycopg_binary-3.3.7-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:a0aeb1b680b2ee414a0196a9dd94b17edaa75c1c04f7cddadc9aae95d0dd940c", size = 5575585, upload-time = "2026-11-03T03:54:57.816Z" }, @@ -476,6 +478,36 @@ dependencies = [ ] sdist = { url = "https://files.pythonhosted.org/packages/af/8e/23ec1021834e35041fbb2f10946141e6acdfd39379c45cc4d65a4e8a1d98/pydantic_core-2.50.2.tar.gz", hash = "sha256:1b0e8dc3932cf4e9ed5727570325cacc716b9409ffc794a221c0ccc72e8eb775", size = 518711, upload-time = "2026-10-29T16:34:57.465Z" } wheels = [ + { url = "https://files.pythonhosted.org/packages/8d/0f/1043d3840b7859cc19abede795e058a785ebc1fa011b022b0a69514dd5c5/pydantic_core-2.50.2-cp311-cp311-macosx_10_12_x86_64.whl", hash = "sha256:2115d7ca6d58554af8a14da3dd32d361a4fe999fae52f115a6155679b5b00e72", size = 2160886, upload-time = "2026-10-29T16:31:48.009Z" }, + { url = "https://files.pythonhosted.org/packages/d8/95/6211dfe1794bde5ce14f3de2212551196784c67411ac5249d8aa627e3e23/pydantic_core-2.50.2-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:b2dd65864aad38dbcc57c3d0e2c978d4286e063378137d8fc0c9fcd558943285", size = 2115730, upload-time = "2026-10-29T16:31:49.449Z" }, + { url = "https://files.pythonhosted.org/packages/67/42/50a1a9721cfc21d360916754096c90467fa21386ef16875445ea06a4cf6e/pydantic_core-2.50.2-cp311-cp311-manylinux1_i686.manylinux_2_5_i686.whl", hash = "sha256:26b778d4ebb75f181d36220ff0f54a513fc46f053d9b09ce79993c2f00bc45cc", size = 2274234, upload-time = "2026-10-29T16:31:50.668Z" }, + { url = "https://files.pythonhosted.org/packages/69/0b/22349c3114a3b3c400333ba6ec1d2e127fc9a4e4682440d8e23d954df0d1/pydantic_core-2.50.2-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:e80c47314c7233e7105a7efcfffd89d56e479e558189d1959eeeaf2639a27680", size = 2116001, upload-time = "2026-10-29T16:31:51.887Z" }, + { url = "https://files.pythonhosted.org/packages/d8/2e/3b88612239e87cfddd370362e93b18a50d5075883817d6b35e8e3871af75/pydantic_core-2.50.2-cp311-cp311-manylinux2014_armv7l.manylinux_2_17_armv7l.whl", hash = "sha256:3bfe12243b3ded517c6734d91f127489e2f51bf95cb533b53130fe360333db80", size = 2204318, upload-time = "2026-10-29T16:31:53.342Z" }, + { url = "https://files.pythonhosted.org/packages/3b/3b/a735bf3967d0fd73b512705d6f80fbe179d3b6208779721e86613cdf736d/pydantic_core-2.50.2-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:01eb0282d0b3a065d55956d1be9ce398c46db3dd6d277a6cb2358c8aa8c53179", size = 2392365, upload-time = "2026-10-29T16:31:54.721Z" }, + { url = "https://files.pythonhosted.org/packages/9d/16/0a0febc06b311d6ca43dd7fa068273d2c4d3c4ad86ac4a6c2f2cbe924c23/pydantic_core-2.50.2-cp311-cp311-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:196b87b48b2695426920e8470d20f9e99f019ebd86f15808aa018b68086840cd", size = 2443963, upload-time = "2026-10-29T16:31:56.455Z" }, + { url = "https://files.pythonhosted.org/packages/70/7d/22bd04c22adae266ae5e99e4c34bd882daf6c93c35bda2f9674421c1e7c3/pydantic_core-2.50.2-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:86e7abd24a67f61a4bfe8df059b67a2bdd8bf33705178e98463195d140bd3780", size = 2236349, upload-time = "2026-10-29T16:31:57.837Z" }, + { url = "https://files.pythonhosted.org/packages/2b/c4/77b12031179047a292128eee12cd7aad899d82391157356a581117e232e7/pydantic_core-2.50.2-cp311-cp311-manylinux_2_31_riscv64.whl", hash = "sha256:aff31602e8518594e6f6bc670cdb27e37cb7dbeb2d5d0b76a7707b70fe951ddf", size = 2272702, upload-time = "2026-10-29T16:31:59.287Z" }, + { url = "https://files.pythonhosted.org/packages/98/58/41f674077b08b79bf2f2ae3c777a5b7b8758647433c6c621580b612e8c1e/pydantic_core-2.50.2-cp311-cp311-musllinux_1_1_aarch64.whl", hash = "sha256:a88851e8e332588cb8cced8b5318d1163c7d0bb87830aa8dcafbc4ae9602b73c", size = 2311296, upload-time = "2026-10-29T16:32:00.722Z" }, + { url = "https://files.pythonhosted.org/packages/61/af/527d1d29cfb8efc7c7f9ed9f35ab5b16a33b1837b186c6e42ecbca699817/pydantic_core-2.50.2-cp311-cp311-musllinux_1_1_armv7l.whl", hash = "sha256:3b1bb3950e0794a795c9344d818d5b476189b0c9c9755e8eb8fde87c3acee17a", size = 2481042, upload-time = "2026-10-29T16:32:02.423Z" }, + { url = "https://files.pythonhosted.org/packages/57/35/79877aaf083424e67c870ba07c0b5ed36a2096a0cfc8b058c1d921797723/pydantic_core-2.50.2-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:928a44ad1e21a7e923eb924d601605f0694cd187d2ce5d40bf7ad76650f4627d", size = 2488007, upload-time = "2026-10-29T16:32:03.819Z" }, + { url = "https://files.pythonhosted.org/packages/aa/45/5a627e40690c21be388c4abfddaefbf589e359614456156c90432ac0a76a/pydantic_core-2.50.2-cp311-cp311-win32.whl", hash = "sha256:9a87744e683d9a13f60b7fa5242c17f8d283ffa94ad727cb19063b48c3d34960", size = 2121376, upload-time = "2026-10-29T16:32:05.053Z" }, + { url = "https://files.pythonhosted.org/packages/1f/9b/d21478003682505aad9619ff9e086bd29aced2615b23d5315cb37de14cad/pydantic_core-2.50.2-cp311-cp311-win_amd64.whl", hash = "sha256:b958c217c6e56bef261f516e4caf5d490b079ad6a428752afada5a764cca6c71", size = 2238388, upload-time = "2026-10-29T16:32:06.811Z" }, + { url = "https://files.pythonhosted.org/packages/e7/26/670a52ea740fd60f5e0a873b74505714c4bfd04c4344f789310005c4cbbd/pydantic_core-2.50.2-cp311-cp311-win_arm64.whl", hash = "sha256:b0e6a2152706d84f7da8b9d34dcecc7e9bde678af32c40bd5b405f427ae0fbdb", size = 2185763, upload-time = "2026-10-29T16:32:08.441Z" }, + { url = "https://files.pythonhosted.org/packages/d6/65/6609a66cda909d414c58438f9bd70b1e947fe12c25f6bd40c93121afd7ef/pydantic_core-2.50.2-cp312-cp312-macosx_10_12_x86_64.whl", hash = "sha256:e3d824b6152e1c0fd58dc6266f2de470eb7b2286135294f5f7cd26a0f0693738", size = 2220341, upload-time = "2026-10-29T16:32:10.193Z" }, + { url = "https://files.pythonhosted.org/packages/f9/0b/92463ae7be78d73885487f72c4599902c2cc190378bccaad5718b7495250/pydantic_core-2.50.2-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:596921489390a002d6a5e303384a0f1f98384f8bb550fbf38a1aafa6093da0f9", size = 2093701, upload-time = "2026-10-29T16:32:11.502Z" }, + { url = "https://files.pythonhosted.org/packages/62/d3/24147a1aa22f7eade546172750e1110fd7b2793998057809800d3ebeae4e/pydantic_core-2.50.2-cp312-cp312-manylinux1_i686.manylinux_2_5_i686.whl", hash = "sha256:36d8b9725684ca3bf658b90a101d335fc8cae405bb22196b7b5ef41344913756", size = 2253622, upload-time = "2026-10-29T16:32:13.051Z" }, + { url = "https://files.pythonhosted.org/packages/f6/50/2628ca3c83a0d9a6fda3305fe59b1b28e40c0221e8f234cd1ef86fb64745/pydantic_core-2.50.2-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:43a8fd56f3c681f3cda2d5c842ad28e88241df742dfcbe8fd1dd437a3056e1f6", size = 2114101, upload-time = "2026-10-29T16:32:14.702Z" }, + { url = "https://files.pythonhosted.org/packages/21/c8/cc6d7304a93f91f5e06260ccad71cc7d882489663a37dec009532379fc46/pydantic_core-2.50.2-cp312-cp312-manylinux2014_armv7l.manylinux_2_17_armv7l.whl", hash = "sha256:6f5a432c6c1ef18a1a02a04b3616b8d3f2f88b13faa46caae1ac6559ab202234", size = 2199541, upload-time = "2026-10-29T16:32:16.153Z" }, + { url = "https://files.pythonhosted.org/packages/65/d9/18f44ac5696b3e2b2384cb89c9fbe6ed69860f528e232b9fb46cc5b45a17/pydantic_core-2.50.2-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:5d3cd8be71c4da3c9b42cc92f17e5e3036bdca98bf18555a0e072c3fe87abbb4", size = 2368597, upload-time = "2026-10-29T16:32:17.544Z" }, + { url = "https://files.pythonhosted.org/packages/1d/22/5f2a48ef819a7e1b74fb003a85d27576ad2f9ddf3901b88998ac63ce1e00/pydantic_core-2.50.2-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:6a438cb8a3f87f2c49e82e43fb19511d4d5043f53e0787dc4df937ccb904373a", size = 2451701, upload-time = "2026-10-29T16:32:18.956Z" }, + { url = "https://files.pythonhosted.org/packages/08/93/2a6556bbdb8e918175af9d849a5d0b367b5644e41939d040f3a7215b1339/pydantic_core-2.50.2-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:9667637665acba166a7dbbc786f14c50512d3a01f7199e0e1a13b929e92d7c7a", size = 2242782, upload-time = "2026-10-29T16:32:20.381Z" }, + { url = "https://files.pythonhosted.org/packages/90/ed/dd9f29a92257f32eb5b99d5120826186ee0632ecc3aaf6c23e2fab89ed6d/pydantic_core-2.50.2-cp312-cp312-manylinux_2_31_riscv64.whl", hash = "sha256:b3e681208e2d39fde13fbea449ef2736a85ec1ea2afa41e9193a8c536e71dafe", size = 2253706, upload-time = "2026-10-29T16:32:22.293Z" }, + { url = "https://files.pythonhosted.org/packages/11/19/1ccf3bf38eb4ed97d8aeefc558458834ae0ad53fdbb1edf61af7228ea500/pydantic_core-2.50.2-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:6eb6ff07964f39e33c6f57fefe939514e76b8c0d4a694e5663e2e04e80cc1798", size = 2288603, upload-time = "2026-10-29T16:32:23.465Z" }, + { url = "https://files.pythonhosted.org/packages/ea/cd/bae2320fc89a65bcd87bf66ec83aac51b3b43b970a2edece15feb8af64dd/pydantic_core-2.50.2-cp312-cp312-musllinux_1_1_armv7l.whl", hash = "sha256:4eb54c25e3463d73e1e4ed439ffc45d1d7e590df40bc7bb06f11a906afd996c3", size = 2476597, upload-time = "2026-10-29T16:32:24.824Z" }, + { url = "https://files.pythonhosted.org/packages/db/35/1bdb8d52c8e562e95c5e6ebb5784792af568ac6a81470dd546d95f392b60/pydantic_core-2.50.2-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:91238117cd296352f54f24117ff5a227bdea428865dba1244aa0cdd1424c0bc2", size = 2478664, upload-time = "2026-10-29T16:32:26.197Z" }, + { url = "https://files.pythonhosted.org/packages/12/72/0179b40ac6a6b0899c61826f2e3e80f88063f6d821e0dd9641927de46700/pydantic_core-2.50.2-cp312-cp312-win32.whl", hash = "sha256:98722314e12a8e4fa346e0afd3fff2098b5732875ff45592b450a7b589b43c4f", size = 2108820, upload-time = "2026-10-29T16:32:27.736Z" }, + { url = "https://files.pythonhosted.org/packages/b4/fb/679144362d7e5162519d9f6631ec982521417de3196351c6c56485f5b29f/pydantic_core-2.50.2-cp312-cp312-win_amd64.whl", hash = "sha256:b381574614245f18fdb2d6d1aa8f149e225869c47b5ee7f81812de8977817314", size = 2252238, upload-time = "2026-10-29T16:32:29.572Z" }, + { url = "https://files.pythonhosted.org/packages/0f/68/e3ccc885c3e2086ff84d7ca496f45b974a9f0a49ce2da8973aaa3a369a4b/pydantic_core-2.50.2-cp312-cp312-win_arm64.whl", hash = "sha256:f07c965a8aa6d62145f122641f292129984f39a3e3697585b19298a1488287db", size = 2162565, upload-time = "2026-10-29T16:32:30.853Z" }, { url = "https://files.pythonhosted.org/packages/c2/fc/ac3ae9d934932ce3c380e7fe53e01372b49ef5dcb49db56f1a1f005b4d8c/pydantic_core-2.50.2-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:93eb41d626d9a2749a678823c70bba8c25033cef474ae8001fd7621adbbd8437", size = 2222463, upload-time = "2026-10-29T16:32:32.125Z" }, { url = "https://files.pythonhosted.org/packages/f7/0b/7605223654ed4e777d05668e914d32b476b1fa2bb756bff9820fe270456b/pydantic_core-2.50.2-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:7c539d452cba22f250103c7d1c00cbe9038eb705e657476e701c43374efd9f2e", size = 2093995, upload-time = "2026-10-29T16:32:33.496Z" }, { url = "https://files.pythonhosted.org/packages/b4/29/4a1a653cfedd3f5e1ccd3b1e919fe324fb45607d12c30fdd7ca5af16ba8d/pydantic_core-2.50.2-cp313-cp313-manylinux1_i686.manylinux_2_5_i686.whl", hash = "sha256:53bd25e8ab54c02bb4c55d4848c1d36f75f3b9a7356e83179fe27794d9e9e6c4", size = 2253178, upload-time = "2026-10-29T16:32:34.77Z" }, @@ -491,6 +523,26 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/35/10/2fefc082eb46f959e80735e859161305c0c2fbb3d5d20ac5547c49a84a3b/pydantic_core-2.50.2-cp313-cp313-win32.whl", hash = "sha256:bd6ecae08c0d871cf93b6f0d4ee76b06c65be44ea22311981a022b2f1948cf9d", size = 2108354, upload-time = "2026-10-29T16:32:54.276Z" }, { url = "https://files.pythonhosted.org/packages/6f/dd/14eeec394ec1422f9c4e9743cd746f4502232a7c65eb235d1a03729d94ab/pydantic_core-2.50.2-cp313-cp313-win_amd64.whl", hash = "sha256:e5c801bdf3cc92274b8fc2c7023c8751e5ae81260c009ac558ff55ce712a2d45", size = 2250556, upload-time = "2026-10-29T16:32:55.396Z" }, { url = "https://files.pythonhosted.org/packages/75/b7/a014acf1ae4b4aa7d32ff957e2250698637daa3a29448444180360b92284/pydantic_core-2.50.2-cp313-cp313-win_arm64.whl", hash = "sha256:fd9aa71a800c87c0f7ab53fa38009169a23a82c685989626ca74a4bd483e1b67", size = 2162633, upload-time = "2026-10-29T16:32:56.792Z" }, + { url = "https://files.pythonhosted.org/packages/f6/82/ec0384d2a74415aeef7fcd032d29af84a98da0ca25cfb4937b10a2ac78eb/pydantic_core-2.50.2-graalpy311-graalpy242_311_native-macosx_10_12_x86_64.whl", hash = "sha256:adec010c824290d4ca87047e8d8bfa4f85ac29f545f326cd5321696805d311ed", size = 2154528, upload-time = "2026-10-29T16:34:28.022Z" }, + { url = "https://files.pythonhosted.org/packages/8c/b4/46483477921934aa31eec9cb86ba95d2f620f4c71da749024c2e3b6e8203/pydantic_core-2.50.2-graalpy311-graalpy242_311_native-macosx_11_0_arm64.whl", hash = "sha256:f47c1349c3b4274aeb18459d54244881a5c0dee0fdccedffca45704ba5c9e0a0", size = 2072173, upload-time = "2026-10-29T16:34:29.771Z" }, + { url = "https://files.pythonhosted.org/packages/4a/16/c1eb6bdd67c9d5f42b290abb86948d8de288bdf4aeca06c588c3cfe6100b/pydantic_core-2.50.2-graalpy311-graalpy242_311_native-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:4ee64baeab403b9de9c92846c5c1abec28ffb046cbc023bfae059897841f88af", size = 2116695, upload-time = "2026-10-29T16:34:31.103Z" }, + { url = "https://files.pythonhosted.org/packages/ae/67/ccd8294730d9335c687facbdfd77515fa3b323e9bbb042c5d63addc6f5f8/pydantic_core-2.50.2-graalpy311-graalpy242_311_native-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:16ec8e07c37f02dcf68939cc7f202ba9a148cc155ee2acf22d337e10b24c2cb7", size = 2263561, upload-time = "2026-10-29T16:34:32.901Z" }, + { url = "https://files.pythonhosted.org/packages/64/4d/23560b11366b547e3e68a3b8f9c02557cee707effa54fd39dbb3c4fff1fa/pydantic_core-2.50.2-graalpy312-graalpy250_312_native-macosx_10_12_x86_64.whl", hash = "sha256:d18d56c1ec63b304f4bb3c7db7e0d311e61cca1b1c944590a4b13ac39b2ca92b", size = 2204868, upload-time = "2026-10-29T16:34:34.745Z" }, + { url = "https://files.pythonhosted.org/packages/06/58/b9ddfaad189143d6568627166a730b6624ca90bd9a9a4af4854df88d444b/pydantic_core-2.50.2-graalpy312-graalpy250_312_native-macosx_11_0_arm64.whl", hash = "sha256:41ed8abeffda6a880207fdc0cd1343a448cec3cc6b38b53f730c0745f745292d", size = 2049162, upload-time = "2026-10-29T16:34:36.186Z" }, + { url = "https://files.pythonhosted.org/packages/8b/20/99d259bf7835b2f13c6d0b3eb7bcf669fb6349986736fa7a8308a9e620b0/pydantic_core-2.50.2-graalpy312-graalpy250_312_native-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:b7abcfaf66c1dc14c5ed928c349614f223c972a8b021b4be9548dbea6c817371", size = 2112135, upload-time = "2026-10-29T16:34:37.777Z" }, + { url = "https://files.pythonhosted.org/packages/9b/ca/652c8fe599abacafd852479059d209e608596ad3de82f1bff22e9f0f02fe/pydantic_core-2.50.2-graalpy312-graalpy250_312_native-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:9e7460abce637f90e37f8c443559fbd687c38884d05cb69ef265e634945f4324", size = 2270339, upload-time = "2026-10-29T16:34:39.039Z" }, + { url = "https://files.pythonhosted.org/packages/18/9b/d240307fd6882a93a88bf038ff07e1a6dcac0e88f41951fe92c9b614f0b6/pydantic_core-2.50.2-pp311-pypy311_pp73-macosx_10_12_x86_64.whl", hash = "sha256:b583ddeee6a6bb5bbc04462167c68034913221139d52d9f155ca6d1637a2fdcf", size = 2157909, upload-time = "2026-10-29T16:34:40.355Z" }, + { url = "https://files.pythonhosted.org/packages/30/e5/d336fb654f8f1584b4a20d71f92c2a966419bc5eafffd36848d8cb1a916d/pydantic_core-2.50.2-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:5ab5738c39b25b5dc5a721270e2269a2f5e86e614375e6c07ee6caab8cbc0f2f", size = 2075773, upload-time = "2026-10-29T16:34:41.761Z" }, + { url = "https://files.pythonhosted.org/packages/38/08/18203f64a405f11c3e4d569c9f49ad7a0b5901cd5fa2dff2436d28531c60/pydantic_core-2.50.2-pp311-pypy311_pp73-manylinux1_i686.manylinux_2_5_i686.whl", hash = "sha256:21a902e546032c82b7275552345a2342d862e0541aea7226c91067c396e68b3f", size = 2277290, upload-time = "2026-10-29T16:34:42.952Z" }, + { url = "https://files.pythonhosted.org/packages/9e/c4/a4e0ae45ad1554c38caa93e200fdd08e74d2c0149b4242c78b2475903379/pydantic_core-2.50.2-pp311-pypy311_pp73-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:92ada606285dab054e40848a951f583c537cde1e54701ea1305ec0096877012d", size = 2265597, upload-time = "2026-10-29T16:34:44.244Z" }, + { url = "https://files.pythonhosted.org/packages/99/20/304baf7724ac137b921ce793e4b686cf4cddc431da4888e5419e7bc7374f/pydantic_core-2.50.2-pp311-pypy311_pp73-musllinux_1_1_aarch64.whl", hash = "sha256:c1b65a42afc73b39e6ae908ec7b9c3b9898676a7b15ce4c66d4965f7071007c8", size = 2289092, upload-time = "2026-10-29T16:34:45.55Z" }, + { url = "https://files.pythonhosted.org/packages/77/6f/0fe5ac160718d75f2f9729bb31aa9a349dadd0d32886b8c0ecc253629c46/pydantic_core-2.50.2-pp311-pypy311_pp73-musllinux_1_1_armv7l.whl", hash = "sha256:c324a7e0c0012e3974053f81a270d8f1aa23227571f4ddd3254c911bb356459b", size = 2458417, upload-time = "2026-10-29T16:34:46.827Z" }, + { url = "https://files.pythonhosted.org/packages/43/44/042cbd7e46f00f45aea36496ca8bdb6b1136c2ec4063875a25286c2ba8fc/pydantic_core-2.50.2-pp311-pypy311_pp73-musllinux_1_1_x86_64.whl", hash = "sha256:cb8d2d7b07cbe2d7488de7e53671f836c4f4a8032dcda079df33dc1b7e2397c0", size = 2492296, upload-time = "2026-10-29T16:34:48.374Z" }, + { url = "https://files.pythonhosted.org/packages/cb/8e/e8aef16e587215a1795dbe991e41006003aef1f1b6f554361f3a6edd585a/pydantic_core-2.50.2-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:7c6e1bd6cadae13958e52897ef020e85c9916a95917149fca463bb0c0421a7c6", size = 2323090, upload-time = "2026-10-29T16:34:50.008Z" }, + { url = "https://files.pythonhosted.org/packages/21/36/d083f973e28c5718f9d9d819c0b8171df1526124e8c3709bd55ddf1d4244/pydantic_core-2.50.2-pp311-pypy311_pp80-macosx_10_12_x86_64.whl", hash = "sha256:f078e276848bc23d1f92f46fc88d5b9cbb824b9acc60d9e07116620e502e16a9", size = 2157909, upload-time = "2026-10-29T16:34:51.579Z" }, + { url = "https://files.pythonhosted.org/packages/0c/4b/e2eb5b51f46411ceb80451a7bf4aee215fd84012eeba22a183b4699006b5/pydantic_core-2.50.2-pp311-pypy311_pp80-macosx_11_0_arm64.whl", hash = "sha256:3435c443da7510a6de1a30c68beae338852a11f0440cc8320ea756a162f38dbe", size = 2075771, upload-time = "2026-10-29T16:34:53.469Z" }, + { url = "https://files.pythonhosted.org/packages/d5/99/e9703785468d1e644f19d602985b722ff97cc8ca67389e2d79f8fb562cfa/pydantic_core-2.50.2-pp311-pypy311_pp80-manylinux_2_28_x86_64.whl", hash = "sha256:b5675a12a7b67063fe3ca187e735b0463cf13fabc10166ae4d4b2f775fd0632d", size = 2265708, upload-time = "2026-10-29T16:34:54.662Z" }, + { url = "https://files.pythonhosted.org/packages/bd/d7/079d3d36aa6ee0333847d968d91ff185837541741d3c58ed0316103309bf/pydantic_core-2.50.2-pp311-pypy311_pp80-win_amd64.whl", hash = "sha256:f5ba7ef10ce82737e173fa95cafa1c8210918f7e653715b2c7a7a31877a74848", size = 2323087, upload-time = "2026-10-29T16:34:56.176Z" }, ] [[package]] @@ -546,6 +598,7 @@ version = "1.4.1.post1" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "pytest" }, + { name = "typing-extensions", marker = "python_full_version < '3.13'" }, ] sdist = { url = "https://files.pythonhosted.org/packages/73/7f/c60a4338420b33453d4f814ac0c930abd399f162b9bdd21af4b9e363037f/pytest_asyncio-1.4.1.post1.tar.gz", hash = "sha256:f582d9ea4a1c082195abe8bd29a1fe106aeb1cd435e3dad2d3bc2749935c36a2", size = 145360, upload-time = "2026-11-01T18:26:03.732Z" } wheels = [ @@ -583,6 +636,7 @@ version = "1.10.0" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "anyio" }, + { name = "typing-extensions", marker = "python_full_version < '3.13'" }, ] sdist = { url = "https://files.pythonhosted.org/packages/48/bb/3d8757f21e9a53d9035c9eb039a777047139a16bfdbedfc7a58241c3d914/starlette-1.10.0.tar.gz", hash = "sha256:b8399098d4c1e3522734f7235dc79b1fc967f96cf139c81e0fa30479e0685f9b", size = 2734356, upload-time = "2026-10-24T15:04:12.342Z" } wheels = [ @@ -713,6 +767,28 @@ version = "2.5.2" source = { registry = "https://pypi.org/simple" } sdist = { url = "https://files.pythonhosted.org/packages/9c/b0/f752d19e1e83ab8bd64aeccfde32ff086aee3ef08520f7340b69a8d0a4d2/wrapt-2.5.2.tar.gz", hash = "sha256:551cb49e88b3722faad780303833bc4fa70685fb1773270fb98b40d39d9fddbf", size = 186066, upload-time = "2026-10-29T23:06:39.868Z" } wheels = [ + { url = "https://files.pythonhosted.org/packages/4d/c2/b4bbaabf73ea9ccc2e322a11455a95d7d9dcae5bbcc6fd836c5f676a082f/wrapt-2.5.2-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:8b240a879405591da10e2d20c2d1ad29b978d40ec37e24801296cfee1d4c04f9", size = 105761, upload-time = "2026-10-29T23:04:28.866Z" }, + { url = "https://files.pythonhosted.org/packages/f7/d4/57db9384ffb339f29b6712cc1d7d4ace29d07670756becf9ad336728ca42/wrapt-2.5.2-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:b632d90ac0d04e3ba8821b19954d6c36ea8f714b75db53c58015025fefccb1ac", size = 105933, upload-time = "2026-10-29T23:04:30.45Z" }, + { url = "https://files.pythonhosted.org/packages/98/00/a0effd5872aed3271b28b4740a71bc2d7406d33b4e03eac01ae099ac8569/wrapt-2.5.2-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:0743950d3dda9940e56f81f5334ba051c4fe2e1421e4e4a4ef8eb8fb86a90894", size = 240286, upload-time = "2026-10-29T23:04:31.855Z" }, + { url = "https://files.pythonhosted.org/packages/69/22/8e9ef3a15115f3cc01f2460aaf9aeb04819704fefd218086642c7182be95/wrapt-2.5.2-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:594c6d10b9cfb951a09f7338531a41d31194e7eee9dee206c0a8992421682719", size = 241793, upload-time = "2026-10-29T23:04:33.501Z" }, + { url = "https://files.pythonhosted.org/packages/15/7f/b2912f3d045fd9a5f30d9d58f3b4df8921c87e902524a32d7eb0e0e315cb/wrapt-2.5.2-cp311-cp311-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:e4362b3b4e4b050b8f1f518e0c71a09f2e938a9f62ee559ea1743a13b3c9e8f1", size = 226781, upload-time = "2026-10-29T23:04:34.862Z" }, + { url = "https://files.pythonhosted.org/packages/ab/06/cdd488014d5010b052fdd9c368d8598accd9eee766d98e698cc8510b364d/wrapt-2.5.2-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:81e685c7662fab9958a852b9c86f3b5b8eee45d047a2766d6c23b63ad1eee423", size = 239441, upload-time = "2026-10-29T23:04:36.296Z" }, + { url = "https://files.pythonhosted.org/packages/dd/b9/6605b2fd612ea1635d0a7cebbdc05cdb59c97a07ee9c418a5f43a49cee53/wrapt-2.5.2-cp311-cp311-musllinux_1_2_riscv64.whl", hash = "sha256:c6b4bd8c662c333518a9aedb35bb9f4f7d1584fbef4bc1507a6c6a47357c628e", size = 224041, upload-time = "2026-10-29T23:04:38.008Z" }, + { url = "https://files.pythonhosted.org/packages/42/9b/6a8acfd407991b50b9bdbaaae5551cc12ba487a8a0973c87793dac621f1f/wrapt-2.5.2-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:7a7efde469ad904b8e05f98c76d63b437f4756c30ec7b9136bef02bdb5d1b14c", size = 229602, upload-time = "2026-10-29T23:04:39.463Z" }, + { url = "https://files.pythonhosted.org/packages/81/6c/9a975e802393c74af9879ca938b298a00fd59074ee90abf4ec4bedcdd109/wrapt-2.5.2-cp311-cp311-win32.whl", hash = "sha256:73d432588d1e0a8fcb88d46ef2733e848ff0c3e14111a0420c77199fd2a8cd30", size = 100856, upload-time = "2026-10-29T23:04:40.884Z" }, + { url = "https://files.pythonhosted.org/packages/46/aa/196ab4e3584e547fcb6c4a622934aae14077c367b86f57a5ab5e76a47203/wrapt-2.5.2-cp311-cp311-win_amd64.whl", hash = "sha256:04703a2a4eea122c3a6b3af89e72bbbaa20779e5c7199c3d06e3fcb6601bc7d4", size = 106052, upload-time = "2026-10-29T23:04:42.232Z" }, + { url = "https://files.pythonhosted.org/packages/e0/5d/7a699446d344bc74bcd607a0cf09087285a253eefc6449048c0df7b5a3e5/wrapt-2.5.2-cp311-cp311-win_arm64.whl", hash = "sha256:53cf804402d49fa2c920a90dfab971a82bca67fb43e54adc7c3b24c054485b4d", size = 103001, upload-time = "2026-10-29T23:04:43.529Z" }, + { url = "https://files.pythonhosted.org/packages/4b/fe/9ccae0a147d0732397f54ff232b1a0da148a4099f17c1b156b9d3e79127e/wrapt-2.5.2-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:bec3b6b1ae2f7ed763fb0ba1776b9b5f11283e6ff40c9cbe3a855ea652c326cf", size = 106628, upload-time = "2026-10-29T23:04:44.962Z" }, + { url = "https://files.pythonhosted.org/packages/d5/ca/a61d994df49fa422abd859e525e04b95ef2888e3818a0f451aa7d4d3527f/wrapt-2.5.2-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:e57d79e3338b3cecee1dd80d6ef8f945f8ea7b92f0d8d5591f840ffa0afc14dc", size = 106264, upload-time = "2026-10-29T23:04:46.307Z" }, + { url = "https://files.pythonhosted.org/packages/dd/26/a6caa9a84ef5db4a273787949cea7ab51f6001d2548768af4c8e3c49debd/wrapt-2.5.2-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:092472b7b1494deef40dac5e9f6295013a9d51b112b5fbc4350f64dc2574e46a", size = 250614, upload-time = "2026-10-29T23:04:47.735Z" }, + { url = "https://files.pythonhosted.org/packages/c7/28/2189571e711ab31cb7f682c739d05f033ae0e83e12eb4d5d21473ca2cd1a/wrapt-2.5.2-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:d108bd98ab2c5ccbf55cf2154e0a73341df930030df2e01ee35d71a44a99d3ad", size = 250770, upload-time = "2026-10-29T23:04:49.183Z" }, + { url = "https://files.pythonhosted.org/packages/80/8e/46a6cc2e8215df7fae292178a355df729547ff9b912686823201d38be269/wrapt-2.5.2-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:858511731d6ede4217960c5fecdb5ecbf90e306dfd93b837395658d61374a498", size = 230031, upload-time = "2026-10-29T23:04:50.641Z" }, + { url = "https://files.pythonhosted.org/packages/97/38/dff531d0125fe880e05fe5fcb89f144d25ffbe95aa9a2c50539eabde7567/wrapt-2.5.2-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:3b6885250b809532a634acd56e360d57c201c1cdc75cbf2b5e106241ece6cbc3", size = 247325, upload-time = "2026-10-29T23:04:52.16Z" }, + { url = "https://files.pythonhosted.org/packages/f0/5b/f4a78df4c52175d53ff095f2f5a54206a2d16e542b1dd2cdcaed901fe432/wrapt-2.5.2-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:c60a5cd8b7b510056f2643d94f1c144533a568ade2891a9dd35733f5e0055777", size = 226900, upload-time = "2026-10-29T23:04:53.559Z" }, + { url = "https://files.pythonhosted.org/packages/20/6f/8eab144c717300f76f1337ba58091f4de5da0f4d772727c9f41135b325c1/wrapt-2.5.2-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:40e03506f09dbf4854fd69848e843dadd9b7fbbdd217837cb27b37fb8f0b5bc3", size = 239017, upload-time = "2026-10-29T23:04:55.293Z" }, + { url = "https://files.pythonhosted.org/packages/59/1a/98e278ef2f8952a34f847a91f75899f6385762b07577c51a5ef82c768dfb/wrapt-2.5.2-cp312-cp312-win32.whl", hash = "sha256:ac00ba7d22d55d3c8d085005ce4942ff3bb118d480f889b5984f1d3454052917", size = 100660, upload-time = "2026-10-29T23:04:56.703Z" }, + { url = "https://files.pythonhosted.org/packages/7d/0a/ab645f8b4c594cac2db49bbc805bff97a9d3f2944061b865f67e0351b6c8/wrapt-2.5.2-cp312-cp312-win_amd64.whl", hash = "sha256:36021ef761856bdbc10d5f3da9a95af93ef60d6acf9c72c8f849937ba2b902aa", size = 106220, upload-time = "2026-10-29T23:04:58.081Z" }, + { url = "https://files.pythonhosted.org/packages/37/1e/232868b68b925ab29ca5acbec4ad54ee42a853fcd8f596bf7e0e0e3850f1/wrapt-2.5.2-cp312-cp312-win_arm64.whl", hash = "sha256:81bdf0bd141d9b1706a0751b2ee068c7afe6be4042712d427b32b3072d5c40b9", size = 103377, upload-time = "2026-10-29T23:04:59.366Z" }, { url = "https://files.pythonhosted.org/packages/1b/7a/38f08a89ca8faa9b788a857f109b5e4cd1f25671a5157e2218072f64aa76/wrapt-2.5.2-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:88f982c2bb306732271aa15cded4002ce28b5d9023de9d11e927da4dcf65e441", size = 106242, upload-time = "2026-10-29T23:05:00.746Z" }, { url = "https://files.pythonhosted.org/packages/e9/8b/2fb9b2522b7e1e7534a72fec0040bbf3d273129ec0a98316e7d37b09aa35/wrapt-2.5.2-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:269321b17467a10997cc6e14793bf1816e6ce488f9711c74b72552466d206739", size = 106366, upload-time = "2026-10-29T23:05:02.191Z" }, { url = "https://files.pythonhosted.org/packages/c2/1e/770d73e0cc82a41602cb2cb184769c28bdbaa9b998944d577a1097c18da3/wrapt-2.5.2-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:8b039b3a296762db1908d6108365225393c4fb33c1dbc5f00aa36f8302eaeaa0", size = 248696, upload-time = "2026-10-29T23:05:03.593Z" }, From 233034089fc2f9cb581a0e63ce9c23c4d03c30a6 Mon Sep 17 00:00:00 2001 From: Erik LaBianca Date: Wed, 11 Nov 2026 17:38:20 -0500 Subject: [PATCH 6/7] Add tag-driven release workflow, wheel build and README quickstart smoke test release.yml runs on v* tags (or a dry-run dispatch that never publishes): CI, build with provenance attestation, fresh-venv smoke on Python 3.11 and 3.13, PyPI trusted publishing, GitHub Release. CI tests Python 3.11/3.12/3.13 and executes the README quickstart against the built wheels. Co-Authored-By: Claude Sonnet 5.5 --- .github/workflows/ci.yml | 21 ++++-- .github/workflows/pages.yml | 1 + .github/workflows/release.yml | 121 ++++++++++++++++++++++++++++++++++ scripts/build_dist.py | 44 +++++++++++++ scripts/release_notes.py | 25 +++++++ scripts/smoke_install.py | 81 +++++++++++++++++++++++ 6 files changed, 289 insertions(+), 4 deletions(-) create mode 100644 .github/workflows/release.yml create mode 100644 scripts/build_dist.py create mode 100644 scripts/release_notes.py create mode 100644 scripts/smoke_install.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 76e4a80..82bf03f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -20,20 +20,26 @@ jobs: check: runs-on: ubuntu-24.04 timeout-minutes: 15 + strategy: + fail-fast: false + matrix: + python: ['3.11', '3.12', '3.13'] steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - uses: astral-sh/setup-uv@v6 - uses: oven-sh/setup-bun@v2 - - run: uv sync --frozen --all-packages --python 3.13 + - run: uv sync --frozen --all-packages --python ${{ matrix.python }} - run: bun install --frozen-lockfile - name: Boundaries, lint, types and unit tests run: uv run python scripts/check.py - - name: Tree size guard - run: python3 scripts/check_tree_size.py + - name: Version consistency and tree size guard + run: | + uv run python scripts/check_versions.py + uv run python scripts/check_tree_size.py - # Native PostgreSQL (pgserver) and browser tests; runs on every PR so the stack is exercised before merge. + # Native PostgreSQL (pgserver), browser scenarios and the README quickstart. native: runs-on: ubuntu-24.04 timeout-minutes: 30 @@ -41,6 +47,9 @@ jobs: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false + - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0 + with: + python-version: '3.13' - uses: astral-sh/setup-uv@v6 - uses: oven-sh/setup-bun@v2 - run: uv sync --frozen --all-packages --python 3.13 @@ -55,6 +64,10 @@ jobs: - run: node node_modules/playwright/cli.js install --with-deps chromium - name: Browser scenarios run: bun run test:native + - name: Build wheels and run the README quickstart against them + run: | + uv run python scripts/build_dist.py + python scripts/smoke_install.py dist - uses: actions/upload-artifact@v4 if: always() with: diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index 20b66bf..0789ba1 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -9,6 +9,7 @@ on: paths: - 'docs/helix/**' - '.github/workflows/pages.yml' + - 'packages/batten/pyproject.toml' workflow_dispatch: permissions: diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..b157715 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,121 @@ +name: Release + +# Runs only on a version tag (v0.1.0a3, ...). A manual dispatch builds and +# smoke-tests but never publishes. +on: + push: + tags: ['v*'] + workflow_dispatch: + inputs: + dry_run: + description: Build and smoke-test only. Publishing happens only from a tag push. + type: boolean + default: true + +permissions: + contents: read + +jobs: + test: + uses: ./.github/workflows/ci.yml + + build: + needs: test + runs-on: ubuntu-24.04 + timeout-minutes: 15 + permissions: + contents: read + id-token: write + attestations: write + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - name: Publishing needs a tag + if: github.ref_type != 'tag' && inputs.dry_run == false + run: | + echo "Publishing only happens from a version tag push; re-run with dry_run." >&2 + exit 1 + - uses: astral-sh/setup-uv@v6 + - uses: oven-sh/setup-bun@v2 + - run: uv sync --frozen --all-packages --python 3.13 + - run: bun install --frozen-lockfile + - name: Tag matches the one workspace version + run: | + if [ "${GITHUB_REF_TYPE}" = tag ]; then + uv run python scripts/check_versions.py "${GITHUB_REF_NAME}" + else + uv run python scripts/check_versions.py + fi + - run: uv run python scripts/build_dist.py + - uses: actions/attest-build-provenance@v2 + if: github.ref_type == 'tag' + with: + subject-path: dist/* + - uses: actions/upload-artifact@v4 + with: + name: dist + path: dist + if-no-files-found: error + + smoke: + needs: build + runs-on: ubuntu-24.04 + timeout-minutes: 20 + strategy: + fail-fast: false + matrix: + python: ['3.11', '3.13'] + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0 + with: + python-version: ${{ matrix.python }} + - uses: actions/download-artifact@v4 + with: + name: dist + path: dist + - name: Fresh-venv install of the built wheels and the README quickstart + run: python scripts/smoke_install.py dist + + publish: + if: github.event_name == 'push' && github.ref_type == 'tag' + needs: smoke + runs-on: ubuntu-24.04 + environment: + name: pypi + url: https://pypi.org/project/novirhyza-batten/ + permissions: + id-token: write + steps: + - uses: actions/download-artifact@v4 + with: + name: dist + path: dist + - run: rm dist/SHA256SUMS + - uses: pypa/gh-action-pypi-publish@release/v1 + with: + packages-dir: dist/ + + github-release: + needs: publish + runs-on: ubuntu-24.04 + permissions: + contents: write + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: actions/download-artifact@v4 + with: + name: dist + path: dist + - name: Create the GitHub Release + env: + GH_TOKEN: ${{ github.token }} + run: | + python3 scripts/release_notes.py "${GITHUB_REF_NAME#v}" > notes.md + gh release create "${GITHUB_REF_NAME}" dist/* --title "Batten ${GITHUB_REF_NAME}" \ + --notes-file notes.md --prerelease --verify-tag diff --git a/scripts/build_dist.py b/scripts/build_dist.py new file mode 100644 index 0000000..8c654e0 --- /dev/null +++ b/scripts/build_dist.py @@ -0,0 +1,44 @@ +"""Build wheels and sdists for every distribution into dist/, with SHA256SUMS.""" + +from __future__ import annotations + +import hashlib +import shutil +import subprocess +import sys +from pathlib import Path + +from check_versions import PROJECTS + +APP = "examples/approval-desk" + + +def main() -> None: + root = Path(__file__).resolve().parents[1] + dist = root / "dist" + shutil.rmtree(dist, ignore_errors=True) + dist.mkdir() + subprocess.run( + [sys.executable, "scripts/prepare_approval.py", "--assets-only"], + cwd=root, + check=True, + ) + for project in PROJECTS: + # The app wheel force-includes generated web assets, so it has no sdist. + kinds = ["--wheel"] if project == APP else ["--sdist", "--wheel"] + subprocess.run( + ["uv", "build", *kinds, "--out-dir", str(dist), str(root / project)], + cwd=root, + check=True, + ) + lines = [ + f"{hashlib.sha256(path.read_bytes()).hexdigest()} {path.name}" + for path in sorted(dist.iterdir()) + if path.suffix == ".whl" or path.name.endswith(".tar.gz") + ] + (dist / "SHA256SUMS").write_text("\n".join(lines) + "\n") + print("\n".join(lines)) + + +if __name__ == "__main__": + main() diff --git a/scripts/release_notes.py b/scripts/release_notes.py new file mode 100644 index 0000000..5a43b8c --- /dev/null +++ b/scripts/release_notes.py @@ -0,0 +1,25 @@ +"""Print the CHANGELOG.md section for one version (used for GitHub Release notes).""" + +from __future__ import annotations + +import re +import sys +from pathlib import Path + + +def section(changelog: str, version: str) -> str: + match = re.search( + rf"^## {re.escape(version)}\b.*?\n(.*?)(?=^## |\Z)", changelog, re.S | re.M + ) + if match is None: + raise SystemExit(f"CHANGELOG.md has no section for {version}") + return match.group(1).strip() + "\n" + + +def main() -> None: + root = Path(__file__).resolve().parents[1] + sys.stdout.write(section((root / "CHANGELOG.md").read_text(), sys.argv[1])) + + +if __name__ == "__main__": + main() diff --git a/scripts/smoke_install.py b/scripts/smoke_install.py new file mode 100644 index 0000000..832bc76 --- /dev/null +++ b/scripts/smoke_install.py @@ -0,0 +1,81 @@ +"""Run the README quickstart in a fresh virtual environment against built wheels. + +Usage: smoke_install.py DIST_DIR + +The quickstart block between the `quickstart` markers in README.md is executed +verbatim, with the wheels in DIST_DIR made visible to pip. The `serve` command is +started in the background and its registry page is fetched. +""" + +from __future__ import annotations + +import re +import subprocess +import sys +import tempfile +import time +import urllib.request +from pathlib import Path + +PORT = 8820 + + +def quickstart(readme: Path) -> list[str]: + match = re.search( + r"\s*```sh\n(.*?)```\s*", + readme.read_text(), + re.S, + ) + if match is None: + raise SystemExit("README.md has no quickstart block") + return [ + line + for line in match.group(1).splitlines() + if line.strip() and not line.startswith("#") + ] + + +def script(lines: list[str], dist: Path) -> str: + body = [f"export PIP_FIND_LINKS={dist}"] + # `exec` makes the server the process we started, so terminate() stops it. + body += [ + "exec " + line if line.startswith("batten-approval serve") else line + for line in lines + ] + return "\n".join(["set -euo pipefail", *body]) + + +def fetch_registry(process: subprocess.Popen[bytes]) -> str: + deadline = time.monotonic() + 300 + while time.monotonic() < deadline: + if process.poll() is not None: + raise SystemExit( + f"quickstart exited early with status {process.returncode}" + ) + try: + with urllib.request.urlopen(f"http://127.0.0.1:{PORT}/", timeout=5) as page: + return page.read().decode() + except OSError: + time.sleep(1) + raise SystemExit("approval desk did not answer on the quickstart port") + + +def main() -> None: + root = Path(__file__).resolve().parents[1] + dist = Path(sys.argv[1]).resolve() + lines = quickstart(root / "README.md") + if not lines or not lines[-1].startswith("batten-approval serve"): + raise SystemExit("quickstart must end with batten-approval serve") + with tempfile.TemporaryDirectory() as work: + process = subprocess.Popen(["bash", "-c", script(lines, dist)], cwd=work) + try: + if "Approval desk" not in fetch_registry(process): + raise SystemExit("registry page does not list the approval desk") + print("quickstart OK: registry lists the approval desk") + finally: + process.terminate() + process.wait(timeout=60) + + +if __name__ == "__main__": + main() From 5e05895a32cc391f27582c215249145524960391 Mon Sep 17 00:00:00 2001 From: Erik LaBianca Date: Wed, 11 Nov 2026 17:38:20 -0500 Subject: [PATCH 7/7] Rewrite README, add CHANGELOG, short AGENTS, version-stamped microsite Co-Authored-By: Claude Sonnet 5.5 --- AGENTS.md | 8 +- CHANGELOG.md | 45 ++++++++++ README.md | 83 ++++++++++++------- .../ADR-003-platform-wheel-distribution.md | 5 ++ .../guide/developer/example-approval-desk.md | 4 +- docs/helix/guide/developer/index.md | 4 +- docs/helix/site/README.md | 65 ++++----------- docs/helix/site/build.py | 6 +- docs/helix/site/verify.py | 4 +- justfile | 5 ++ 10 files changed, 139 insertions(+), 90 deletions(-) create mode 100644 CHANGELOG.md diff --git a/AGENTS.md b/AGENTS.md index 660f8d3..e87e605 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,8 +1,10 @@ # Working in Batten Batten is an application SDK: a UMF/Weft/PostgreSQL-backed local host, an ASGI -registry and an object store. Packages live in `packages/`, the example app in -`examples/approval-desk`. +registry and an object store. Packages: `packages/batten` (contracts, runtime, +tables, asgi), `packages/batten-storage`, `packages/batten-local` (local host and +`umf_postgres`); example app in `examples/approval-desk`. One version for all, +checked by `scripts/check_versions.py`; releases are `v*` tags (`release.yml`). - Setup and checks: `uv sync --frozen --all-packages`, `bun install --frozen-lockfile`, `uv run python scripts/check.py` (boundaries, ruff, pyright, oxlint, tsc, pytest). @@ -14,6 +16,8 @@ registry and an object store. Packages live in `packages/`, the example app in packages must not import native or platform modules. Keep new public names in `public-api.json`. - Use fabricated data only; no credentials. MIT OR Apache-2.0. +- `README.md` has the quickstart that `scripts/smoke_install.py` executes in CI; keep + its commands and that script in step. - CI is the gate. Do not commit evidence, receipts, verification JSON or qualification packets. `ROADMAP.md` lists what is not built; do not describe it as supported. diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..30997a3 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,45 @@ +# Changelog + +All distributions share one version and one `v*` tag. Versions before 0.1.0a3 were +separate GitHub prereleases (`runtime-v*`, `storage-v*`). + +## 0.1.0a3 + +Unreleased. First release from PyPI. + +- One version for every distribution; one `v*` tag; tag-driven release workflow with + trusted publishing to PyPI, a fresh-venv install smoke test and a GitHub Release. +- Seven wheels became three plus the example: `novirhyza-batten` (contracts, runtime, + tables, ASGI; the `batten.*` import paths are unchanged), `novirhyza-batten-storage`, + `novirhyza-batten-local` (local host and UMF/Weft provider) and + `novirhyza-batten-approval-desk`. The old `novirhyza-batten-{contracts,runtime,tables,asgi,umf-postgres}` + names were never published to PyPI. +- Python 3.11 to 3.13 supported (tested in CI); the workspace was 3.13 only. +- Dependency ranges instead of exact pins: `umf-codegen>=0.10.8,<0.11`, + `umf-weft>=0.4.57,<0.5`, `umf-access>=0.1.0.dev8,<0.2`, `psycopg>=3.3.7,<4`, + `pgserver-pg18>=18.6.1,<19` (still installed from its GitHub release until it is + on PyPI). +- Removed the unimplemented reference-app specifications, evidence and verification + files, and the ratchet gates; added unit tests for contracts, runtime, ASGI, the + UMF provider and the local host; CI runs on Linux for every pull request. +- The approval UMF model now lives in `examples/approval-desk/model/`. + +## 0.1.0a2 (runtime-v0.1.0a2, 2026-11-03) + +- UMF codegen and core 0.10.8; Weft SQL compiler moved from `weft-sql` 0.4.54 to + `umf-weft` 0.4.57; psycopg 3.3.7. +- TypeScript 7 and Oxlint for the browser tooling; the same two Playwright scenarios. + +## 0.1.0a1 (runtime-v0.1.0a1, 2026-11-02) + +- First runnable local application: approval desk and a visual app registry, with + contracts, runtime, table port, UMF/PostgreSQL adapter, ASGI transport and local + host as separate wheels. +- Submit, edit, approve and reject requests through UMF tables and Weft on PostgreSQL 18; + a lost mutation response is recovered from its original native receipt. + +## storage 0.1.0a1 (storage-v0.1.0a1) + +- `novirhyza-batten-storage`: portable async object storage protocols and a managed + local POSIX provider (scoped writes, pinned reads and ranges, conditional + replacement, bounded listing, multipart uploads). diff --git a/README.md b/README.md index 8687bc1..30c1178 100644 --- a/README.md +++ b/README.md @@ -1,48 +1,69 @@ # Batten -Batten is an application software development kit (SDK) in the Novirhyza family. -Authors define native data structures, operations, workflows, jobs, and interfaces. -A public host contract handles admission, execution, integration, and delivery -through explicitly bounded platform modules. +Batten is a small Python application SDK from Novirhyza. You declare tables and +operations once; Batten hosts them behind a public operation API with identity, +audit capture, bounded concurrency and an ASGI transport, on top of UMF and Weft +tables stored in PostgreSQL 18. -The proposed portable core has no ontology-specific capability. An ontology -provider is one Batten module, backed by Arras. UMF, Weft, Tether, and other -platform libraries are dependencies supplied by the platform. +**Status: alpha (0.1.0a3).** What CI tests today, on Linux with Python 3.11, 3.12 +and 3.13: the host runtime, the ASGI registry and operation endpoints, the local +object store, the UMF table provider (compiling the approval model with released +`umf-codegen`), and the example approval desk end to end on a real pgserver +PostgreSQL 18 cluster with Playwright browser scenarios (Python 3.13). -Visit the [Batten microsite](https://documentdrivendx.github.io/batten/). +Batten ships **standalone** for now. It depends on UMF, Weft and pgserver only; +there is no Arras, Lintel or Truss integration yet (see the [roadmap](ROADMAP.md)). +Local identities are loopback development stubs, not production authentication. -Explore the [microsite source and local preview instructions](docs/helix/site/README.md) -or read the [application overview](docs/helix/guide/developer/index.md). -The microsite explains the design. The first source implementation is the optional -[local object-storage package](packages/batten-storage/README.md); the complete -application runtime remains in design. +## Install and run the example -Dual licensed under [MIT](LICENSE-MIT) OR [Apache-2.0](LICENSE-APACHE). -Copyright Synaptiq. +Needs Python 3.11 to 3.13 on Linux or macOS arm64. `pgserver-pg18` is not on PyPI +yet, so the install points pip at its GitHub release. + + +```sh +python -m venv .venv +. .venv/bin/activate +pip install --pre --find-links https://github.com/DocumentDrivenDX/pgserver/releases/expanded_assets/pg18.6-pgv0.8.6-r2 novirhyza-batten-approval-desk +batten-approval init +batten-approval call --actor alex --operation list +batten-approval serve +``` + + +`init` creates a fabricated local PostgreSQL 18 cluster in `.local/approval`; +`call` runs one operation as Alex; `serve` starts the app. Open + and choose **Approval desk**. CI runs these exact commands +against the built wheels before every release. +## Packages -Development uses Python 3.13, Node 26.13.0, Bun 1.4.4 and the locked uv 0.13.7 -workspace. Oxlint and TypeScript 7 supply the browser quality checks: +All distributions share one version and one `v*` release tag. + +| PyPI name | Import | What it is | +|---|---|---| +| `novirhyza-batten` | `batten.contracts`, `batten.runtime`, `batten.tables`, `batten.asgi` | Operation contracts, host runtime, table port, ASGI transport and app registry | +| `novirhyza-batten-storage` | `batten.storage` | Portable object storage and a managed local filesystem store; no dependencies | +| `novirhyza-batten-local` | `batten.hosting.local`, `batten.umf_postgres` | Local host and UMF/Weft table provider on pgserver PostgreSQL 18 | +| `novirhyza-batten-approval-desk` | `approval_desk` | The example app (`batten-approval` command) | + +## Development ```sh uv sync --frozen --all-packages bun install --frozen-lockfile -uv run python scripts/check.py +uv run python scripts/check.py # boundaries, ruff, pyright, oxlint, tsc, pytest +uv run python scripts/prepare_approval.py && uv run pytest -m integration && bun run test:native ``` -`just test` runs both the Python suite and the two JavaScript Playwright scenarios. -The same quality command runs in CI; `just check` is an equivalent entry point. `just lint` -provides the configured local pre-commit check. Product storage has no third-party -runtime dependencies. Quality tools remain outside its wheel. - +The last line needs native PostgreSQL (pgserver) and a Playwright browser; it runs +in CI on every pull request. See [AGENTS.md](AGENTS.md) for the layout and rules. -What is not built is listed in the [roadmap](ROADMAP.md). +## More -## Run the first reference application +[Microsite](https://documentdrivendx.github.io/batten/) · +[Changelog](CHANGELOG.md) · [Roadmap](ROADMAP.md) · +[Design records](docs/helix/README.md) · [Object storage](packages/batten-storage/README.md) -The [approval desk](examples/approval-desk/README.md) uses original UMF tables and -Weft on a dedicated PostgreSQL 18 pgserver, a modular local Batten host and an -authored TypeScript UI. Start with `just approval-prepare`, explicitly initialize -with `just approval-init`, then run `just approval`. The installed app opens at -. Browser tests run with `just approval-test`; -`just check` stays independent of database processes. +Dual licensed under [MIT](LICENSE-MIT) OR [Apache-2.0](LICENSE-APACHE). +Copyright Synaptiq. diff --git a/docs/helix/02-design/adr/ADR-003-platform-wheel-distribution.md b/docs/helix/02-design/adr/ADR-003-platform-wheel-distribution.md index a6b7da0..9f47cd1 100644 --- a/docs/helix/02-design/adr/ADR-003-platform-wheel-distribution.md +++ b/docs/helix/02-design/adr/ADR-003-platform-wheel-distribution.md @@ -14,6 +14,11 @@ ddx: # ADR-003: Distribute platform modules separately +> As of 0.1.0a3 the contracts, runtime, tables and ASGI modules ship in one wheel +> (`novirhyza-batten`) and the local host with the UMF/PostgreSQL provider in another +> (`novirhyza-batten-local`). Import paths are unchanged and the import-boundary check +> still enforces the separation. The table below is the original plan. + ## Problem Optional dependencies in one wheel can keep installation light, but the wheel diff --git a/docs/helix/guide/developer/example-approval-desk.md b/docs/helix/guide/developer/example-approval-desk.md index 699e193..b0c7768 100644 --- a/docs/helix/guide/developer/example-approval-desk.md +++ b/docs/helix/guide/developer/example-approval-desk.md @@ -7,7 +7,7 @@ Runnable local preview. Follow this journey as a requester and independent approver. Use fabricated data throughout. -[Prepare and start the local app](https://github.com/DocumentDrivenDX/batten/blob/main/examples/approval-desk/README.md) before following these steps. The preview uses loopback development identities and PostgreSQL 18; production authentication and broader fleet qualification remain separate. +[Install and start the local app](https://github.com/DocumentDrivenDX/batten/blob/main/README.md#install-and-run-the-example) before following these steps. The preview uses loopback development identities and PostgreSQL 18; production authentication and broader fleet qualification remain separate. ## Capabilities in this journey @@ -15,7 +15,7 @@ tables, actions. These tags describe requested integration boundaries. ## 1. Open the local registry -Follow the run instructions to prepare the exact Python 3.13 cohort and explicitly initialize a new fabricated database. Start the host, open its root registry and choose Approval desk. +Follow the install instructions, then explicitly initialize a new fabricated database with `batten-approval init`. Start the host with `batten-approval serve`, open its root registry and choose Approval desk. ## 2. Submit as Alex diff --git a/docs/helix/guide/developer/index.md b/docs/helix/guide/developer/index.md index 9fb7437..12ef862 100644 --- a/docs/helix/guide/developer/index.md +++ b/docs/helix/guide/developer/index.md @@ -51,9 +51,9 @@ A provider must satisfy the required interface and exact compatibility checks. A ## Explore the design -The local runtime preview delivers an approval desk and a visual application registry, with native UMF/Weft persistence on PostgreSQL 18. Separate wheels package the contracts, runtime, table port, native adapter, ASGI transport, local host and app. Qualification is bounded to the recorded cohort and local development identities; the complete fleet remains a design goal. Optional local object storage has its own release. The interactive explorer illustrates the broader contracts and makes no service calls. +The local runtime preview delivers an approval desk and a visual application registry, with native UMF/Weft persistence on PostgreSQL 18. Four wheels package the runtime and ASGI transport, the optional object store, the local UMF/Weft host and the example app; they share one version. Local identities are development stubs, and the complete fleet remains a design goal. The interactive explorer illustrates the broader contracts and makes no service calls. -[Get the runtime preview](https://github.com/DocumentDrivenDX/batten/releases/tag/runtime-v0.1.0a2) or [read the run instructions](https://github.com/DocumentDrivenDX/batten/blob/main/examples/approval-desk/README.md). +[Install the example](https://github.com/DocumentDrivenDX/batten/blob/main/README.md#install-and-run-the-example) or [read the example README](https://github.com/DocumentDrivenDX/batten/blob/main/examples/approval-desk/README.md). [Compose an application](composition.md), [choose a host](hosting.md), or read the [architecture](architecture.md). diff --git a/docs/helix/site/README.md b/docs/helix/site/README.md index ff72789..d7bc94d 100644 --- a/docs/helix/site/README.md +++ b/docs/helix/site/README.md @@ -1,65 +1,28 @@ # Batten microsite -The microsite projects the vision, requirements and design into source-stamped -reader explanations. The local runtime preview has separate release assets and bounded native/browser evidence. +The microsite turns the design guide pages in `docs/helix/guide/developer/` into a +static site. The home page is stamped with the package version from +`packages/batten/pyproject.toml`. -Build from the repository root with Python 3.13 and its standard library: +From the repository root, with Python 3.11 or later and its standard library: ```sh -python3.13 docs/helix/site/build.py -python3.13 -m http.server 8814 --bind 127.0.0.1 --directory docs/helix/site/dist +python3 docs/helix/site/build.py +python3 docs/helix/site/verify.py +python3 -m http.server 8814 --bind 127.0.0.1 --directory docs/helix/site/dist ``` Open `http://127.0.0.1:8814/`. Generated output lives in `dist/`, which Git ignores. All links and assets are relative so the output can be served beneath a project prefix. No runtime CDN, backend, analytics or external font is required. +`verify.py` checks generated routes, local assets, fragments, social metadata and +the version stamp. Do not hand-edit generated HTML. -Written source pages live in `docs/helix/guide/developer/`. Their HELIX provenance -headers bind them to source content digests. The builder rejects stale sources. -An independent reader evaluates explanations before documentor records a review. - -With HELIX's documentor available, run: - -```sh -documentor check-pages docs/helix/guide --root . --strict-prose -documentor check --root . -``` - -The installed HELIX plugin owns the publishing catalog. No catalog is vendored. -The custom static assembly uses `build.py`; do not hand-edit generated HTML. -The site's module/host controls illustrate the design and make no service calls. +Each guide page lists the design documents it draws on in `helix:source` comments; +the build fails if a cited file is missing. The module/host controls on the home +page illustrate the design and make no service calls. ## GitHub Pages -The public site is https://documentdrivendx.github.io/batten/. The repository -uses GitHub Actions as its Pages publishing source. - -The Pages workflow builds with Python 3.13 and verifies generated routes, local -assets, fragments and project-prefix-safe links. Official actions are pinned by -commit SHA. Pull requests build without deploying; successful pushes to `main` -publish through the `github-pages` environment using the job-scoped Pages/OIDC -permissions. No deployment credential is stored in the repository. - -Run the publication check locally after building: - -```sh -python3.13 docs/helix/site/verify.py -``` - -To retry publication, rerun the Pages workflow for the reviewed `main` revision. -To restore an earlier site, revert the reviewed source change and let the same -workflow rebuild it. A release archive also preserves its exact static output. -The standalone build command itself does not modify hosting configuration. - -## Slack and social previews - -Every route emits static Open Graph and Twitter card metadata, a canonical public -URL and an absolute HTTPS image URL. Slack can crawl these without JavaScript. -The branded `assets/social-preview.png` is a 1200 × 630 PNG; its editable artwork -is `assets/social-preview.svg`. Regenerate the PNG with Chromium at that viewport -after changing the artwork. The publication checker validates metadata consistency, -per-route URLs, image signature and dimensions before deployment. - -After publication, fetch the page as Slackbot and check that the public PNG returns -`image/png`. A real Slack workspace render remains separate from crawler checks; -Slack may cache previews for previously shared URLs. +The public site is https://documentdrivendx.github.io/batten/. The Pages workflow +builds and verifies the site on pull requests and publishes it on pushes to `main`. diff --git a/docs/helix/site/build.py b/docs/helix/site/build.py index 93ebe4c..c2d21bd 100644 --- a/docs/helix/site/build.py +++ b/docs/helix/site/build.py @@ -4,12 +4,16 @@ import html import re import shutil +import tomllib from pathlib import Path ROOT = Path(__file__).resolve().parents[3] SITE = Path(__file__).resolve().parent GUIDE = ROOT / "docs/helix/guide/developer" OUT = SITE / "dist" +VERSION = tomllib.loads((ROOT / "packages/batten/pyproject.toml").read_text())[ + "project" +]["version"] REPO = "https://github.com/DocumentDrivenDX/batten" PUBLIC_URL = "https://documentdrivendx.github.io/batten/" DESCRIPTION = "Batten: declarative AI applications with explicit platform choices. Try the local approval desk preview, or explore the architecture for governed fleets." @@ -163,7 +167,7 @@ def home(body: str, provenance: str) -> str:
      UMF / APPLICATION

      review_queue

      modelsReview
      actionsApproveReview
      agentsRecommendReview
      interfaceReview screen
      explicit capability bindings
      {MARK}batten core+ selected modules
      LocalStandaloneEmbedded

      Same application intent. Different host bindings.

      {strip}
      -

      AVAILABLE NOW / 0.1.0a2

      Run the local approval desk.

      Submit, revise and independently approve requests through native UMF and Weft on PostgreSQL 18. Open the visual app registry and follow decisions through durable receipts and local telemetry.

      Python 3.13 · Local development identities · Fabricated data. This preview qualifies the recorded local cohort; production identity and the complete fleet remain separate work.

      +

      ALPHA / {VERSION}

      Run the local approval desk.

      Submit, revise and independently approve requests through native UMF and Weft on PostgreSQL 18. Open the visual app registry and follow decisions through durable receipts and local telemetry.

      Python 3.11 to 3.13 · Local development identities · Fabricated data. Batten ships standalone: it depends on UMF, Weft and pgserver only. Production identity and the broader fleet remain roadmap work.

      A DELIBERATE FOUNDATION

      A small core.
      Room to compose.

      01 / NATIVE MEANING

      Build on the platform.

      Use UMF models and actions, Weft queries, Arras ontology and Tether agents through their public boundaries.

      02 / EXPLICIT CAPABILITIES

      Bring what the app needs.

      Select modules independently. Keep optional platform dependencies out of applications that do not use them.

      03 / GOVERNED FLEETS

      Operate a shared fleet.

      Share declarative services with explicit identity, limits and lifecycle. Qualify runtime upgrades against application evidence.

      {explorer()}

      GOOD INTERFACES, BY DESIGN

      Make room
      for the experience.

      ux-builder owns the design workflow, blueprint, components and themes. Batten’s proposed binding connects that experience to native models and governed operations.

      Explore the UI boundary ↗
      Review workspaceILLUSTRATION
      Review queue →ActivitySettings
      REVIEW / FABRICATED EXAMPLE

      A decision, with context.

      ✧ Recommendation

      Review the proposed change before approval.

      Declared actionApproveReviewAuthorityChecked by the host
      Review and confirm ↗
      diff --git a/docs/helix/site/verify.py b/docs/helix/site/verify.py index 1238388..0ba4621 100644 --- a/docs/helix/site/verify.py +++ b/docs/helix/site/verify.py @@ -5,7 +5,7 @@ from html.parser import HTMLParser from urllib.parse import unquote, urlsplit -from build import OUT, PAGES, PUBLIC_URL +from build import OUT, PAGES, PUBLIC_URL, VERSION class Page(HTMLParser): @@ -97,6 +97,8 @@ def verify() -> None: raise ValueError(f"Missing primary landmark or unique heading: {name}") verify_links(name, page, pages) verify_social(name, page) + if f"ALPHA / {VERSION}" not in (OUT / "index.html").read_text(): + raise ValueError("Home page is not stamped with the release version") if not (OUT / ".nojekyll").is_file(): raise ValueError("Missing Pages static publication marker") if any(p.is_symlink() for p in OUT.rglob("*")): diff --git a/justfile b/justfile index 1965190..e02bdc6 100644 --- a/justfile +++ b/justfile @@ -25,3 +25,8 @@ approval-test: # Rebuild only the app against the already prepared platform cohort. approval-refresh: uv run python scripts/prepare_approval.py --app-only + +# Build wheels/sdists into dist/ and run the README quickstart against them. +dist: + uv run python scripts/build_dist.py + python3 scripts/smoke_install.py dist