wyrd-scribe 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 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.

package/README.md

@@ -0,0 +1,114 @@
+# wyrd-scribe
+
+`wyrd-scribe` is a Tier-A MCP server for creating provenance-stamped Markdown pages inside one
+folder you explicitly grant. Tier A is create-only: it can create a new page and append its lineage
+record, but it cannot overwrite, rename, or delete a page, and it exposes no lineage-query tool.
+
+## Installation and configuration
+
+Install it with `npm install -g wyrd-scribe`.
+The executable is `wyrd-scribe`. It communicates over stdio, so an MCP client configuration can
+launch it directly:
+
+```json
+{
+  "command": "wyrd-scribe",
+  "args": ["--grant", "/absolute/path/to/folder"]
+}
+```
+
+The granted folder may instead be supplied as `WYRD_GRANT`. An explicit `--grant` argument takes
+precedence over `WYRD_GRANT`. `WYRD_SCRIBE_TIER` selects the tier and defaults to `A` when absent.
+This build recognises tiers B and C but refuses to start with either because those tiers are not
+implemented.
+
+## `write_page`
+
+The server exposes one tool with this exact input shape:
+
+```json
+{
+  "path": "Notes/new-page.md",
+  "content": "Page text\n",
+  "derived_from": [
+    {
+      "source": "Sources/source.md",
+      "spans": [
+        { "offset": 0, "length": 9 },
+        { "quote": "source text" },
+        { "offset": 0, "length": 9, "quote": "source te" }
+      ]
+    }
+  ]
+}
+```
+
+`path` and every `derived_from[].source` are relative to the granted folder. Each span is exactly
+one of: byte `offset` plus positive byte `length`; a non-empty, uniquely occurring `quote`; or all
+three fields, in which case the bytes and quote must agree. Unknown input keys are refused.
+
+The granted folder must already contain a `.wyrd/` directory. The Scribe does not create that
+directory. On the first eligible write it mints `.wyrd/scribe.json` with this shape:
+
+```json
+{
+  "schema": "wyrd.scribe/v1",
+  "vault_id": "a server-minted UUID v4",
+  "write_frontmatter": false
+}
+```
+
+`write_frontmatter` defaults to `false`. Set it to `true` in the vault configuration to opt into a
+`wyrd_lineage` key in created pages.
+
+## Outcomes and recovery
+
+A successful call creates the page first and then appends one LF-terminated JSON record to
+`.wyrd/lineage.jsonl`. If the ledger append fails after page creation, the page is retained. The
+result is `PAGE_WRITTEN_LEDGER_FAILED`, includes the created-page information and underlying
+`cause`, and may report retained bytes. Inspect the retained page and ledger before repairing or
+retrying; a retry at the same page path is create-only and will refuse `EXISTS`.
+
+Each ledger line is a `wyrd.lineage/v1` object with `event: "page_written"`, a server-minted
+`event_id`, `recorded_at`, the `wyrd-scribe` writer and version, the vault UUID, the created page's
+path and SHA-256 content identity, and a `sources` array. Every source carries its grant-relative
+path and content identity; every span records byte offset and length plus stored quote text, byte
+counts, full-quote SHA-256, and whether the stored text was truncated.
+
+When frontmatter projection is enabled, the created page receives one `wyrd_lineage` key containing
+single-line JSON. The projection carries the schema, event, event ID, timestamp, writer, vault, and
+sources. It deliberately omits the page identity and page content hash; `event_id` joins it to the
+complete ledger record.
+
+## Security boundary and limits
+
+All granted-folder reads and writes go through `wyrd-fence`. The containment guarantees, hard-link
+limits, residual filesystem races, and recovery consequences are defined in the Fence's
+[authoritative Security boundary and limits section](https://github.com/MortalPastry/wyrd-mcp/blob/main/packages/wyrd-fence/README.md#security-boundary-and-limits).
+The Scribe additionally refuses directly addressed `Arc/` targets and performs create-only page
+writes. These controls are a scoped filesystem boundary, not an operating-system sandbox.
+
+## Privacy and data flow
+
+The server uses stdio only; it does not open a network transport. It reads the vault configuration
+and cited source bytes inside the granted folder, and writes only the new page, the minted config
+when needed, and the lineage ledger there. The connected MCP client receives tool metadata and the
+structured result or refusal, including lineage and recovery information; it does not receive
+absolute host paths or uncited source-file contents from the Scribe.
+
+## Build and test from source
+
+From the workspace root:
+
+```sh
+npm install
+npm --workspace wyrd-fence run build
+npm --workspace wyrd-mcp run build
+npm --workspace wyrd-scribe test
+```
+
+The package's `test` lifecycle builds the Reader prerequisite before running the Scribe suite.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

package/dist/config.d.ts

@@ -0,0 +1,79 @@
+/**
+ * THE VAULT'S OWN CONFIG — `.wyrd/scribe.json`, read through the gate, never through `fs`.
+ *
+ * B2 rules frontmatter opt-in is PER-VAULT rather than per-call, so the answer to "does this vault
+ * carry visible lineage?" is a fact about the vault. That makes this file the vault's, not the
+ * server's, and the vault identity it carries is what the 2026-08-31 identity block requires on
+ * every lineage identity so a record that travels between Mages stays unambiguous.
+ *
+ * ⚠⚠ `.wyrd/` MUST ALREADY EXIST, AND THE SCRIBE WILL NOT CREATE IT. The fence's
+ * `createFileInGrant` requires an existing parent and the fence has no mkdir — deliberately, since
+ * a directory-creating primitive is a second write shape to get right. The alternative to refusing
+ * would be the Scribe mutating a stranger's vault merely by starting, which is the thing D7's
+ * whole tier design exists to keep the user in charge of. So an absent `.wyrd/` refuses and NAMES
+ * the directory to create.
+ *
+ * ⚠ NOTHING IS CACHED ACROSS CALLS. The config is one small read behind a gate that already
+ * resolves the path; a cache would make "which vault am I writing to?" a question about process
+ * history rather than about the vault, and the answer would go stale exactly when someone edits it.
+ * The SOURCE cache in `source.ts` is a different trade — it exists because sources are transcripts.
+ */
+import type { FenceRefusal, FsGate } from 'wyrd-fence';
+import type { ScribeRefusal } from './refusal.js';
+/** The directory the config lives in, grant-relative. Named in the refusal so the user can act. */
+export declare const WYRD_DIR = ".wyrd";
+export declare const CONFIG_PATH = ".wyrd/scribe.json";
+export declare const LINEAGE_PATH = ".wyrd/lineage.jsonl";
+export declare const CONFIG_SCHEMA = "wyrd.scribe/v1";
+/** The ceiling: a config LARGER than this many bytes refuses `SCRIBE_CONFIG_TOO_LARGE`. */
+export declare const CONFIG_CEILING = 16384;
+/**
+ * ⚠ ONE BYTE OVER THE CEILING, NOT AT IT. A read of exactly the ceiling cannot distinguish "the
+ * file is exactly 16,384 bytes" from "the file is larger and this is the first window"; asking for
+ * one more byte makes `truncated` the answer to that question rather than an inference.
+ *
+ * ⚠⚠ AND `truncated` ALONE DID NOT ENFORCE THE CEILING, WHICH A ROUND-5 LENS PROBED LIVE ON
+ * 2026-09-08: a file of EXACTLY 16,385 bytes fits the window whole, so the gate reports
+ * `truncated: false` and the file was accepted one byte past the documented ceiling. `readSlice`
+ * therefore asks both questions — the gate's `truncated`, and `size > CONFIG_CEILING` — and `ST4`
+ * pins both edges by exact byte count (`M28` deletes the size clause).
+ */
+export declare const CONFIG_READ_LIMIT: number;
+export interface ScribeConfig {
+    readonly schema: typeof CONFIG_SCHEMA;
+    readonly vault_id: string;
+    readonly write_frontmatter: boolean;
+}
+/** The serialised form, with a trailing newline so the file is a well-formed text file. */
+export declare function serialiseConfig(config: ScribeConfig): Buffer;
+/**
+ * What a load did, alongside what it loaded.
+ *
+ * ⚠⚠ AN ENVELOPE RATHER THAN A FOURTH KEY ON `ScribeConfig`, AND THE SEPARATION IS THE POINT.
+ * `ScribeConfig` is the vault's own persisted document — exactly three keys, validated key-for-key
+ * by `validate` above, and an unknown key REFUSES. `created` is a fact about THIS INVOCATION and
+ * belongs to no vault, so putting it on the config value would make a per-call fact look like
+ * persisted state and would collide with the very screen that keeps the document honest.
+ */
+export interface LoadedConfig {
+    readonly config: ScribeConfig;
+    /** True when THIS call minted `.wyrd/scribe.json`; false when it read one that already existed. */
+    readonly created: boolean;
+}
+/**
+ * Load the vault's config, minting it if `.wyrd/` exists and the file does not.
+ *
+ * ⚠ THE `.wyrd/` PROBE IS A LIST, NOT A STAT, because the gate exposes no stat and a list is the
+ * operation whose refusal distinguishes the cases this needs: `MISSING` means the directory is
+ * absent, `NOT_A_DIRECTORY` means something else owns the name. Both become
+ * `SCRIBE_NOT_INITIALISED` naming the directory — the user's action is identical either way — but
+ * every OTHER fence refusal (`ESCAPES`, `DENIED`, `ROOT_MOVED`) passes through UNCHANGED, because
+ * translating those into "not initialised" would tell the user to create a directory that already
+ * exists and hide the real reason.
+ *
+ * ⚠ THE LIST PROBE CANNOT SEE AN ALIASED `.wyrd/`, WHICH IS WHY THE CREATE MOVED ABOVE THE READ.
+ * `listDirInGrant` resolves through an in-grant junction on purpose — `.wyrd -> Arc` canonicalises
+ * to a directory inside the grant and lists happily. So does `readFileInGrant`. Only a WRITE path
+ * asks whether the parent is where it was spelled.
+ */
+export declare function loadConfig(gate: FsGate, newUuid: () => string): Promise<LoadedConfig | ScribeRefusal | FenceRefusal>;

package/dist/config.js

@@ -0,0 +1,215 @@
+/**
+ * THE VAULT'S OWN CONFIG — `.wyrd/scribe.json`, read through the gate, never through `fs`.
+ *
+ * B2 rules frontmatter opt-in is PER-VAULT rather than per-call, so the answer to "does this vault
+ * carry visible lineage?" is a fact about the vault. That makes this file the vault's, not the
+ * server's, and the vault identity it carries is what the 2026-08-31 identity block requires on
+ * every lineage identity so a record that travels between Mages stays unambiguous.
+ *
+ * ⚠⚠ `.wyrd/` MUST ALREADY EXIST, AND THE SCRIBE WILL NOT CREATE IT. The fence's
+ * `createFileInGrant` requires an existing parent and the fence has no mkdir — deliberately, since
+ * a directory-creating primitive is a second write shape to get right. The alternative to refusing
+ * would be the Scribe mutating a stranger's vault merely by starting, which is the thing D7's
+ * whole tier design exists to keep the user in charge of. So an absent `.wyrd/` refuses and NAMES
+ * the directory to create.
+ *
+ * ⚠ NOTHING IS CACHED ACROSS CALLS. The config is one small read behind a gate that already
+ * resolves the path; a cache would make "which vault am I writing to?" a question about process
+ * history rather than about the vault, and the answer would go stale exactly when someone edits it.
+ * The SOURCE cache in `source.ts` is a different trade — it exists because sources are transcripts.
+ */
+import { isRefusal } from 'wyrd-fence';
+import { scribeRefuse } from './refusal.js';
+/** The directory the config lives in, grant-relative. Named in the refusal so the user can act. */
+export const WYRD_DIR = '.wyrd';
+export const CONFIG_PATH = '.wyrd/scribe.json';
+export const LINEAGE_PATH = '.wyrd/lineage.jsonl';
+export const CONFIG_SCHEMA = 'wyrd.scribe/v1';
+/** The ceiling: a config LARGER than this many bytes refuses `SCRIBE_CONFIG_TOO_LARGE`. */
+export const CONFIG_CEILING = 16_384;
+/**
+ * ⚠ ONE BYTE OVER THE CEILING, NOT AT IT. A read of exactly the ceiling cannot distinguish "the
+ * file is exactly 16,384 bytes" from "the file is larger and this is the first window"; asking for
+ * one more byte makes `truncated` the answer to that question rather than an inference.
+ *
+ * ⚠⚠ AND `truncated` ALONE DID NOT ENFORCE THE CEILING, WHICH A ROUND-5 LENS PROBED LIVE ON
+ * 2026-09-08: a file of EXACTLY 16,385 bytes fits the window whole, so the gate reports
+ * `truncated: false` and the file was accepted one byte past the documented ceiling. `readSlice`
+ * therefore asks both questions — the gate's `truncated`, and `size > CONFIG_CEILING` — and `ST4`
+ * pins both edges by exact byte count (`M28` deletes the size clause).
+ */
+export const CONFIG_READ_LIMIT = CONFIG_CEILING + 1;
+/** Exactly these three keys. An unknown key REFUSES rather than being ignored — see below. */
+const CONFIG_KEYS = new Set(['schema', 'vault_id', 'write_frontmatter']);
+/**
+ * ⚠ UUID v4, MATCHED STRICTLY. A loose match ("any 36-char string with dashes") would admit a
+ * vault id minted by something other than this code path, and the identity block's whole point is
+ * that a lineage record travelling between Mages is unambiguous. A shape that admits anything is
+ * not an identity scheme.
+ */
+const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+/**
+ * ⚠ THE FENCE'S OWN `isRefusal` IS IMPORTED ABOVE RATHER THAN RE-DECLARED HERE — spec D8, and the
+ * same rule the package manifest states about `createFsGate`. A private copy of the guard that
+ * decides whether a fence result is a refusal is a second definition of the fence's own contract,
+ * free to drift from it silently. ⚠ `stamp.ts` deliberately keeps a private one; read the note
+ * there before assuming it was missed.
+ */
+/**
+ * ⚠ THE CONFIG IS PARSED WITH `Object.create(null)` SEMANTICS IN MIND — `JSON.parse` already
+ * produces a plain object whose prototype is `Object.prototype`, so `__proto__` in the JSON text
+ * lands as an ordinary own key and is caught by the unknown-key screen rather than mutating a
+ * prototype. The screen therefore does double duty and is not merely tidiness.
+ */
+function validate(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return scribeRefuse('SCRIBE_CONFIG_INVALID', `${CONFIG_PATH} is not valid JSON`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return scribeRefuse('SCRIBE_CONFIG_INVALID', `${CONFIG_PATH} must be a JSON object`);
+    }
+    for (const key of Reflect.ownKeys(parsed)) {
+        if (typeof key !== 'string' || !CONFIG_KEYS.has(key)) {
+            return scribeRefuse('SCRIBE_CONFIG_INVALID', `${CONFIG_PATH} carries an unknown key`);
+        }
+    }
+    const view = parsed;
+    if (view.schema !== CONFIG_SCHEMA) {
+        return scribeRefuse('SCRIBE_CONFIG_INVALID', `${CONFIG_PATH} must declare schema "${CONFIG_SCHEMA}"`);
+    }
+    if (typeof view.vault_id !== 'string' || !UUID_V4.test(view.vault_id)) {
+        return scribeRefuse('SCRIBE_CONFIG_INVALID', `${CONFIG_PATH} must carry a v4 UUID vault_id`);
+    }
+    if (typeof view.write_frontmatter !== 'boolean') {
+        return scribeRefuse('SCRIBE_CONFIG_INVALID', `${CONFIG_PATH} must carry a boolean write_frontmatter`);
+    }
+    return Object.freeze({
+        schema: CONFIG_SCHEMA,
+        vault_id: view.vault_id,
+        write_frontmatter: view.write_frontmatter
+    });
+}
+/**
+ * The minted default. `write_frontmatter` is FALSE, matching D7's "defaulting to the safest":
+ * stamping a stranger's page bytes is the more visible act, so it is the one they opt into.
+ */
+function mint(vaultId) {
+    return Object.freeze({ schema: CONFIG_SCHEMA, vault_id: vaultId, write_frontmatter: false });
+}
+/** The serialised form, with a trailing newline so the file is a well-formed text file. */
+export function serialiseConfig(config) {
+    return Buffer.from(`${JSON.stringify({ schema: config.schema, vault_id: config.vault_id, write_frontmatter: config.write_frontmatter }, null, 2)}\n`, 'utf8');
+}
+/**
+ * Load the vault's config, minting it if `.wyrd/` exists and the file does not.
+ *
+ * ⚠ THE `.wyrd/` PROBE IS A LIST, NOT A STAT, because the gate exposes no stat and a list is the
+ * operation whose refusal distinguishes the cases this needs: `MISSING` means the directory is
+ * absent, `NOT_A_DIRECTORY` means something else owns the name. Both become
+ * `SCRIBE_NOT_INITIALISED` naming the directory — the user's action is identical either way — but
+ * every OTHER fence refusal (`ESCAPES`, `DENIED`, `ROOT_MOVED`) passes through UNCHANGED, because
+ * translating those into "not initialised" would tell the user to create a directory that already
+ * exists and hide the real reason.
+ *
+ * ⚠ THE LIST PROBE CANNOT SEE AN ALIASED `.wyrd/`, WHICH IS WHY THE CREATE MOVED ABOVE THE READ.
+ * `listDirInGrant` resolves through an in-grant junction on purpose — `.wyrd -> Arc` canonicalises
+ * to a directory inside the grant and lists happily. So does `readFileInGrant`. Only a WRITE path
+ * asks whether the parent is where it was spelled.
+ */
+export async function loadConfig(gate, newUuid) {
+    const dir = await gate.listDirInGrant(WYRD_DIR);
+    if (isRefusal(dir)) {
+        if (dir.reason === 'MISSING' || dir.reason === 'NOT_A_DIRECTORY') {
+            return scribeRefuse('SCRIBE_NOT_INITIALISED', `this vault has no ${WYRD_DIR}/ directory; create ${WYRD_DIR}/ inside the vault and retry`);
+        }
+        return dir;
+    }
+    /**
+     * ⚠⚠ THE CREATE IS ATTEMPTED FIRST, AHEAD OF THE READ, AND THE ORDER IS THE SECURITY PROPERTY.
+     *
+     * The fence's `resolveNew` compares the resolved parent against the spelled one BEFORE it
+     * probes the leaf, so a `.wyrd -> Arc` junction is refused `PARENT_ALIAS` ahead of `EXISTS` —
+     * ahead of any open, and ahead of any page write. Read-first cannot reach that: an existing
+     * `Arc/scribe.json` answers the read successfully and the alias is never questioned, so the
+     * page is created and only the LEDGER APPEND refuses, leaving an orphan page. That orphan is
+     * the defect this ordering exists to close, and closing it needs no published API change.
+     *
+     * ⚠ `EXISTS` IS NOT AN ERROR HERE, AND THAT WAS ALREADY TRUE BEFORE THE HOIST. Two Scribe
+     * processes granted the same vault reach this line together; the fence's `wx` open makes
+     * exactly one of them the winner, and the loser must adopt the winner's id rather than refuse.
+     * Minting a second id would give one vault two identities, which is the ambiguity the identity
+     * block exists to prevent — arriving through a race instead of through a schema. What the hoist
+     * changes is that `EXISTS` is now the ORDINARY path rather than the racing one.
+     *
+     * ⚠⚠ AND THIS CREATE IS NOW THE STAMP PATH'S FIRST WRITE, WHICH THE HEADER OF `stamp.ts` USED
+     * TO DENY. Until 2026-09-08 that header said NOTHING was written until every source had
+     * resolved and every limit had passed, and named the page as the first write. Both sentences
+     * are narrowed there now, and the truth is stated here at the site that changed it: on an
+     * uninitialised vault this line creates `.wyrd/scribe.json` BEFORE a single source has been
+     * read. What the ordering still buys is the claim worth having — no PAGE, meaning no byte of
+     * caller-supplied content, exists until every check that CAN be decided without one has passed.
+     * This file is the server's own bookkeeping at a fixed path inside a directory the user made
+     * for it, and `writePage` reports it back through `config_created` rather than leaving it to be
+     * inferred.
+     *
+     * ⚠ THAT CLAUSE READ "until every check has passed" UNTIL 2026-09-08 AND IS NARROWED, because
+     * one check runs after the page exists: the final ledger-line size re-check over the canonical
+     * path (`stamp.ts` step 9), which leaves an ORPHAN page when it fires. Nothing about THIS file
+     * changes — the config mint is still the first write and still reported — but a sentence here
+     * that overstates the page guarantee is read as the guarantee, so it says what holds.
+     *
+     * ⚠⚠ THE MINTER RUNS ON EVERY LOAD, AND `loadConfig` RUNS ON EVERY STAMP THAT REACHES STEP 4
+     * (`stamp.ts`; steps 1-3 can refuse before it), SO IT RUNS AT MOST ONCE PER WRITE. Two
+     * consequences, both deliberate:
+     *
+     *   · One speculative `newUuid()` per stamp is discarded when the config already exists. That
+     *     is `crypto.randomUUID` in production — no I/O, no syscall worth naming.
+     *   · An INJECTED `newUuid` that THROWS now throws on a stamp against a VALID EXISTING config,
+     *     where before it threw only when the config was missing. It is NOT caught here, and that
+     *     is a ruling rather than an omission: there is no honest reason to convert it to.
+     *     `SCRIBE_CONFIG_INVALID` would blame a config that is perfectly valid, and a fence reason
+     *     would attribute a Scribe-side fault to the fence. Catching it behind a fallback to the
+     *     read-first order would be worse still — a containment check that switches itself off when
+     *     an injected function misbehaves is not a check. The default minter does not throw; a
+     *     throwing one is a broken injection, and this path reports it as one.
+     */
+    const minted = mint(newUuid());
+    const created = await gate.createFileInGrant(CONFIG_PATH, serialiseConfig(minted));
+    // ⚠ `created: true` IS READ OFF THE ONE BRANCH THAT ACTUALLY CREATED, never inferred later from
+    // the file's presence. By the time a caller could stat it, a concurrent process minting the same
+    // vault's config makes "the file is there" true for both of them and true for neither's call.
+    if (!isRefusal(created))
+        return Object.freeze({ config: minted, created: true });
+    if (created.reason !== 'EXISTS')
+        return created;
+    const slice = await gate.readFileInGrant(CONFIG_PATH, 0, CONFIG_READ_LIMIT);
+    if (isRefusal(slice))
+        return slice;
+    // ⚠ NARROWED ON `ok`, NOT THROUGH THE FENCE'S `isRefusal`. That guard's predicate says
+    // `FenceRefusal`, and what `readSlice` can return here is a SCRIBE refusal — borrowing the
+    // fence's guard would typecheck by mislabelling the value's own union.
+    const read = readSlice(slice);
+    if ('ok' in read)
+        return read;
+    return Object.freeze({ config: read, created: false });
+}
+function readSlice(slice) {
+    // ⚠ TWO QUESTIONS, BECAUSE EACH ALONE WAS WRONG IN ONE DIRECTION. `truncated` is the gate's
+    // own answer to "is there more than the window holds", and it stays because the gate trims a
+    // window back to a codepoint boundary, so a byte count compared against the WINDOW can disagree
+    // with the gate about whether more remains. But a file that fits the window is not thereby
+    // under the ceiling: the window is one byte wider than the ceiling on purpose (see
+    // `CONFIG_READ_LIMIT`), so a file of exactly `CONFIG_CEILING + 1` bytes came back
+    // `truncated: false` and was accepted until 2026-09-08. `slice.size` is the file's whole
+    // length as the gate measured it, independent of any trimming, so comparing IT against the
+    // ceiling is exact.
+    if (slice.truncated || slice.size > CONFIG_CEILING) {
+        return scribeRefuse('SCRIBE_CONFIG_TOO_LARGE', `${CONFIG_PATH} is larger than ${CONFIG_CEILING} bytes`);
+    }
+    return validate(slice.bytes.toString('utf8'));
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAIvC,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,mGAAmG;AACnG,MAAM,CAAC,MAAM,QAAQ,GAAG,OAAO,CAAC;AAChC,MAAM,CAAC,MAAM,WAAW,GAAG,mBAAmB,CAAC;AAC/C,MAAM,CAAC,MAAM,YAAY,GAAG,qBAAqB,CAAC;AAElD,MAAM,CAAC,MAAM,aAAa,GAAG,gBAAgB,CAAC;AAE9C,2FAA2F;AAC3F,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC;AAErC;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,cAAc,GAAG,CAAC,CAAC;AAQpD,8FAA8F;AAC9F,MAAM,WAAW,GAAwB,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,UAAU,EAAE,mBAAmB,CAAC,CAAC,CAAC;AAE9F;;;;;GAKG;AACH,MAAM,OAAO,GAAG,uEAAuE,CAAC;AAExF;;;;;;GAMG;AAEH;;;;;GAKG;AACH,SAAS,QAAQ,CAAC,IAAY;IAC1B,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACD,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,YAAY,CAAC,uBAAuB,EAAE,GAAG,WAAW,oBAAoB,CAAC,CAAC;IACrF,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACzE,OAAO,YAAY,CAAC,uBAAuB,EAAE,GAAG,WAAW,wBAAwB,CAAC,CAAC;IACzF,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACxC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACnD,OAAO,YAAY,CAAC,uBAAuB,EAAE,GAAG,WAAW,yBAAyB,CAAC,CAAC;QAC1F,CAAC;IACL,CAAC;IACD,MAAM,IAAI,GAAG,MAA+E,CAAC;IAC7F,IAAI,IAAI,CAAC,MAAM,KAAK,aAAa,EAAE,CAAC;QAChC,OAAO,YAAY,CAAC,uBAAuB,EAAE,GAAG,WAAW,yBAAyB,aAAa,GAAG,CAAC,CAAC;IAC1G,CAAC;IACD,IAAI,OAAO,IAAI,CAAC,QAAQ,KAAK,QAAQ,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QACpE,OAAO,YAAY,CAAC,uBAAuB,EAAE,GAAG,WAAW,gCAAgC,CAAC,CAAC;IACjG,CAAC;IACD,IAAI,OAAO,IAAI,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;QAC9C,OAAO,YAAY,CAAC,uBAAuB,EAAE,GAAG,WAAW,yCAAyC,CAAC,CAAC;IAC1G,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC;QACjB,MAAM,EAAE,aAAa;QACrB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,iBAAiB,EAAE,IAAI,CAAC,iBAAiB;KAC5C,CAAC,CAAC;AACP,CAAC;AAED;;;GAGG;AACH,SAAS,IAAI,CAAC,OAAe;IACzB,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,OAAO,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC,CAAC;AACjG,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,eAAe,CAAC,MAAoB;IAChD,OAAO,MAAM,CAAC,IAAI,CACd,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,iBAAiB,EAAE,MAAM,CAAC,iBAAiB,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EACjI,MAAM,CACT,CAAC;AACN,CAAC;AAiBD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC5B,IAAY,EACZ,OAAqB;IAErB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;IAChD,IAAI,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC;QACjB,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,IAAI,GAAG,CAAC,MAAM,KAAK,iBAAiB,EAAE,CAAC;YAC/D,OAAO,YAAY,CACf,wBAAwB,EACxB,qBAAqB,QAAQ,uBAAuB,QAAQ,8BAA8B,CAC7F,CAAC;QACN,CAAC;QACD,OAAO,GAAG,CAAC;IACf,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgDG;IACH,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IAC/B,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,iBAAiB,CAAC,WAAW,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC;IACnF,gGAAgG;IAChG,iGAAiG;IACjG,8FAA8F;IAC9F,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;QAAE,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;IACjF,IAAI,OAAO,CAAC,MAAM,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC;IAEhD,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,WAAW,EAAE,CAAC,EAAE,iBAAiB,CAAC,CAAC;IAC5E,IAAI,SAAS,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACnC,uFAAuF;IACvF,2FAA2F;IAC3F,uEAAuE;IACvE,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;IAC9B,IAAI,IAAI,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IAC9B,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;AAC3D,CAAC;AAED,SAAS,SAAS,CAAC,KAAY;IAC3B,4FAA4F;IAC5F,6FAA6F;IAC7F,gGAAgG;IAChG,2FAA2F;IAC3F,mFAAmF;IACnF,kFAAkF;IAClF,yFAAyF;IACzF,2FAA2F;IAC3F,oBAAoB;IACpB,IAAI,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,IAAI,GAAG,cAAc,EAAE,CAAC;QACjD,OAAO,YAAY,CACf,yBAAyB,EACzB,GAAG,WAAW,mBAAmB,cAAc,QAAQ,CAC1D,CAAC;IACN,CAAC;IACD,OAAO,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;AAClD,CAAC"}