Substrate-native compatibility — why the Action API shim was dropped

@@ -20,19 +20,9 @@ cites:
 - osc-sn-51-721
---

The PointSav wiki at `documentation.pointsav.com` provides structural compatibility with MediaWiki's reader-facing conventions — URL patterns, wikilink syntax, footnote syntax — while deliberately declining to replicate MediaWiki's internal API surface. Every interface the substrate does not replicate is a [[compliance-and-continuous-disclosure|compliance obligation]] it does not assume.

**Correction (2026-08-02, verified against canonical `origin/main`):** this article's
whole v0.1.x route surface (`GET /git/{slug}`, `POST /edit/{slug}`, `GET
/feed.json`, MBA-auth editing) describes an **earlier, retired** wiki engine, not the
live one. `app-mediakit-knowledge`'s real `Cargo.toml` states explicitly: "ground-up
rewrite... Renamed from app-mediakit-knowledge-2 at cutover (plan P8). 100% new
code," now at `version = "0.0.1"`. The live router (`app.rs`) has no `/edit`, `/git`,
or `/feed.json` route, and no `EDITOR_ENABLED`/MBA-auth machinery exists anywhere in
the crate. Conversely, `GET /history/{*slug}` — which a companion passage in this
article calls "(Phase 4)"/not-yet-built — is already live in the real router today.
**Flagged, not resolved** — this article needs re-basing against the current engine,
not a line-by-line fix.
The PointSav wiki at `documentation.pointsav.com` provides structural compatibility with MediaWiki's reader-facing conventions — URL patterns, wikilink syntax, footnote syntax — while deliberately declining to replicate MediaWiki's internal API surface, including a write API. Every interface the substrate does not replicate is a [[compliance-and-continuous-disclosure|compliance obligation]] it does not assume.

The engine is read-only from a visitor's perspective — there is no in-browser editor, no write API, and no authenticated edit path of any kind. An article is edited in its source git repository, through the normal editorial workflow that produces the commit, and the change appears on the wiki's next render with no service restart. The revision history a reader sees is that same git log, read directly rather than duplicated into a separate database.

## Cost and benefit of declining the shim

@@ -58,7 +48,7 @@ But the moat has two parts, and the parts have different costs to participate in

### Reader and integrator conventions

The first part is **reader and external-integrator structural compatibility**: a reader who knows Wikipedia's URL pattern and markup can navigate and edit the wiki without retraining; an external system that ingests `sitemap.xml` or follows wikilinks discovers the corpus without bespoke adapters. This part is low-cost to provide — `/wiki/{slug}`, `[[wikilink]]`, and `[^1]` are conventions the substrate adopts because they are useful, not mimicry.
The first part is **reader and external-integrator structural compatibility**: a reader who knows Wikipedia's URL pattern and markup can navigate the wiki without retraining; an external system that ingests `sitemap.xml` or follows wikilinks discovers the corpus without bespoke adapters. This part is low-cost to provide — `/wiki/{slug}`, `[[wikilink]]`, and `[^1]` are conventions the substrate adopts because they are useful, not mimicry.

### Interface mimicry and its costs

@@ -80,7 +70,7 @@ Four substrate-compatibility surfaces are preserved, all in the low-cost-to-prov

**URL conventions.** `/wiki/{slug}` matches MediaWiki's URL layout. External sites that link to articles via this URL pattern continue to resolve without 404s. The route is one line in the wiki engine's axum router and costs nothing to maintain. Adopting the convention is a low-cost ecosystem-reach choice.

**Wikilink syntax.** `[[slug]]` and `[[slug|display text]]` match Wikipedia's markup. Contributors who know Wikipedia recognise the form. The wiki's renderer parses wikilinks at render time, resolves them against the in-memory link graph (the redb-backed graph lights up in Phase 4), and emits HTML with red-link styling for unresolved targets.
**Wikilink syntax.** `[[slug]]` and `[[slug|display text]]` match Wikipedia's markup. Contributors who know Wikipedia recognise the form. The engine indexes the content tree into an in-memory link graph on startup, and the renderer resolves wikilinks against that index at render time, emitting HTML with red-link styling for unresolved targets.

**Footnote syntax.** `[^1]` matches CommonMark's footnote extension. The bibliography resolves footnotes against the article's frontmatter `references:` list. The implementation ships with `comrak` and adds no maintenance burden specific to the substrate.

@@ -94,7 +84,7 @@ Three surfaces in the high-cost-to-provide category were declined:

- *Maintenance scales with MediaWiki's velocity.* Every Action API endpoint MediaWiki ships, deprecates, or modifies generates a shim-side maintenance event. The substrate cannot govern that velocity.
- *Compliance audit scales with the API surface.* Every interface the substrate exposes to the public must be disclosure-grounded under applicable continuous-disclosure requirements. The Action API shim would have multiplied the audit surface by an order of magnitude with no commensurate ecosystem benefit on the substrate's actual customer base.
- *Substrate-native interfaces cover the use cases.* The wiki's route surface (`/wiki/{slug}`, JSON-LD, Atom, JSON Feed, sitemap, `llms.txt`, raw Markdown via `/git/{slug}`, `/search?q=`, `POST /edit/{slug}`) covers what the Action API shim would have served, without committing the substrate to Wikipedia's API contract.
- *Substrate-native interfaces cover the reader-facing use cases.* The wiki's route surface (`/wiki/{slug}`, JSON-LD, Atom, sitemap, `/search?q=`) covers what the Action API shim's reader-facing surface would have served, without committing the substrate to Wikipedia's API contract. The shim's write-side surface (`?action=edit`, authentication) has no substrate-native equivalent at all — the engine is read-only over HTTP; articles are edited in the source git repository, not through the wiki.

**MediaWiki templates and parser functions.** The wiki's renderer is `comrak` (CommonMark) plus PointSav-specific extensions for wikilinks, footnotes, table of contents, and section anchors. It is not a MediaWiki parser. Templates do not expand server-side. The workaround for content that would be a template in MediaWiki is Markdown partials, inlined by the contributor at edit time; the substrate accepts the duplication cost in exchange for a deterministic rendering pipeline that can be audited without parsing a Turing-complete template language at render time.

@@ -102,23 +92,21 @@ Three surfaces in the high-cost-to-provide category were declined:

## The substrate-native API surface set

What the Action API shim would have served, the substrate's native interfaces serve coherently:
The Action API shim's reader-facing surface, the substrate's native interfaces serve coherently — its write and authentication surface has no substrate-native equivalent, by design:

| Action API need | Substrate-native interface |
|---|---|
| `?action=parse` (render Markdown to HTML) | `GET /wiki/{slug}` (rendered HTML directly) |
| `?action=raw` (raw wikitext) | `GET /git/{slug}` (raw Markdown) |
| `?action=edit` (write articles) | `POST /edit/{slug}` (atomic write with frontmatter validation) |
| `?action=query&list=allpages` (enumerate articles) | `GET /sitemap.xml` (sitemaps.org compliant) |
| `?action=query&prop=links` (link graph) | `GET /backlinks/{slug}` (Phase 4) |
| `?action=query&prop=revisions` (history) | `GET /history/{slug}` (Phase 4) |
| `?action=opensearch` / `?action=query&list=search` | `GET /search?q=` (Tantivy / BM25) |
| `?action=query&list=allpages` (enumerate articles) | `GET /sitemap.xml` (sitemaps.org compliant), `GET /special/all-pages` |
| `?action=query&prop=revisions` (history) | `GET /history/{slug}` (live — reads the git log directly, renders each revision's diff) |
| `?action=opensearch` / `?action=query&list=search` | `GET /search?q=` (Tantivy full-text search) |
| `?format=json` (machine-readable per article) | JSON-LD `<script type="application/ld+json">` in every article's `<head>` |
| RSS / Atom feeds | `GET /feed.atom` + `GET /feed.json` |
| RSS / Atom feeds | `GET /feed.atom` |
| `?action=expandtemplates` | not provided; the substrate's renderer does not expand templates |
| `?action=login` / authentication | not provided over HTTP; authenticated edits use the Mutual Bidirectional Auth (MBA) path |
| `?action=edit` (write articles) | not provided over HTTP at all — there is no write API, no in-browser editor, and no authenticated edit path; an article is edited in its source git repository and appears on next render |
| `?action=login` / authentication | not applicable — there is nothing to authenticate against, since the engine exposes no write surface |

The interfaces compose with the substrate's other invariants. The JSON-LD is generated from the article's frontmatter by the same code path that emits the article HTML, so the structured data cannot drift from the rendered content. The Atom feed shares its data source with the JSON Feed, the sitemap, and the index page; a content tree change updates all four atomically. The [[worm-ledger-design|search backend]] (Tantivy) reads the same content tree as the HTML renderer; no separate write path needs to keep the search index synchronised with the article store, because the article store is the file system.
The interfaces compose with the substrate's other invariants. The JSON-LD is generated from the article's frontmatter by the same code path that emits the article HTML, so the structured data cannot drift from the rendered content. The Atom feed shares its data source with the sitemap and the index page; a content tree change updates all three atomically. The search backend (Tantivy) reads the same content tree as the HTML renderer; no separate write path needs to keep the search index synchronised with the article store, because the article store is the file system.

## The `verify://` URL scheme (planned)

@@ -138,7 +126,7 @@ An Action API shim returning `?action=query&prop=revisions` would have committed

An Action API shim returning `?action=parse` server-side would have committed the substrate to a server-side rendering contract independent of the Markdown source. If the rendered HTML drifts from the Markdown source, the substrate has a disclosure conflict. The substrate declines the shim and keeps the rendered HTML a deterministic function of the Markdown source plus the renderer version.

An Action API shim supporting `?action=edit` would have committed the substrate to an authenticated write path with weaker provenance than the substrate's edit surface. The `POST /edit/{slug}` route requires MBA-verified authorship per SYS-ADR-19; a MediaWiki-style API edit would have permitted token-bearer auth over a session that does not bind the editor's identity to a human-verified key chain. The substrate declines the shim and keeps the provenance guarantee.
An Action API shim supporting `?action=edit` would have committed the substrate to an authenticated HTTP write path with weaker provenance than the substrate's real edit surface — git commit authorship, which the workspace's own commit discipline already binds to a verified identity. A MediaWiki-style API edit would have introduced a second, token-bearer-auth write path that does not carry the same identity guarantee. The substrate declines the shim entirely rather than build a parallel path — there is no write API to secure, so there is nothing to authenticate against.

The pattern: every interface the substrate does not replicate is an obligation it does not assume.