Files

T

harness: withdraw five pre-code ADRs to deferred ideas

Twenty-seven ADRs existed before a line of Go. Five specified the shape of
unbuilt mechanisms — cache validity, declared types, the settings cascade,
taxonomies, extras — which breaks the rule against abstraction before a
second concrete use, in prose where the counters cannot see it. They move to
ideas/deferred-decisions.md as recorded intent and return shaped by whatever
implements them.

Citations retargeted throughout; where one was decoration the rule now stands
on its own reasoning. Type declarations and the cascade drop to [spec] with
the MVP behaviour stated instead, so the first prompts have less to build.
conventions.md names http.ServeMux as the router, closing a hole that invited
hand-rolling a path splitter. The ADR gate now checks a number is registered
in the log rather than headed by an entry, so withdrawals resolve and invented
numbers still fail. Two architecture invariants corrected: identity no longer
implies a required language suffix, and the duplicated permalink clause is gone.

2026-07-30 01:01:38 +06:00

4.7 KiB

Raw Blame History

Extensions

The plugin story, and the gate keeping it from arriving early.

STATUS: not buildable yet. A feature is its own directory under internal/ext/<name>/, called explicitly from wire.go (ADR-0027) — correct and sufficient until the counters say otherwise. This document exists so the eventual shape is known, not so it can be built now.

The gate

Stage of growth	What a feature looks like	Trigger to advance
Now (0–2 features)	Its own directory under `internal/ext/<name>/`, called explicitly from `wire.go`	—
Transform counter due	Extract the Stage pipeline: an ordered `[]Stage` in one wire file	`state.md`
Extension counter due	Extract the `Extension` struct below; move each into `internal/ext/<name>`	`state.md`
After Arc 2	Composition only; the core no longer grows	Arc 2 closes

state.md holds the thresholds and is the only place they are written. Do not extract early. Do not "prepare".

Target shape

Compile-time registry. No plugin.so, no init() side effects, no discovery, no config file listing plugins. One slice, one file, source order — the order is the semantics.

Compile-time is not a preference: Go's plugin package forbids a static binary and demands an exact toolchain match, which the container target (ADR-0010) rules out. Dynamic loading buys only extension-without-recompiling, worth nothing to the single author (ADR-0006) holding commit access. The registry costs a few hundred lines that render zero pages — hence real callers before a contract.

// internal/ext/ext.go — the whole contract, once earned.
type Extension struct {
    Name       string
    Stages     []Stage                // ordered; Phase decides placement
    Views      map[string]View         // named, referenced by frontmatter `view:`
    Shortcodes map[string]Shortcode    // trusted content only (ADR-0003)
    Effects    []Effect                // derived artifacts and outbound calls, off the request path
    Adapters   []Adapter               // Interaction sources, Arc 3
    Routes     []Route                 // additional URL cases, via the resolver
}

cmd/atelier/wire.go holds the only list of enabled extensions. Enabling or disabling one is a one-line diff and a rebuild. Removing one leaves no trace elsewhere — that property is the test of whether the contract is right.

Stage phases

An ordered list, not a dependency graph. Two stages needing a graph to be correct are one stage wearing a disguise.

Phase	Operates on	Examples
`PhaseLoad`	raw bytes + frontmatter	includes, translation fallback
`PhaseParse`	the parsed Markdown tree	shortcodes, transclusion, image derivatives
`PhaseMarkup`	rendered HTML fragments, code spans skipped	smart quotes, dashes, widows, Bengali numerals
`PhasePage`	the assembled page object	OpenGraph, JSON-LD, related posts, series nav
`PhaseOutput`	the final byte stream	minification, dithering, gemtext conversion

Every Stage runs on every bundle unless a cascade key disables it (ideas/deferred-decisions.md), and declares its trust requirement. A Stage evaluating templates or shortcodes runs in trusted mode only, and the pipeline refuses it otherwise — enforced in code, not by convention, and tested with an untrusted-input case.

Rules for any extension

Deletable without trauma. Removing the package leaves the engine building and serving.
Reads only what already exists on the page; adds through the Extra bag, never by widening the core struct for its own convenience.
Owns its output files under a namespaced path, or none.
No new dependency without an ADR — extensions get no looser budget than the core, and their Go lines count against EXT_LOC_MAX. Presentation features (OpenGraph, galleries, series nav, related posts) belong in templates and frontmatter where they cost nothing; reach for Go only when there is real logic.
Failure degrades: a broken extension logs and is skipped, never takes a request down.
Needing a permanent external service or a primitive change makes it a trunk — see exploration.md.
One directory, no sibling imports, and a doc.go in this shape (ADR-0027):

// Package feeds emits RSS and Atom for the primary feed and each section.
//
// Contributes: Effect (on change).
// Cascade keys: feeds.enabled, feeds.limit.
// Contract fields: none.
// Not doing: JSON Feed, WebSub — separate features if wanted.
package feeds

ContentAPI

A thin internal write path, introduced with comments in Arc 3 and not before. It exists so a second client (admin panel, Micropub endpoint) becomes possible without the engine growing a UI. Read paths keep going straight to the filesystem; git remains the source of truth.

4.7 KiB Raw Blame History Unescape Escape