@supersuit/hypercontext-core 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+The first version: what every hypercontext record package shares, in one copy.
+
+- `readHeader`, `writeHeader`, `placeKey`: the YAML header codec, the union of the copies group-md, piece-md, superobjective and hypercontext each carried (group-md's was the only one with `placeKey`). Never throws on a header it does not understand; a write changes only the keys it was asked to change, every other byte kept, CRLF included. Their codec tests came with it.
+- `readFlatHeader`: the forgiving reader self-md reads self.md with (booleans, folded values joined), kept under its own name because it is not the same reader.
+- `STANDARD_BASE`, `bareStandard`, `standardUrl`, `versionOf`, `classifyStandard`: the versioned-standard rule. `stampStandard`: the byte-preserving stamp that adds `standard:` after `kind:` or upgrades a kind's bare URL in place, and never gives a headerless file a header.
+- `validateManifest`, `assertManifest`: the shape of a standard's manifest (STANDARDS.md section 2), with every problem said in words. Header-key constraints are JSON Schema's: `const`, `enum`, `pattern`, `type`, `items`, `minLength`, `maxLength`, `minItems`, `maxItems`.
+- No dependencies.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SupersuitUp
+
+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.

package/README.md

@@ -1,3 +1,50 @@
-# Temporary Holding Version
+# @supersuit/hypercontext-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+*This package lives in the [hypercontext repository](https://github.com/SupersuitUp/hypercontext/tree/main/packages/core), with every record standard that uses it.*
+
+What every hypercontext record package shares, in one copy: the YAML header codec, the rule that a record names the version of the standard it follows, and the validator for a standard's manifest. friend-md, group-md, self-md, superprojects, transcript-md, piece-md, superobjective and hypercontext are built on it, and you only need it directly if you are writing a record package of your own.
+
+```sh
+npm install @supersuit/hypercontext-core
+```
+
+## The header codec
+
+```js
+import { readHeader, writeHeader, placeKey } from '@supersuit/hypercontext-core';
+
+const { data, body, raw } = readHeader(text);       // every scalar reads as a string
+const next = writeHeader(text, { status: 'done' });  // only `status` changes, every other byte kept
+const stamped = placeKey(text, 'standard', url, 'kind'); // a new key, directly after `kind:`
+```
+
+The subset is what records use: scalars, quoted strings, flow lists, block lists, one-line flow maps and block lists of them. Two promises: it never throws on a header it does not understand (an unknown shape reads as a string and is carried through a write untouched), and a write changes only the keys it was asked to change. `null` removes a key.
+
+`readFlatHeader(text)` is the forgiving reader self-md uses: it returns the data object directly, turns `true`/`false` into booleans, and joins folded values.
+
+## Versioned standards
+
+```js
+import { standardUrl, versionOf, classifyStandard, stampStandard, bareStandard } from '@supersuit/hypercontext-core';
+
+standardUrl('friend', 1);                 // https://hypercontext.wiki/standards/friend/v1
+versionOf('friend', record.standard);     // 1, 0 for the bare URL, null for anything else
+classifyStandard('friend', value, [1]);   // {state: missing|bare|current|implemented|unimplemented|other, version}
+stampStandard(text, standardUrl('friend', 1), bareStandard('friend')); // {text, changed, reason?}
+```
+
+`stampStandard` adds `standard:` after `kind:` (first when there is none), fills an empty key in place, and upgrades the kind's bare URL. It leaves another kind's URL or another version for a person, and never gives a file with no header one.
+
+## Manifests
+
+```js
+import { validateManifest } from '@supersuit/hypercontext-core';
+
+const { ok, problems } = validateManifest(JSON.parse(readFileSync('standards/friend/v1.json', 'utf8')));
+```
+
+Checks the shape in [STANDARDS.md section 2](https://github.com/SupersuitUp/hypercontext/blob/main/packages/hypercontext/docs/STANDARDS.md): `manifest_version`, a `standard` that agrees with `kind` and `version`, `latest`, `title`, `status` and `superseded_by`, `record`, `header.required` and `header.keys` (constraints a reader can check without a package, with JSON Schema's meaning), `validator` or, when it is null, `checked_by`, every code with its `level`, `means` and `fix`, and `umbrella`.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,25 @@
 {
   "name": "@supersuit/hypercontext-core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "What every hypercontext record package shares, in one copy: the YAML header codec, the versioned-standard rule and its byte-preserving stamp, and the validator for a standard's manifest.",
+  "keywords": ["hypercontext", "records", "markdown", "frontmatter", "yaml", "manifest", "self-documenting", "supersuit"],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.mjs",
+    "./header": "./src/header.mjs",
+    "./flat-header": "./src/flat-header.mjs",
+    "./selfdoc": "./src/selfdoc.mjs",
+    "./manifest": "./src/manifest.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": ["src/", "README.md", "CHANGELOG.md", "LICENSE"],
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "mutation-check": "node scripts/mutation-check.mjs"
+  },
+  "engines": { "node": ">=20" },
+  "license": "MIT",
+  "publishConfig": { "access": "public" },
+  "repository": { "type": "git", "url": "git+https://github.com/SupersuitUp/hypercontext.git", "directory": "packages/core" },
+  "dependencies": {}
+}

package/src/flat-header.mjs

@@ -0,0 +1,186 @@
+/**
+ * readFlatHeader: a Markdown file's frontmatter as a plain object, the FORGIVING reader. Never throws.
+ *
+ * This is the second header reader the record packages carried, and it is NOT the same as
+ * header.mjs's readHeader, so it keeps its own name: it returns the data object directly rather
+ * than {data, body, raw}, turns "true"/"false" into booleans, and falls back to a line reader that
+ * joins indented continuation lines into the key above. self-md reads self.md with it.
+ *
+ * Copied from Freedom's people library (freedom-people.mjs readHeader) together with exactly the
+ * flat-YAML helpers it reaches (freedom-frontmatter split -> agentic-projects parseFlat), with
+ * behavior unchanged. The strict reader accepts the flat subset: scalars, quoted strings, inline
+ * lists and block lists. Anything it refuses (a folded value, an indented continuation) falls back
+ * to a forgiving line reader, so a hand-edited header still yields what it can.
+ */
+class FrontmatterSyntaxError extends Error {
+  constructor(message, line) { super(`line ${line}: ${message}`); this.name = "FrontmatterSyntaxError"; this.line = line; }
+}
+
+const KEY = /^([a-z][a-z0-9_]*):(?:\s+(.*))?$/;
+const LIST_ITEM = /^\s+-\s+(.*)$/;
+const INDENTED = /^\s+\S/;
+
+const unescape = (inner) => {
+  try { return JSON.parse(`"${inner}"`); }
+  catch { return inner; }
+};
+
+const unquote = (s) => {
+  const t = s.trim();
+  if (t.length >= 2 && t[0] === '"' && t.at(-1) === '"') return unescape(t.slice(1, -1));
+  if (t.length >= 2 && t[0] === "'" && t.at(-1) === "'") return t.slice(1, -1);
+  return t;
+};
+
+/** Strip a comment only when it follows a CLOSED quote or inline list. */
+const stripTrailingComment = (v) => {
+  const t = v.trim();
+  const close = t[0] === '"' || t[0] === "'" ? t[0] : t[0] === "[" ? "]" : null;
+  if (!close) return t;
+  let q = null;
+  for (let i = 1; i < t.length; i++) {
+    const ch = t[i];
+    if (q) { if (ch === "\\" && q === '"') { i++; continue; } if (ch === q) q = null; continue; }
+    if (close === "]" && (ch === '"' || ch === "'")) { q = ch; continue; }
+    if (close !== "]" && ch === "\\" && close === '"') { i++; continue; }
+    if (ch === close) {
+      const rest = t.slice(i + 1);
+      return /^\s+#/.test(rest) ? t.slice(0, i + 1) : t;
+    }
+  }
+  return t;
+};
+
+const splitTopLevel = (inner) => {
+  const out = []; let cur = ""; let q = null;
+  for (let i = 0; i < inner.length; i++) {
+    const ch = inner[i];
+    if (q) {
+      cur += ch;
+      if (ch === "\\" && q === '"') { cur += inner[++i] ?? ""; continue; }
+      if (ch === q) q = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") { q = ch; cur += ch; continue; }
+    if (ch === ",") { out.push(cur); cur = ""; continue; }
+    cur += ch;
+  }
+  if (cur.trim()) out.push(cur);
+  return out;
+};
+
+const splitInline = (inner) => splitTopLevel(inner).map(unquote).filter((s) => s !== "");
+
+/** The strict flat subset. Throws FrontmatterSyntaxError on anything outside it. */
+function parseFlat(text) {
+  const out = {};
+  const lines = String(text ?? "").split("\n");
+  let listKey = null;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i], n = i + 1;
+    if (!line.trim() || line.trim().startsWith("#")) continue;
+    const item = line.match(LIST_ITEM);
+    if (item) {
+      if (!listKey) throw new FrontmatterSyntaxError("a list item with no list key above it", n);
+      out[listKey].push(unquote(stripTrailingComment(item[1])));
+      continue;
+    }
+    if (INDENTED.test(line)) {
+      throw new FrontmatterSyntaxError(/^\s+\S+:/.test(line)
+        ? "a nested map; frontmatter here is flat (facts, never paragraphs)"
+        : "an indented continuation; a value is one line", n);
+    }
+    const kv = line.match(KEY);
+    if (!kv) {
+      const bad = line.match(/^([^:]+):/);
+      throw new FrontmatterSyntaxError(bad ? `key "${bad[1]}" is not snake_case` : "not a key: value line", n);
+    }
+    const [, key, rawVal] = kv;
+    if (key in out) throw new FrontmatterSyntaxError(`duplicate key "${key}"`, n);
+    const val = stripTrailingComment(rawVal ?? "");
+    if (val === "") {
+      const next = lines[i + 1] ?? "";
+      if (LIST_ITEM.test(next)) { out[key] = []; listKey = key; continue; }
+      out[key] = ""; listKey = null; continue;
+    }
+    listKey = null;
+    if (val.startsWith("[")) {
+      if (!val.endsWith("]")) throw new FrontmatterSyntaxError("an inline list that does not close on its line", n);
+      out[key] = splitInline(val.slice(1, -1));
+      continue;
+    }
+    out[key] = unquote(val);
+  }
+  return out;
+}
+
+/** `---\n<header>\n---\n<body>` -> { data }. data is null when there is no opening ---. */
+function split(text) {
+  const src = String(text ?? "");
+  if (!/^---\n/.test(src)) return { data: null, body: src, raw: null };
+  const end = src.indexOf("\n---\n", 3);
+  const endEof = end < 0 && src.endsWith("\n---") ? src.length - 4 : -1;
+  if (end < 0 && endEof < 0) throw new FrontmatterSyntaxError("unterminated frontmatter block: no closing ---", 1);
+  const raw = src.slice(4, end >= 0 ? end : endEof);
+  const body = end >= 0 ? src.slice(end + 5) : "";
+  return { data: parseFlat(raw), body, raw };
+}
+
+const coerce = (v) => (v === "true" ? true : v === "false" ? false : v);
+
+/** CRLF to LF, so every reader below sees one line ending. */
+const lf = (t) => String(t ?? "").replace(/\r\n?/g, "\n");
+
+/** Split a record into its raw header lines and its body. `header` is null when there is none. */
+function parts(text) {
+  const src = lf(text);
+  if (!src.startsWith("---\n")) return { header: null, body: src };
+  const end = src.indexOf("\n---", 4);
+  if (end < 0) return { header: src.slice(4), body: "" };
+  const nl = src.indexOf("\n", end + 4);
+  return { header: src.slice(4, end), body: nl < 0 ? "" : src.slice(nl + 1) };
+}
+
+/** Drop a trailing ` # comment` from an UNQUOTED `key: value` line. */
+const stripComment = (line) => {
+  const m = line.match(/^([A-Za-z_][\w-]*:[ \t]*)(.*)$/);
+  if (!m || /^["']/.test(m[2])) return line;
+  return m[1] + m[2].replace(/\s+#.*$/, "").replace(/^#.*$/, "");
+};
+
+/**
+ * The header as an object. Never throws: a folded or indented value that the strict parser
+ * refuses falls back to a line reader that joins continuation lines into the key above and
+ * collects `- item` block lists into arrays. "true"/"false" become booleans.
+ *
+ * @param {string} text The whole file.
+ * @returns {Record<string, string|boolean|string[]>}
+ */
+export function readFlatHeader(text) {
+  const { header } = parts(text);
+  if (header === null) return {};
+  const raw = header.split("\n").map(stripComment).join("\n");
+  try {
+    const { data } = split(`---\n${raw}\n---\n`);
+    if (data) return Object.fromEntries(Object.entries(data).map(([k, v]) => [k, coerce(v)]));
+  } catch { /* fall through to the line reader */ }
+  const out = {};
+  let last = null;
+  for (const line of raw.split("\n")) {
+    const m = line.match(/^([A-Za-z_][\w-]*):\s*(.*)$/);
+    if (m) {
+      last = m[1];
+      let v = m[2].trim();
+      if (v === ">-" || v === ">" || v === "|" || v === "|-") v = "";
+      if (/^\[.*\]$/.test(v)) v = v.slice(1, -1).split(",").map((x) => x.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
+      else v = coerce(v.replace(/^["']|["']$/g, ""));
+      out[last] = v;
+    } else if (last && /^\s+-\s+\S/.test(line) && (out[last] === "" || Array.isArray(out[last]))) {
+      if (!Array.isArray(out[last])) out[last] = [];
+      out[last].push(line.replace(/^\s+-\s+/, "").trim().replace(/^["']|["']$/g, ""));
+    } else if (last && /^\s+\S/.test(line) && typeof out[last] === "string") {
+      out[last] = (out[last] ? out[last] + " " : "") + line.trim();
+    }
+  }
+  return out;
+}

package/src/header.mjs

@@ -0,0 +1,274 @@
+// The YAML header of a hypercontext record, in both directions, and only the subset a record uses:
+// scalars, quoted strings, flow lists, block lists, one-line flow maps, and block lists of
+// one-line flow maps.
+//
+// ONE COPY. This codec was copied into group-md, piece-md, superobjective and hypercontext, and the
+// copies had already diverged (only group-md's had placeKey) when they were folded into this
+// package on 2026-10-20. Every package that reads this subset imports it from here, so a codec
+// fix lands once and reaches every kind.
+//
+// TWO PROMISES, AND THEY ARE WHY THIS IS HAND-ROLLED.
+//
+// 1. It never throws on a header it does not understand. A shape outside the subset (a folded
+//    scalar, a nested block map) is read as a string and its lines are carried through a write
+//    exactly as they were.
+// 2. A write changes only the keys it was asked to change. Every other line of the header and
+//    the whole body come back byte for byte, including spacing and comments, because existing
+//    records carry keys this standard does not define and other tools read them.
+//
+// Every scalar reads as a string. `member_count: 4` is "4" and `tracked: false` is "false";
+// the package that owns a kind decides what a value means.
+
+const KEY = /^([A-Za-z_][\w.-]*):(?:[ \t]+(.*?))?[ \t]*$/;
+const ITEM = /^[ \t]*-(?:[ \t]+(.*?))?[ \t]*$/;
+const FENCE = /^---[ \t]*$/;
+const clean = (line) => line.replace(/\r$/, '');
+
+// ---------------------------------------------------------------- reading values
+
+function readDouble(s, i) {
+  let j = i + 1;
+  while (j < s.length && s[j] !== '"') j += s[j] === '\\' ? 2 : 1;
+  if (j >= s.length) return null;
+  const inner = s.slice(i + 1, j);
+  let value;
+  // The inverse of JSON.stringify on the way out. A hand-typed value whose backslashes are
+  // not valid escapes is kept as written instead of thrown away.
+  try { value = JSON.parse(`"${inner}"`); } catch { value = inner; }
+  return { value, next: j + 1 };
+}
+
+function readSingle(s, i) {
+  let j = i + 1, value = '';
+  while (j < s.length) {
+    if (s[j] === "'") {
+      if (s[j + 1] === "'") { value += "'"; j += 2; continue; }
+      return { value, next: j + 1 };
+    }
+    value += s[j++];
+  }
+  return null;
+}
+
+const skipSpace = (s, i) => { while (i < s.length && (s[i] === ' ' || s[i] === '\t')) i++; return i; };
+
+// One value inside a flow list or a flow map. `stops` are the characters that end a plain scalar.
+function readFlow(s, i, stops) {
+  i = skipSpace(s, i);
+  const ch = s[i];
+  if (ch === '"') return readDouble(s, i);
+  if (ch === "'") return readSingle(s, i);
+  if (ch === '[') return readFlowList(s, i);
+  if (ch === '{') return readFlowMap(s, i);
+  let j = i;
+  while (j < s.length && !stops.includes(s[j])) j++;
+  return { value: s.slice(i, j).trim(), next: j };
+}
+
+function readFlowList(s, i) {
+  const out = [];
+  i = skipSpace(s, i + 1);
+  if (s[i] === ']') return { value: out, next: i + 1 };
+  while (i < s.length) {
+    const item = readFlow(s, i, ',]');
+    if (!item) return null;
+    i = skipSpace(s, item.next);
+    if (item.value !== '' || s[i] !== ']') out.push(item.value);
+    if (s[i] === ',') { i = skipSpace(s, i + 1); if (s[i] === ']') return { value: out, next: i + 1 }; continue; }
+    if (s[i] === ']') return { value: out, next: i + 1 };
+    return null;
+  }
+  return null;
+}
+
+function readFlowMap(s, i) {
+  const out = {};
+  i = skipSpace(s, i + 1);
+  if (s[i] === '}') return { value: out, next: i + 1 };
+  while (i < s.length) {
+    const key = readFlow(s, i, ':,}');
+    if (!key || typeof key.value !== 'string') return null;
+    i = skipSpace(s, key.next);
+    if (s[i] !== ':') return null;
+    const val = readFlow(s, i + 1, ',}');
+    if (!val) return null;
+    out[key.value] = val.value;
+    i = skipSpace(s, val.next);
+    if (s[i] === ',') { i = skipSpace(s, i + 1); if (s[i] === '}') return { value: out, next: i + 1 }; continue; }
+    if (s[i] === '}') return { value: out, next: i + 1 };
+    return null;
+  }
+  return null;
+}
+
+// A plain scalar ends at a ` #` comment. `C#` keeps its `#` because nothing precedes it with a space.
+const stripComment = (s) => s.replace(/(^|[ \t])#.*$/, '').trim();
+
+// The value on a `key: value` line or after a `- `.
+function readValue(rawValue) {
+  const s = (rawValue ?? '').trim();
+  if (s === '') return '';
+  if ('"\'[{'.includes(s[0])) {
+    const got = readFlow(s, 0, '');
+    if (got) {
+      const rest = s.slice(got.next);
+      if (/^[ \t]*(#.*)?$/.test(rest) && (rest === '' || /^[ \t]/.test(rest))) return got.value;
+    }
+    return s; // not a shape this codec models: keep the text
+  }
+  return stripComment(s);
+}
+
+// ---------------------------------------------------------------- the header as lines
+
+// Splits text into the opening fence, the header lines and everything from the closing fence on.
+function fences(text) {
+  const lines = String(text ?? '').split('\n');
+  if (!FENCE.test(clean(lines[0] ?? '').replace(/^/, ''))) return null;
+  for (let i = 1; i < lines.length; i++) {
+    if (FENCE.test(clean(lines[i]))) return { lines, close: i };
+  }
+  return null;
+}
+
+// Header lines grouped into segments: a key with the lines that belong to it, or a loose line
+// (blank, comment, anything unreadable) that no write ever touches.
+function segments(headerLines) {
+  const out = [];
+  let open = null;
+  for (const line of headerLines) {
+    const text = clean(line);
+    const key = text.match(KEY);
+    if (key) {
+      open = { key: key[1], value: key[2] ?? '', lines: [line] };
+      out.push(open);
+      continue;
+    }
+    const indented = /^[ \t]+\S/.test(text);
+    const item = ITEM.test(text);
+    if (open && (indented || (item && open.value === ''))) { open.lines.push(line); continue; }
+    open = null;
+    out.push({ key: null, lines: [line] });
+  }
+  return out;
+}
+
+function segmentValue(seg) {
+  if (seg.value !== '') return readValue(seg.value);
+  const rest = seg.lines.slice(1).map(clean);
+  if (!rest.length || !ITEM.test(rest[0])) return '';
+  const items = [];
+  for (const line of rest) {
+    const m = line.match(ITEM);
+    if (m) items.push(readValue(m[1] ?? ''));
+  }
+  return items;
+}
+
+/**
+ * Read a record's header.
+ * @returns {{data: Record<string, any>, body: string, raw: string}} `data` holds strings, lists
+ * and one-level maps; `body` is everything after the closing fence; `raw` is the header text.
+ * Text with no header reads as `{data: {}, body: text, raw: ''}`.
+ */
+export function readHeader(text) {
+  const f = fences(text);
+  if (!f) return { data: {}, body: String(text ?? ''), raw: '' };
+  const headerLines = f.lines.slice(1, f.close);
+  const data = {};
+  for (const seg of segments(headerLines)) {
+    if (seg.key && !(seg.key in data)) data[seg.key] = segmentValue(seg);
+  }
+  return {
+    data,
+    body: f.lines.slice(f.close + 1).join('\n'),
+    raw: headerLines.length ? headerLines.join('\n') + '\n' : '',
+  };
+}
+
+// ---------------------------------------------------------------- writing values
+
+const RESERVED = /^(true|false|null|yes|no|on|off|~)$/i;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+
+// One rule everywhere: a date or a single plain token starting with a letter goes bare, and
+// anything else is quoted, so no value can be read back as something it is not.
+const quote = (s) => (DATE.test(s) || (/^[A-Za-z][A-Za-z0-9_-]*$/.test(s) && !RESERVED.test(s))) ? s : JSON.stringify(s);
+
+const isMap = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+function flowValue(v) {
+  if (Array.isArray(v)) return `[${v.map(flowValue).join(', ')}]`;
+  if (isMap(v)) return flowMap(v);
+  return typeof v === 'string' ? quote(v) : String(v);
+}
+
+function flowMap(obj) {
+  const parts = Object.entries(obj).filter(([, v]) => v !== undefined && v !== null).map(([k, v]) => `${k}: ${flowValue(v)}`);
+  return `{${parts.join(', ')}}`;
+}
+
+function renderKey(key, value) {
+  if (Array.isArray(value)) {
+    if (!value.length) return [`${key}: []`];
+    if (value.some(isMap)) return [`${key}:`, ...value.map((v) => `  - ${isMap(v) ? flowMap(v) : flowValue(v)}`)];
+    return [`${key}: [${value.map((v) => JSON.stringify(String(v))).join(', ')}]`];
+  }
+  if (isMap(value)) return [`${key}: ${flowMap(value)}`];
+  return [`${key}: ${typeof value === 'string' ? quote(value) : String(value)}`];
+}
+
+// What a value will read back as, so a patch that changes nothing can be recognized.
+const canon = (v) => JSON.stringify(v, (_, x) => (x === null || x === undefined ? undefined : typeof x === 'object' ? x : String(x)));
+
+/**
+ * Set header keys, leaving every other line of the text byte-identical.
+ * A key already holding the value is not rewritten. `null` removes a key. A new key is appended
+ * before the closing fence. Text with no header gains one.
+ * @param {string} text the whole file
+ * @param {Record<string, any>} patch strings, numbers, booleans, lists, one-level maps, or null
+ */
+export function writeHeader(text, patch) {
+  const src = String(text ?? '');
+  const entries = Object.entries(patch ?? {}).filter(([, v]) => v !== undefined);
+  const f = fences(src);
+  if (!f) {
+    const lines = entries.filter(([, v]) => v !== null).flatMap(([k, v]) => renderKey(k, v));
+    if (!lines.length) return src;
+    return `---\n${lines.join('\n')}\n---\n${src}`;
+  }
+  const eol = /\r$/.test(f.lines[0]) ? '\r' : '';
+  const segs = segments(f.lines.slice(1, f.close));
+  for (const [key, value] of entries) {
+    const at = segs.findIndex((s) => s.key === key);
+    if (value === null) { if (at >= 0) segs.splice(at, 1); continue; }
+    if (at >= 0 && canon(segmentValue(segs[at])) === canon(value)) continue;
+    const seg = { key, value: '', lines: renderKey(key, value).map((l) => l + eol) };
+    seg.value = clean(seg.lines[0]).match(KEY)?.[2] ?? '';
+    if (at >= 0) segs[at] = seg; else segs.push(seg);
+  }
+  return [f.lines[0], ...segs.flatMap((s) => s.lines), ...f.lines.slice(f.close)].join('\n');
+}
+
+/**
+ * Set one header key, and when the header does not have it yet, place it directly after the
+ * segment of `afterKey` (first in the header when that key is absent) instead of at the end.
+ * Every other line stays byte-identical, and the line ending follows the opening fence.
+ * A key already holding the value is a no-op; one holding another value is replaced in place.
+ * @param {string} text the whole file
+ * @param {string} key
+ * @param {any} value
+ * @param {string} afterKey
+ */
+export function placeKey(text, key, value, afterKey) {
+  const src = String(text ?? '');
+  const f = fences(src);
+  if (!f) return writeHeader(src, { [key]: value });
+  const segs = segments(f.lines.slice(1, f.close));
+  if (segs.some((s) => s.key === key)) return writeHeader(src, { [key]: value });
+  const eol = /\r$/.test(f.lines[0]) ? '\r' : '';
+  const at = segs.findIndex((s) => s.key === afterKey);
+  const lines = renderKey(key, value).map((l) => l + eol);
+  segs.splice(at + 1, 0, { key, value: '', lines });
+  return [f.lines[0], ...segs.flatMap((s) => s.lines), ...f.lines.slice(f.close)].join('\n');
+}

package/src/index.mjs

@@ -0,0 +1,5 @@
+// @supersuit/hypercontext-core: what every hypercontext record package shares, in one copy.
+export { readHeader, writeHeader, placeKey } from './header.mjs';
+export { readFlatHeader } from './flat-header.mjs';
+export { STANDARD_BASE, bareStandard, standardUrl, versionOf, classifyStandard, stampStandard } from './selfdoc.mjs';
+export { validateManifest, assertManifest, MANIFEST_VERSION, STATUSES, FORMATS, LEVELS, CONSTRAINTS, TYPES } from './manifest.mjs';

package/src/manifest.mjs

@@ -0,0 +1,125 @@
+// The shape of a standard's manifest: the machine-readable twin of one version of one standard
+// (docs/STANDARDS.md in @supersuit/hypercontext, section 2), checked as data.
+//
+// Every record package ships its manifests at standards/<kind>/v<N>.json, the umbrella reads them
+// to know which versions exist, and the wiki publishes them unchanged. One validator for all of
+// them, so a manifest that a reader with no package could not use is refused in the package that
+// ships it rather than discovered by the reader.
+import { STANDARD_BASE, bareStandard, standardUrl } from './selfdoc.mjs';
+
+export const MANIFEST_VERSION = 1;
+export const STATUSES = Object.freeze(['current', 'superseded']);
+export const FORMATS = Object.freeze(['md', 'json']);
+/** Finding levels a manifest's codes may carry. transcript-md says `warning` where others say `warn`. */
+export const LEVELS = Object.freeze(['error', 'warn', 'warning', 'info']);
+/**
+ * The constraints a header key may carry: the ones a reader can check without installing anything.
+ * Their meaning is JSON Schema's, so a reader may hand them to any JSON Schema validator.
+ */
+export const CONSTRAINTS = Object.freeze(['const', 'enum', 'pattern', 'type', 'items', 'minLength', 'maxLength', 'minItems', 'maxItems']);
+export const TYPES = Object.freeze(['string', 'number', 'integer', 'boolean', 'array', 'object', 'null']);
+
+const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const isStr = (v) => typeof v === 'string' && v.trim() !== '';
+const KIND = /^[a-z][a-z0-9-]*$/;
+const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+
+function checkConstraint(where, c, problems) {
+  if (!isObj(c)) { problems.push(`${where} is not an object of constraints`); return; }
+  for (const name of Object.keys(c)) if (!CONSTRAINTS.includes(name)) problems.push(`${where} has constraint "${name}", which is not one of ${CONSTRAINTS.join(', ')}`);
+  if ('enum' in c && (!Array.isArray(c.enum) || c.enum.length === 0)) problems.push(`${where}.enum is not a non-empty list`);
+  if ('pattern' in c) {
+    if (typeof c.pattern !== 'string') problems.push(`${where}.pattern is not a string`);
+    else { try { new RegExp(c.pattern); } catch { problems.push(`${where}.pattern is not a valid regular expression`); } }
+  }
+  if ('type' in c) {
+    const types = Array.isArray(c.type) ? c.type : [c.type];
+    for (const t of types) if (!TYPES.includes(t)) problems.push(`${where}.type "${t}" is not one of ${TYPES.join(', ')}`);
+  }
+  for (const n of ['minLength', 'maxLength', 'minItems', 'maxItems']) if (n in c && !(Number.isInteger(c[n]) && c[n] >= 0)) problems.push(`${where}.${n} is not a whole number`);
+  if ('items' in c) checkConstraint(`${where}.items`, c.items, problems);
+}
+
+/**
+ * Check one manifest against the shape STANDARDS.md section 2 defines.
+ * @param {unknown} m the parsed manifest
+ * @returns {{ok: boolean, problems: string[]}} every problem found, in plain words; empty when ok
+ */
+export function validateManifest(m) {
+  const problems = [];
+  if (!isObj(m)) return { ok: false, problems: ['the manifest is not a JSON object'] };
+  if (m.manifest_version !== MANIFEST_VERSION) problems.push(`manifest_version is ${JSON.stringify(m.manifest_version)}, not ${MANIFEST_VERSION}`);
+
+  const kindOk = typeof m.kind === 'string' && KIND.test(m.kind);
+  if (!kindOk) problems.push(`kind ${JSON.stringify(m.kind)} is not a lowercase kind name`);
+  const versionOk = Number.isInteger(m.version) && m.version >= 1;
+  if (!versionOk) problems.push(`version ${JSON.stringify(m.version)} is not a whole number from 1`);
+  if (typeof m.standard !== 'string' || !m.standard.startsWith(STANDARD_BASE)) problems.push(`standard ${JSON.stringify(m.standard)} is not a ${STANDARD_BASE}<kind>/v<N> URL`);
+  else if (kindOk && versionOk && m.standard !== standardUrl(m.kind, m.version)) problems.push(`standard is ${m.standard}, but kind and version say ${standardUrl(m.kind, m.version)}`);
+  if (kindOk && m.latest !== bareStandard(m.kind)) problems.push(`latest is ${JSON.stringify(m.latest)}, not ${bareStandard(m.kind)}`);
+
+  if (!isStr(m.title)) problems.push('title is missing or empty');
+  if (!STATUSES.includes(m.status)) problems.push(`status ${JSON.stringify(m.status)} is not one of ${STATUSES.join(', ')}`);
+  if ('superseded_by' in m && m.superseded_by !== null && typeof m.superseded_by !== 'string') problems.push('superseded_by is neither null nor a URL');
+  if (m.status === 'superseded' && !isStr(m.superseded_by)) problems.push('status is superseded, and superseded_by names no URL');
+  if (m.status === 'current' && isStr(m.superseded_by)) problems.push('status is current, and superseded_by names a URL');
+
+  if (!isObj(m.record)) problems.push('record is missing');
+  else {
+    if (!isStr(m.record.path)) problems.push('record.path is missing or empty');
+    if (!FORMATS.includes(m.record.format)) problems.push(`record.format ${JSON.stringify(m.record.format)} is not one of ${FORMATS.join(', ')}`);
+  }
+
+  if (!isObj(m.header)) problems.push('header is missing');
+  else {
+    if (!Array.isArray(m.header.required) || !m.header.required.every(isStr)) problems.push('header.required is not a list of key names');
+    else if (new Set(m.header.required).size !== m.header.required.length) problems.push('header.required names a key twice');
+    if (!isObj(m.header.keys)) problems.push('header.keys is not an object');
+    else {
+      for (const [key, c] of Object.entries(m.header.keys)) checkConstraint(`header.keys.${key}`, c, problems);
+      const std = m.header.keys.standard;
+      if (isObj(std) && 'const' in std && std.const !== m.standard) problems.push(`header.keys.standard.const is ${JSON.stringify(std.const)}, not this manifest's standard`);
+      const kind = m.header.keys.kind;
+      if (isObj(kind) && 'const' in kind && kind.const !== m.kind) problems.push(`header.keys.kind.const is ${JSON.stringify(kind.const)}, not this manifest's kind`);
+    }
+  }
+
+  if (m.validator === null) {
+    if (!isObj(m.checked_by)) problems.push('validator is null and checked_by is missing: nothing says what checks this kind');
+    else {
+      if (!isStr(m.checked_by.check)) problems.push('checked_by.check is missing or empty');
+      if (!isStr(m.checked_by.note)) problems.push('checked_by.note is missing: it must say what is not checked');
+    }
+  } else if (!isObj(m.validator)) problems.push('validator is neither an object nor null');
+  else {
+    if (!isStr(m.validator.package)) problems.push('validator.package is missing or empty');
+    if (typeof m.validator.implements_since !== 'string' || !SEMVER.test(m.validator.implements_since)) problems.push(`validator.implements_since ${JSON.stringify(m.validator.implements_since)} is not a version`);
+    if (!isStr(m.validator.check)) problems.push('validator.check is missing or empty');
+    if ('backfill' in m.validator && m.validator.backfill !== null && !isStr(m.validator.backfill)) problems.push('validator.backfill is neither null nor a command');
+  }
+
+  if (!Array.isArray(m.codes) || m.codes.length === 0) problems.push('codes is not a non-empty list');
+  else {
+    const seen = new Set();
+    m.codes.forEach((c, i) => {
+      const at = isObj(c) && isStr(c.code) ? `codes "${c.code}"` : `codes[${i}]`;
+      if (!isObj(c)) { problems.push(`${at} is not an object`); return; }
+      if (!isStr(c.code)) problems.push(`${at} has no code`);
+      else if (seen.has(c.code)) problems.push(`${at} is listed twice`);
+      else seen.add(c.code);
+      if (!LEVELS.includes(c.level)) problems.push(`${at} has level ${JSON.stringify(c.level)}, not one of ${LEVELS.join(', ')}`);
+      if (!isStr(c.means)) problems.push(`${at} does not say what it means`);
+      if (!isStr(c.fix)) problems.push(`${at} does not say how to fix it`);
+    });
+  }
+
+  if (!isStr(m.umbrella)) problems.push('umbrella is missing or empty');
+  return { ok: problems.length === 0, problems };
+}
+
+/** validateManifest, throwing one error that lists every problem. For a package's own tests. */
+export function assertManifest(m, label = 'manifest') {
+  const { ok, problems } = validateManifest(m);
+  if (!ok) throw new Error(`${label} is not a valid manifest:\n  - ${problems.join('\n  - ')}`);
+  return m;
+}

package/src/selfdoc.mjs

@@ -0,0 +1,90 @@
+// The one property every hypercontext record shares: it names the version of the standard it
+// follows, so an agent that has never seen its package can open the file cold and find its rules
+// (docs/STANDARDS.md in @supersuit/hypercontext, section 1).
+//
+// What lives here is the part every package agrees on: the URL shapes, how a URL is read back as
+// a version of a kind, and the byte-preserving stamp that writes `standard:` into a header. What a
+// package does with an unimplemented version (refuse, throw, leave it) is that package's policy and
+// stays in that package.
+import { readHeader, writeHeader } from './header.mjs';
+
+export const STANDARD_BASE = 'https://hypercontext.wiki/standards/';
+
+/** The unversioned page of a kind: always its latest version. A record never names it. */
+export const bareStandard = (kind) => `${STANDARD_BASE}${kind}`;
+
+/** The URL of one version of a kind's standard, the value a record carries under `standard:`. */
+export const standardUrl = (kind, version) => `${bareStandard(kind)}/v${version}`;
+
+/**
+ * The version a URL names for a kind: a number, 0 for the bare URL (written before versions
+ * existed), null for anything else (another kind's standard, a typo, a URL that only looks like a
+ * version).
+ * @param {string} kind
+ * @param {unknown} standard
+ * @returns {number|null}
+ */
+export function versionOf(kind, standard) {
+  const s = String(standard ?? '');
+  if (s === bareStandard(kind)) return 0;
+  const m = s.startsWith(`${bareStandard(kind)}/v`) ? s.slice(bareStandard(kind).length + 2).match(/^(\d+)$/) : null;
+  return m ? Number(m[1]) : null;
+}
+
+/**
+ * What a record's `standard:` value says, relative to the versions a validator implements:
+ * - `missing`: absent or empty;
+ * - `bare`: the kind's unversioned URL, written before versions; a stamp upgrades it;
+ * - `current`: the newest implemented version, the one writers stamp;
+ * - `implemented`: an older version the validator still reads;
+ * - `unimplemented`: a version of this kind the validator does not implement;
+ * - `other`: another kind's standard or any other string.
+ * @param {string} kind
+ * @param {unknown} standard
+ * @param {number[]} [implemented=[1]]
+ * @returns {{state: 'missing'|'bare'|'current'|'implemented'|'unimplemented'|'other', version: number|null}}
+ */
+export function classifyStandard(kind, standard, implemented = [1]) {
+  const s = typeof standard === 'string' ? standard.trim() : '';
+  if (!s) return { state: 'missing', version: null };
+  const v = versionOf(kind, s);
+  if (v === 0) return { state: 'bare', version: null };
+  if (v === null) return { state: 'other', version: null };
+  if (!implemented.includes(v)) return { state: 'unimplemented', version: v };
+  return { state: v === Math.max(...implemented) ? 'current' : 'implemented', version: v };
+}
+
+/**
+ * Add `standard:` to a record that names none, or upgrade the bare URL of its own kind (written
+ * before versions) to the given version, changing nothing else. A new line goes directly after
+ * `kind:` when the header has one, otherwise first. A record naming another kind's standard, or a
+ * version of its own, comes back unchanged: that is a judgment for a person. A file with no header
+ * is never given one. CRLF line endings are kept.
+ * @param {string} text
+ * @param {string} url the versioned standard to name
+ * @param {string} [bare] the kind's unversioned URL, upgraded in place when found
+ * @returns {{text: string, changed: boolean, reason?: string}}
+ */
+export function stampStandard(text, url, bare) {
+  const src = String(text ?? '');
+  const h = readHeader(src);
+  if (h.raw === '' && !/^---[ \t]*\r?\n/.test(src)) return { text: src, changed: false, reason: 'no header' };
+  const lines = src.split('\n');
+  let close = -1;
+  for (let i = 1; i < lines.length; i++) if (/^---[ \t]*\r?$/.test(lines[i])) { close = i; break; }
+  if (close < 0) return { text: src, changed: false, reason: 'no header' };
+  const eol = /\r$/.test(lines[0]) ? '\r' : '';
+  const has = typeof h.data.standard === 'string' && h.data.standard !== '';
+  if (has && bare && h.data.standard === bare) {
+    for (let i = 1; i < close; i++) {
+      if (/^standard:/.test(lines[i])) { lines[i] = `standard: ${JSON.stringify(url)}${eol}`; return { text: lines.join('\n'), changed: true }; }
+    }
+  }
+  if (has) return { text: src, changed: false, reason: 'already names a standard' };
+  // An empty `standard:` key is filled in place rather than duplicated.
+  if ('standard' in h.data) return { text: writeHeader(src, { standard: url }), changed: true };
+  let at = 1;
+  for (let i = 1; i < close; i++) if (/^kind:/.test(lines[i])) { at = i + 1; break; }
+  lines.splice(at, 0, `standard: ${JSON.stringify(url)}${eol}`);
+  return { text: lines.join('\n'), changed: true };
+}