Publish the VDMT white paper and Markdown-first theory website

.github/workflows/publication.yml

@@ -0,0 +1,88 @@
+name: Publication
+
+on:
+  push:
+    branches: [main, vdmt-formal-specification]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: publication-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - name: Archive reviewed source
+        run: git archive --format=zip --prefix=vdmt/ HEAD > vdmt-source.zip
+      - name: Retain source edition
+        uses: actions/upload-artifact@v7.0.1
+        with:
+          name: vdmt-source
+          path: vdmt-source.zip
+          retention-days: 14
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+          cache: pip
+      - name: Install publication dependencies
+        run: python -m pip install -r requirements.txt -r requirements-dev.txt
+      - name: Test abstract contracts and publication tooling
+        run: python -m unittest discover -s tests -v
+      - name: Run the complete reference demonstration
+        run: |
+          mkdir -p validation
+          python examples/demo.py > validation/reference-demo.json
+      - name: Acquire versioned browser assets
+        run: python scripts/vendor.py
+      - name: Build Markdown-first publication
+        run: python scripts/build.py
+      - name: Archive built publication for review
+        run: python scripts/archive.py
+      - name: Validate every article and Markdown alternate
+        run: python scripts/check_site.py
+      - name: Install browser
+        run: python -m playwright install --with-deps chromium
+      - name: Check rendering, navigation, math, and theme behavior
+        run: python scripts/browser_check.py
+      - name: Retain publication and review evidence
+        if: always()
+        uses: actions/upload-artifact@v7.0.1
+        with:
+          name: vdmt-publication
+          path: |
+            vdmt-site.zip
+            validation/
+            vendor/manifest.json
+          if-no-files-found: warn
+          retention-days: 14
+      - name: Prepare Pages artifact
+        if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+  deploy:
+    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+      - name: Deploy checked publication
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.py[cod]
+site/
+vendor/
+validation/
+vdmt-source.zip
+vdmt-site.zip
+.DS_Store

AUTHORS.md

@@ -0,0 +1,7 @@
+# Authorship and contribution record
+
+**Llewellyn van der Merwe** — originator of the architecture, author of the originating JCB implementation, source of the practical account and independent-development testimony, and intended author/publisher of the VDMT research exposition through Vast Development Method.
+
+This 2026 documentation edition and its original reference implementation were prepared with AI assistance for the originator's review. The publication does not imply that a degree has been awarded, that an institution has endorsed it, or that independent peer review has been completed.
+
+Earlier mathematical and architectural work is credited in `DOCS/foundations/related-work.md` and `DOCS/reference/bibliography.md`. JCB contributors retain attribution for their work. Future contributors should be recorded with their actual contributions rather than silently incorporated into a sole-authorship claim.

CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 — 15 September 2026
+
+Initial formal documentation edition of Vast Development Method Theory. Separates the language-independent framework from the pinned JCB case study; defines contextual closure, scoped derivation, occurrence identity, staged materialization, and partial editorial reconciliation; supplies conditional propositions, counterexamples, a reference model, conformance tests, related work, and an experimental program.
+
+Adds a Markdown-first publication for theory.vdm.io with per-article Markdown alternates, a complete research corpus, machine-readable manifests, light/dark/system themes, search, mathematical rendering, diagrams, and a gated GitHub Pages workflow.
+
+Historical provenance is recorded separately: the originating public JCB implementation is dated 30 January 2016. This changelog does not backdate the 2026 manuscript or claim every modern feature existed at the root commit.

CITATION.cff

@@ -0,0 +1,30 @@
+cff-version: 1.2.0
+message: "Please cite the white paper when discussing VDMT; cite a pinned source revision for implementation claims."
+title: "Vast Development Method Theory: Contextual Recollection, Staged Synthesis, and Persistent Editorial Reconciliation"
+authors:
+  - family-names: "van der Merwe"
+    given-names: "Llewellyn"
+version: 0.1.0
+date-released: 2026-09-15
+url: "https://theory.vdm.io"
+repository-code: "https://github.com/vast-development-method/theory"
+license:
+  - CC-BY-4.0
+  - MIT
+keywords:
+  - contextual closure
+  - staged synthesis
+  - round-trip engineering
+  - compiler architecture
+  - scoped memory
+preferred-citation:
+  type: report
+  title: "Vast Development Method Theory: Contextual Recollection, Staged Synthesis, and Persistent Editorial Reconciliation"
+  authors:
+    - family-names: "van der Merwe"
+      given-names: "Llewellyn"
+  year: 2026
+  version: 0.1.0
+  institution:
+    name: "Vast Development Method"
+  url: "https://theory.vdm.io"

CONTRIBUTING.md

@@ -0,0 +1,27 @@
+# Contributing to VDMT
+
+The paper welcomes criticism, counterexamples, independent implementations, source corrections, and reproducible measurements. Agreement with the author's hypotheses is not a condition of contribution.
+
+## One article, one source
+
+Write each article in `DOCS/` as UTF-8 Markdown. Include YAML front matter with `title`, `description`, `section`, `order`, and `evidence`. Give the page one H1, then descriptive H2/H3 sections. Use ordinary relative `.md` links, fenced code, and `$...$` / `$$...$$` mathematics. Do not maintain separate HTML prose or separate hand-edited Markdown exports. The build creates both from the same source and checks their correspondence.
+
+A new nuance should receive a focused article when it has its own definitions, assumptions, example, failure conditions, or evidence. Link it to its prerequisites and implications. Do not split a sentence into several pages merely to inflate the count.
+
+## Evidence discipline
+
+Label claims using the taxonomy in `DOCS/foundations/epistemic-status.md`. Source observations require a repository revision, path, relevant method or line range, and an explanation of what was inspected. Experiments require input and environment descriptions and a procedure that another researcher can run. Propositions require all assumptions and an argument; a test does not become a proof by passing. Cite prior work at the point of comparison.
+
+Do not silently promote a proposed feature to an observed JCB property. Do not equate the historical public implementation date with the date of this manuscript. Do not use a marketing claim or a generated line count as evidence of cognitive optimality.
+
+## Review workflow
+
+Create a branch from `main`. Make focused commits, run the repository tests, build the publication, and open a pull request explaining substantive changes. A formal change should state which definitions and propositions depend on it. A source correction should state whether it affects an implementation observation or the abstract specification. A historical correction must retain a transparent record of the prior wording.
+
+PRs are checked but never deployed to the public domain. Only an approved merge to `main` publishes. Large changes to definitions should increment the specification version and explain compatibility.
+
+## Rights and attribution
+
+Contribute only material you have the right to share. Contributions to original paper text and diagrams are offered under CC BY 4.0; original software contributions under MIT. Contributors retain their own copyright unless separately agreed. Preserve upstream rights for quotations and dependencies. Do not add invented author identities, institutional affiliations, degrees, ORCID identifiers, DOIs, or publication dates.
+
+The theory's originator is Llewellyn van der Merwe. Maintain that attribution without erasing the contributions of collaborators or the priority of related published work.

DOCS/404.md

@@ -0,0 +1,13 @@
+---
+title: Page not found
+description: Return to the VDMT reading guide or search the publication for the intended article.
+section: Reference
+order: 999
+listed: false
+evidence: Publication navigation
+---
+# Page not found
+
+The requested article is not available at this address. Return to the [publication home](index.md), use the [reading guide](reading-guide.md), or search by concept in the navigation.
+
+Every published article has a corresponding Markdown source. A missing or moved article should not be replaced with a guessed scientific claim. The [publication guide](reference/publication.md) explains the stable HTML and Markdown URL structure.

DOCS/applications/ai-memory.md

@@ -0,0 +1,44 @@
+---
+title: Application to AI context and memory
+description: Scoped external memory, iterative retrieval, attributed interpretations, and authorized corrections.
+section: Applications
+order: 83
+evidence: Proposed application and empirical hypotheses
+---
+# Application to AI context and memory
+
+## A structured memory layer, not a claim about model internals
+
+VDMT can be applied to the external context orchestration around an AI system. A task induces retrieval requests; retrieved evidence reveals additional dependencies; claims are stored with provenance and scope; task-specific representations are assembled; and authorized human corrections become persistent input for later tasks.
+
+This is a proposed application of the framework. It does not establish that a language model internally implements VDMT, or that a registry can substitute for learned reasoning.
+
+## Separate evidence from generated interpretation
+
+A retrieved statement, a verified observation, a model inference, and a human correction should have distinct types. A fluent generated summary must not be promoted to authoritative source merely because it has been stored and retrieved again.
+
+A context key may include user or tenant, task, source revision, time validity, and permitted use. Retrieval must respect those boundaries. Similar text from a different project is not automatically applicable knowledge.
+
+## Bounded iterative retrieval
+
+An answer can reveal a missing premise and trigger another retrieval. Use a budget and a stopping criterion based on the task's evidence obligations, not an indefinite “think again” loop. A failed search is not proof that a fact does not exist.
+
+Approximate retrieval changes the semantics: the candidate set can vary with embedding models, ranking, index state, and nondeterministic services. Include those inputs in reproducibility records or explicitly adopt a probabilistic contract. The finite deterministic closure proof does not automatically cover a stochastic retriever.
+
+## Derived comprehension blocks
+
+A task-specific block can combine several attributed facts into a reusable interpretation. Its dependency record should identify the premises, transformation, uncertainty, and scope. When a premise changes, invalidate or review the block rather than treating a remembered conclusion as timeless knowledge.
+
+This gives an operational interpretation to the repeated question “what do I know about this?” The answer includes what is known, what is inferred, why it is applicable, and what remains unresolved.
+
+## Human feedback
+
+Corrections should enter through an authorized reconciliation step. Preserve who changed what, the affected scope, and whether the correction replaces a source assertion or merely expresses a preference. A malicious instruction embedded in a retrieved document remains document content, not authority to change the system's rules.
+
+The editorial-loop analogy is useful, but AI memory needs additional privacy, consent, retention, and trust controls. Code-region markers alone are not a sufficient memory-governance mechanism.
+
+## Evaluation
+
+Compare answer quality, unsupported-claim rate, stale-memory rate, retrieval cost, context size, and correction persistence against fixed-context and ordinary retrieval baselines. Use held-out tasks and blinded evaluation where judgment is required. Report failures, not only successful examples.
+
+A gain would support a bounded engineering hypothesis about context orchestration. It would not establish biological similarity, consciousness, or universal cognitive optimality. See [cognition](../research/cognition.md) and [hypotheses](../research/hypotheses.md).

DOCS/applications/code-generation.md

@@ -0,0 +1,38 @@
+---
+title: Application to code generation
+description: Reusing domain definitions across target languages while preserving context, typed bindings, and admitted custom behavior.
+section: Applications
+order: 80
+evidence: Proposed application
+---
+# Application to code generation
+
+## A language-independent compiler plan
+
+Consider a service description containing entities, fields, permissions, and operations. A VDMT implementation can gather the entity graph, resolve referenced types, derive target-specific names and validation rules, and emit schemas, server handlers, clients, and documentation. PHP is one possible target, not a requirement.
+
+The source context should distinguish a domain fact such as “email is required” from its representation in a particular target. A database constraint, a browser validation hint, and an API schema property are separate projections of that fact. Reusing the domain fact prevents redundant acquisition; it does not remove the need to validate each target projection.
+
+## Definitions and occurrences
+
+An `Address` definition may occur as a customer's billing address and a supplier's contact address. The type can be shared, while nullability, authorization, serialization name, and lifecycle belong to the occurrence. A cache keyed only by `Address` would be incorrect if it retained an occurrence-specific rendering.
+
+Use the identity model from [definition and occurrence identity](../mechanisms/occurrence-identity.md). Interpret definitions against explicit contexts, then plan artifacts from those interpretations rather than allowing arbitrary code fragments to decide their own destinations.
+
+## Staged representations
+
+A useful progression is domain facts → validated semantic model → target-specific intermediate representation → artifact plan → serialized output. String templates can implement the last stages, but an AST emitter can provide stronger guarantees against identifier capture and malformed syntax.
+
+The theory does not require that all stages share one representation. A typed relation can become an AST node and later a string, provided the transformation and provenance are clear. Late-bound imports should be derived from actual dependency usage, not from a global list that happens to work in one example.
+
+## Preserving developer adaptations
+
+Two strategies are compatible with VDMT. Keep custom logic in separate source-owned extension modules and reference them from generated code; or use the [round-trip profile](../mechanisms/round-trip.md) to recover explicitly marked regions. The first avoids parsing generated files; the second accommodates an IDE workflow in which the output is also an editing surface.
+
+Neither strategy should promise to preserve arbitrary unmarked edits. A domain-specific semantic merge is an additional capability, not an automatic consequence of the framework.
+
+## Verification
+
+Parse every generated target, check cross-file symbol resolution, validate schemas, and exercise behavior. Compare a clean build with an incremental build after changing a shared definition and an occurrence override separately. Test that the same source model can target two languages without leaking one target's names or syntax into the other.
+
+A successful cross-language implementation would support portability of the contracts. It would not establish that one language is universally faster or that every code-generation workload benefits from the same caching policy.

DOCS/applications/configuration.md

@@ -0,0 +1,38 @@
+---
+title: Application to configuration synthesis
+description: Deriving coherent deployment artifacts from shared requirements without confusing generated configuration with live operational state.
+section: Applications
+order: 82
+evidence: Proposed application
+---
+# Application to configuration synthesis
+
+## Shared requirements, different destinations
+
+A deployment description may specify services, networks, secrets references, resource limits, and policy. Context completion resolves referenced services and target capabilities. Derivation creates a target-specific plan that can emit container configuration, service units, proxy routes, firewall rules, and operator documentation.
+
+One port declaration may affect several files. One security policy may constrain many service occurrences. The architecture is useful when those relationships are explicit rather than maintained by repeated manual edits.
+
+## Environment is part of meaning
+
+A service definition interpreted for development is not the same occurrence as its production deployment. Host architecture, target operating system, available features, and policy revision can all affect the result. Include these dimensions in the input and cache identity.
+
+Secrets should normally be represented by authorized references rather than copied into every intermediate store and public artifact. Provenance must not turn a generated manifest into a secret-disclosure channel.
+
+## Planning before activation
+
+Generated configuration is an artifact, not evidence that the live environment has adopted it. Separate synthesis, validation, activation, and observation. A valid file can fail to activate because a port is occupied, a dependency is unavailable, or the current host state differs from the assumed input.
+
+The publication phase in the abstract model can be implemented as a controlled activation procedure with rollback. It must not be treated as a magical transaction across unrelated machines or services.
+
+## Persistent local adaptations
+
+An operator may have approved local exceptions. Represent them as explicit overlays with ownership and expiry, or recover only designated editable regions under the round-trip contract. Untracked changes to live generated files are configuration drift, not automatically authoritative new source.
+
+When a shared policy changes, determine whether a local exception remains valid. A three-way text comparison can detect simultaneous edits but cannot decide organizational authorization. That decision belongs to the domain's policy layer.
+
+## Verification and limits
+
+Validate syntax, references, resource feasibility, dependency cycles, and cross-artifact consistency. Test activation in a disposable environment. Compare the intended manifest with observed state after deployment and retain the distinction between desired and actual state.
+
+The framework can reduce duplication and expose dependencies. It does not guarantee availability, secure defaults, or safe migration without domain-specific rules. Those claims require operational tests and a failure model beyond code or file generation.