@graftsync/spec 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brandon Roberts
+
+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/dist/document.d.ts

@@ -0,0 +1,45 @@
+export interface SplitDocument {
+    /** Raw YAML between the fences (no fences). */
+    frontmatter: string;
+    /** Everything after the closing fence. */
+    body: string;
+    /** Line number (1-based) where the body starts. */
+    bodyLine: number;
+}
+/** Split a graft.md file into frontmatter YAML and markdown body. */
+export declare function splitFrontmatter(text: string): SplitDocument | null;
+export declare function joinFrontmatter(frontmatter: string, body: string): string;
+export interface Section {
+    /** Heading text, trimmed. */
+    title: string;
+    /** Section content (without the heading line), trimmed. */
+    content: string;
+    /** 1-based line of the heading within the body. */
+    line: number;
+}
+/** Extract level-2 (`## `) sections from a markdown body. Ignores headings inside code fences. */
+export declare function parseSections(body: string): Section[];
+export declare function findSection(sections: Section[], title: string): Section | undefined;
+/**
+ * Comment- and formatting-preserving editor for graft.md.
+ * Used for bookkeeping (status, verified version, variants, history) so that
+ * hand-written YAML comments and the agent-facing body survive tool edits.
+ */
+export declare class GraftDocumentEditor {
+    private doc;
+    private body;
+    constructor(text: string);
+    get(path: (string | number)[]): unknown;
+    set(path: (string | number)[], value: unknown): this;
+    setStatus(status: string): this;
+    setVerified(version: string): this;
+    /** Append a variant entry. Existing entries are left untouched except where `rangeUpdates` says so. */
+    addVariant(variant: {
+        range: string;
+        module: string;
+    }, rangeUpdates?: Map<number, string>): this;
+    /** Append a bullet to the `## History` section, creating it if missing. */
+    appendHistory(entry: string, date?: string): this;
+    toString(): string;
+}
+//# sourceMappingURL=document.d.ts.map

package/dist/document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,qEAAqE;AACrE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAWnE;AAED,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAGzE;AAED,MAAM,WAAW,OAAO;IACtB,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,kGAAkG;AAClG,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAwBrD;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAGnF;AAED;;;;GAIG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,GAAG,CAAW;IACtB,OAAO,CAAC,IAAI,CAAS;IAErB,YAAY,IAAI,EAAE,MAAM,EAMvB;IAED,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,GAAG,OAAO,CAGtC;IAED,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAGnD;IAED,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAE9B;IAED,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEjC;IAED,uGAAuG;IACvG,UAAU,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,YAAY,GAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAa,GAAG,IAAI,CAU1G;IAED,2EAA2E;IAC3E,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,MAA8C,GAAG,IAAI,CAoCvF;IAED,QAAQ,IAAI,MAAM,CAEjB;CACF"}

package/dist/document.js

@@ -0,0 +1,145 @@
+import { parseDocument } from 'yaml';
+const FENCE = '---';
+/** Split a graft.md file into frontmatter YAML and markdown body. */
+export function splitFrontmatter(text) {
+    const normalized = text.replace(/^/, '');
+    const lines = normalized.split(/\r?\n/);
+    if (lines[0]?.trim() !== FENCE)
+        return null;
+    const close = lines.findIndex((line, i) => i > 0 && line.trim() === FENCE);
+    if (close === -1)
+        return null;
+    return {
+        frontmatter: lines.slice(1, close).join('\n'),
+        body: lines.slice(close + 1).join('\n'),
+        bodyLine: close + 2,
+    };
+}
+export function joinFrontmatter(frontmatter, body) {
+    const fm = frontmatter.endsWith('\n') ? frontmatter : `${frontmatter}\n`;
+    return `${FENCE}\n${fm}${FENCE}\n${body}`;
+}
+/** Extract level-2 (`## `) sections from a markdown body. Ignores headings inside code fences. */
+export function parseSections(body) {
+    const lines = body.split(/\r?\n/);
+    const sections = [];
+    let current = null;
+    let inFence = false;
+    const flush = (end) => {
+        if (!current)
+            return;
+        sections.push({
+            title: current.title,
+            line: current.line,
+            content: lines.slice(current.start, end).join('\n').trim(),
+        });
+    };
+    lines.forEach((line, i) => {
+        if (/^\s*(```|~~~)/.test(line))
+            inFence = !inFence;
+        if (inFence)
+            return;
+        const m = /^##\s+(.+?)\s*#*\s*$/.exec(line);
+        if (m && !line.startsWith('###')) {
+            flush(i);
+            current = { title: m[1], line: i + 1, start: i + 1 };
+        }
+    });
+    flush(lines.length);
+    return sections;
+}
+export function findSection(sections, title) {
+    const wanted = title.toLowerCase();
+    return sections.find((s) => s.title.toLowerCase() === wanted);
+}
+/**
+ * Comment- and formatting-preserving editor for graft.md.
+ * Used for bookkeeping (status, verified version, variants, history) so that
+ * hand-written YAML comments and the agent-facing body survive tool edits.
+ */
+export class GraftDocumentEditor {
+    doc;
+    body;
+    constructor(text) {
+        const split = splitFrontmatter(text);
+        if (!split)
+            throw new Error('graft.md has no YAML frontmatter');
+        this.doc = parseDocument(split.frontmatter);
+        if (this.doc.errors.length)
+            throw new Error(`invalid frontmatter YAML: ${this.doc.errors[0].message}`);
+        this.body = split.body;
+    }
+    get(path) {
+        const v = this.doc.getIn(path);
+        return v && typeof v === 'object' && 'toJSON' in v ? v.toJSON() : v;
+    }
+    set(path, value) {
+        this.doc.setIn(path, value);
+        return this;
+    }
+    setStatus(status) {
+        return this.set(['status'], status);
+    }
+    setVerified(version) {
+        return this.set(['rootstock', 'verified'], version);
+    }
+    /** Append a variant entry. Existing entries are left untouched except where `rangeUpdates` says so. */
+    addVariant(variant, rangeUpdates = new Map()) {
+        for (const [index, range] of rangeUpdates)
+            this.doc.setIn(['variants', index, 'range'], range);
+        const node = this.doc.createNode({ range: variant.range, module: variant.module });
+        const seq = this.doc.getIn(['variants']);
+        if (seq && typeof seq === 'object' && 'add' in seq) {
+            seq.add(node);
+        }
+        else {
+            this.doc.setIn(['variants'], [variant]);
+        }
+        return this;
+    }
+    /** Append a bullet to the `## History` section, creating it if missing. */
+    appendHistory(entry, date = new Date().toISOString().slice(0, 10)) {
+        const bullet = `- ${date}: ${entry.trim().replace(/\n+/g, ' ')}`;
+        const lines = this.body.split('\n');
+        let start = -1;
+        let inFence = false;
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (/^\s*(```|~~~)/.test(line))
+                inFence = !inFence;
+            if (!inFence && /^##\s+history\s*$/i.test(line.trim())) {
+                start = i;
+                break;
+            }
+        }
+        if (start === -1) {
+            const trimmed = this.body.replace(/\s*$/, '');
+            this.body = `${trimmed}\n\n## History\n\n${bullet}\n`;
+            return this;
+        }
+        // Find end of the History section: next level-1/2 heading (outside code fences).
+        let end = lines.length;
+        inFence = false;
+        for (let i = start + 1; i < lines.length; i++) {
+            const line = lines[i];
+            if (/^\s*(```|~~~)/.test(line))
+                inFence = !inFence;
+            if (!inFence && /^#{1,2}\s/.test(line)) {
+                end = i;
+                break;
+            }
+        }
+        // Insert after the last non-blank line of the section.
+        let insertAt = end;
+        while (insertAt > start + 1 && lines[insertAt - 1].trim() === '')
+            insertAt--;
+        const needsBlank = insertAt === start + 1;
+        lines.splice(insertAt, 0, ...(needsBlank ? ['', bullet] : [bullet]));
+        this.body = lines.join('\n');
+        return this;
+    }
+    toString() {
+        return joinFrontmatter(this.doc.toString(), this.body);
+    }
+}
+//# sourceMappingURL=document.js.map

package/dist/document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.js","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './schema.js';
+export * from './document.js';
+export * from './parse.js';
+export * from './template.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from './schema.js';
+export * from './document.js';
+export * from './parse.js';
+export * from './template.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC"}

package/dist/parse.d.ts

@@ -0,0 +1,34 @@
+import { type Section } from './document.js';
+import { type GraftFrontmatter } from './schema.js';
+export type DiagnosticSeverity = 'error' | 'warning';
+export interface Diagnostic {
+    severity: DiagnosticSeverity;
+    /** Stable machine-readable code, e.g. `frontmatter/invalid`, `body/missing-section`. */
+    code: string;
+    message: string;
+    /** Dotted frontmatter path or section name the diagnostic refers to. */
+    path?: string;
+}
+export interface ParsedGraft {
+    frontmatter: GraftFrontmatter;
+    body: string;
+    sections: Section[];
+}
+export interface ParseResult {
+    /** Present whenever frontmatter passed schema validation (even if other errors exist). */
+    graft?: ParsedGraft;
+    diagnostics: Diagnostic[];
+    /** True when there are no error-severity diagnostics. */
+    ok: boolean;
+}
+export interface ParseOptions {
+    /** Name of the directory containing graft.md; must equal `id` when given. */
+    directoryName?: string;
+}
+/** Parse and validate the text of a graft.md file. Never throws on invalid input. */
+export declare function parseGraft(text: string, options?: ParseOptions): ParseResult;
+/** Return the variant whose range contains `version` (prereleases included), if any. */
+export declare function selectVariant<V extends {
+    range: string;
+}>(variants: readonly V[], version: string): V | undefined;
+//# sourceMappingURL=parse.d.ts.map

package/dist/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgD,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AAC3F,OAAO,EAA6C,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/F,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,SAAS,CAAC;AAErD,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,wFAAwF;IACxF,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,gBAAgB,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,0FAA0F;IAC1F,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,yDAAyD;IACzD,EAAE,EAAE,OAAO,CAAC;CACb;AAED,MAAM,WAAW,YAAY;IAC3B,6EAA6E;IAC7E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,qFAAqF;AACrF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,WAAW,CAqFhF;AAwCD,wFAAwF;AACxF,wBAAgB,aAAa,CAAC,CAAC,SAAS;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAEjH"}

package/dist/parse.js

@@ -0,0 +1,128 @@
+import semver from 'semver';
+import { parse as parseYaml } from 'yaml';
+import { parseSections, splitFrontmatter, findSection } from './document.js';
+import { GraftFrontmatterSchema, REQUIRED_SECTIONS } from './schema.js';
+/** Parse and validate the text of a graft.md file. Never throws on invalid input. */
+export function parseGraft(text, options = {}) {
+    const diagnostics = [];
+    const done = (graft) => ({
+        graft,
+        diagnostics,
+        ok: !diagnostics.some((d) => d.severity === 'error'),
+    });
+    const split = splitFrontmatter(text);
+    if (!split) {
+        diagnostics.push({
+            severity: 'error',
+            code: 'frontmatter/missing',
+            message: 'graft.md must start with YAML frontmatter delimited by `---` lines',
+        });
+        return done();
+    }
+    let raw;
+    try {
+        raw = parseYaml(split.frontmatter);
+    }
+    catch (err) {
+        diagnostics.push({
+            severity: 'error',
+            code: 'frontmatter/yaml',
+            message: `frontmatter is not valid YAML: ${err.message}`,
+        });
+        return done();
+    }
+    const result = GraftFrontmatterSchema.safeParse(raw ?? {});
+    if (!result.success) {
+        for (const issue of result.error.issues) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'frontmatter/invalid',
+                path: issue.path.join('.'),
+                message: `${issue.path.join('.') || '(root)'}: ${issue.message}`,
+            });
+        }
+    }
+    const sections = parseSections(split.body);
+    for (const name of REQUIRED_SECTIONS) {
+        const section = findSection(sections, name);
+        if (!section) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'body/missing-section',
+                path: name,
+                message: `missing required section "## ${name}"`,
+            });
+        }
+        else if (!section.content) {
+            diagnostics.push({
+                severity: 'warning',
+                code: 'body/empty-section',
+                path: name,
+                message: `section "## ${name}" is empty; agents rely on it during sync`,
+            });
+        }
+    }
+    if (!result.success)
+        return done();
+    const fm = result.data;
+    if (options.directoryName !== undefined && options.directoryName !== fm.id) {
+        diagnostics.push({
+            severity: 'error',
+            code: 'frontmatter/id-mismatch',
+            path: 'id',
+            message: `id "${fm.id}" must match its directory name "${options.directoryName}"`,
+        });
+    }
+    diagnostics.push(...checkVariantRanges(fm));
+    if (fm.mechanism === 'fork' && !fm.fork) {
+        diagnostics.push({
+            severity: 'error',
+            code: 'frontmatter/fork-missing',
+            path: 'fork',
+            message: 'mechanism "fork" needs a `fork:` block ({ repo, upstream, tag })',
+        });
+    }
+    return done({ frontmatter: fm, body: split.body, sections });
+}
+function checkVariantRanges(fm) {
+    const out = [];
+    const opts = { includePrerelease: true };
+    fm.variants.forEach((a, i) => {
+        fm.variants.slice(i + 1).forEach((b, j) => {
+            if (semver.intersects(a.range, b.range, opts)) {
+                out.push({
+                    severity: 'error',
+                    code: 'variants/overlap',
+                    path: `variants.${i}`,
+                    message: `variant ranges "${a.range}" (variants.${i}) and "${b.range}" (variants.${i + j + 1}) overlap; a version must select exactly one variant`,
+                });
+            }
+        });
+    });
+    const modules = new Set();
+    fm.variants.forEach((v, i) => {
+        if (modules.has(v.module)) {
+            out.push({
+                severity: 'error',
+                code: 'variants/duplicate-module',
+                path: `variants.${i}.module`,
+                message: `variant module "${v.module}" is listed more than once`,
+            });
+        }
+        modules.add(v.module);
+    });
+    if (!fm.variants.some((v) => semver.satisfies(fm.rootstock.verified, v.range, opts))) {
+        out.push({
+            severity: 'warning',
+            code: 'variants/verified-uncovered',
+            path: 'rootstock.verified',
+            message: `verified version ${fm.rootstock.verified} is not covered by any variant range`,
+        });
+    }
+    return out;
+}
+/** Return the variant whose range contains `version` (prereleases included), if any. */
+export function selectVariant(variants, version) {
+    return variants.find((v) => semver.satisfies(version, v.range, { includePrerelease: true }));
+}
+//# sourceMappingURL=parse.js.map

package/dist/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"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"}

package/dist/schema.d.ts

@@ -0,0 +1,90 @@
+import { z } from 'zod';
+/** Lifecycle of a graft. */
+export declare const GRAFT_STATUSES: readonly ['applied', 'conflicted', 'upstreamed', 'obsolete'];
+export type GraftStatus = (typeof GRAFT_STATUSES)[number];
+/** Statuses for which tooling still applies and verifies the graft. */
+export declare const ACTIVE_STATUSES: readonly GraftStatus[];
+/** Body sections every graft.md must contain, in recommended order. */
+export declare const REQUIRED_SECTIONS: readonly ['Why', 'Invariants', 'Where to look', 'Anchors', 'History'];
+export type RequiredSection = (typeof REQUIRED_SECTIONS)[number];
+export declare const GRAFT_ID_PATTERN: RegExp;
+export declare const RootstockSchema: z.ZodObject<{
+    package: z.ZodString;
+    verified: z.ZodString;
+}, z.core.$strip>;
+export declare const VariantRefSchema: z.ZodObject<{
+    range: z.ZodString;
+    module: z.ZodString;
+}, z.core.$strip>;
+export declare const OracleSchema: z.ZodObject<{
+    command: z.ZodString;
+    modes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const ForkSchema: z.ZodObject<{
+    repo: z.ZodString;
+    upstream: z.ZodString;
+    tag: z.ZodDefault<z.ZodString>;
+    track: z.ZodOptional<z.ZodString>;
+    dir: z.ZodOptional<z.ZodString>;
+    install: z.ZodDefault<z.ZodEnum<{
+        none: "none";
+        package: "package";
+    }>>;
+    build: z.ZodOptional<z.ZodString>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const GeneratorSchema: z.ZodObject<{
+    command: z.ZodString;
+    timeout: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const GraftFrontmatterSchema: z.ZodObject<{
+    id: z.ZodString;
+    rootstock: z.ZodObject<{
+        package: z.ZodString;
+        verified: z.ZodString;
+    }, z.core.$strip>;
+    mechanism: z.ZodString;
+    targets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    variants: z.ZodArray<z.ZodObject<{
+        range: z.ZodString;
+        module: z.ZodString;
+    }, z.core.$strip>>;
+    oracle: z.ZodObject<{
+        command: z.ZodString;
+        modes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        timeout: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    generator: z.ZodOptional<z.ZodObject<{
+        command: z.ZodString;
+        timeout: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    fork: z.ZodOptional<z.ZodObject<{
+        repo: z.ZodString;
+        upstream: z.ZodString;
+        tag: z.ZodDefault<z.ZodString>;
+        track: z.ZodOptional<z.ZodString>;
+        dir: z.ZodOptional<z.ZodString>;
+        install: z.ZodDefault<z.ZodEnum<{
+            none: "none";
+            package: "package";
+        }>>;
+        build: z.ZodOptional<z.ZodString>;
+        timeout: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    status: z.ZodDefault<z.ZodEnum<{
+        applied: "applied";
+        conflicted: "conflicted";
+        obsolete: "obsolete";
+        upstreamed: "upstreamed";
+    }>>;
+}, z.core.$strip>;
+export type Rootstock = z.infer<typeof RootstockSchema>;
+export type VariantRef = z.infer<typeof VariantRefSchema>;
+export type Oracle = z.infer<typeof OracleSchema>;
+export type ForkConfig = z.infer<typeof ForkSchema>;
+export type Generator = z.infer<typeof GeneratorSchema>;
+export type GraftFrontmatter = z.infer<typeof GraftFrontmatterSchema>;
+/** Frontmatter as authored, before defaults are applied. */
+export type GraftFrontmatterInput = z.input<typeof GraftFrontmatterSchema>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,4BAA4B;AAC5B,eAAO,MAAM,cAAc,YAAI,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,CAAU,CAAC;AAC3F,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1D,uEAAuE;AACvE,eAAO,MAAM,eAAe,EAAE,SAAS,WAAW,EAA8B,CAAC;AAEjF,uEAAuE;AACvE,eAAO,MAAM,iBAAiB,YAAI,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,SAAS,CAAU,CAAC;AACvG,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjE,eAAO,MAAM,gBAAgB,QAAyB,CAAC;AAYvD,eAAO,MAAM,eAAe;;;iBAK1B,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;iBAK3B,CAAC;AAEH,eAAO,MAAM,YAAY;;;;iBAUvB,CAAC;AAEH,eAAO,MAAM,UAAU;;;;;;;;;;;;iBA4BrB,CAAC;AAEH,eAAO,MAAM,eAAe;;;iBAe1B,CAAC;AAEH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAcjC,CAAC;AAEH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AACxD,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC1D,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAClD,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AACpD,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AACxD,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AACtE,4DAA4D;AAC5D,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC"}

package/dist/schema.js

@@ -0,0 +1,101 @@
+import semver from 'semver';
+import { z } from 'zod';
+/** Lifecycle of a graft. */
+export const GRAFT_STATUSES = ['applied', 'conflicted', 'upstreamed', 'obsolete'];
+/** Statuses for which tooling still applies and verifies the graft. */
+export const ACTIVE_STATUSES = ['applied', 'conflicted'];
+/** Body sections every graft.md must contain, in recommended order. */
+export const REQUIRED_SECTIONS = ['Why', 'Invariants', 'Where to look', 'Anchors', 'History'];
+export const GRAFT_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+const semverVersion = z
+    .string()
+    .refine((v) => semver.valid(v) !== null, { message: 'must be a valid semver version (e.g. "4.2.0")' });
+const semverRange = z
+    .string()
+    .refine((r) => semver.validRange(r, { includePrerelease: true }) !== null, {
+    message: 'must be a valid semver range (e.g. ">=4.0.0 <5.0.0")',
+});
+export const RootstockSchema = z.object({
+    /** npm package name of the upstream. */
+    package: z.string().min(1),
+    /** Last upstream version this graft was verified against by its oracle. */
+    verified: semverVersion,
+});
+export const VariantRefSchema = z.object({
+    /** Upstream version range this variant is valid for. */
+    range: semverRange,
+    /** Path to the variant module, relative to the graft directory. */
+    module: z.string().min(1),
+});
+export const OracleSchema = z.object({
+    /**
+     * Shell command that exits 0 iff the graft's invariants hold.
+     * Runs once per mode, with GRAFT_MODE set. `{mode}` in the command is substituted.
+     */
+    command: z.string().min(1),
+    /** Modes to run the oracle in (e.g. dev, build). */
+    modes: z.array(z.string().min(1)).min(1).default(['default']),
+    /** Optional timeout per mode, in seconds. */
+    timeout: z.number().int().positive().optional(),
+});
+export const ForkSchema = z.object({
+    /** Git URL (or path, relative to the project root) of the fork that carries the modification as commits. */
+    repo: z.string().min(1),
+    /** Git URL of the upstream source repository the fork tracks. */
+    upstream: z.string().min(1),
+    /** Upstream release tag for a version; `{version}` is substituted. */
+    tag: z
+        .string()
+        .min(1)
+        .default('v{version}')
+        .refine((t) => t.includes('{version}'), { message: 'must contain {version}' }),
+    /**
+     * Repo mode: an upstream branch to follow (e.g. `main`). `graft outdated` then offers its tip as
+     * `<version>+<commit>` instead of the newest release tag.
+     */
+    track: z.string().min(1).optional(),
+    /** Package directory inside the repositories (for monorepos). Default: the repo root. */
+    dir: z.string().min(1).optional(),
+    /**
+     * How the rebased fork is consumed. `package` (default): built, packed and installed into the
+     * project as a vendored tarball. `none`: the fork is the product itself (e.g. a translated docs
+     * site); nothing is installed and the oracle runs in the rebased checkout.
+     */
+    install: z.enum(['package', 'none']).default('package'),
+    /** Command run in the package directory of the rebased source before packing (e.g. `npm ci && npm run build`). */
+    build: z.string().min(1).optional(),
+    /** Optional timeout for the build, in seconds. */
+    timeout: z.number().int().positive().optional(),
+});
+export const GeneratorSchema = z.object({
+    /**
+     * Shell command that writes a new variant module for an upstream version, run from the
+     * project root. `{version}` is replaced with the target upstream version and `{out}` with
+     * the path to write the variant to (also exported as GRAFT_UPSTREAM_VERSION and
+     * GRAFT_VARIANT_OUT). `graft sync` runs it when no existing variant fits a new version.
+     */
+    command: z
+        .string()
+        .min(1)
+        .refine((c) => c.includes('{out}') || c.includes('GRAFT_VARIANT_OUT'), {
+        message: 'must write the variant to {out} (or $GRAFT_VARIANT_OUT)',
+    }),
+    /** Optional timeout, in seconds. */
+    timeout: z.number().int().positive().optional(),
+});
+export const GraftFrontmatterSchema = z.object({
+    id: z.string().regex(GRAFT_ID_PATTERN, 'must be lowercase kebab-case'),
+    rootstock: RootstockSchema,
+    /** Name of the mechanism adapter that applies this graft (e.g. patch). */
+    mechanism: z.string().min(1),
+    /** Upstream files the mechanism operates on, relative to the package root. */
+    targets: z.array(z.string().min(1)).optional(),
+    variants: z.array(VariantRefSchema).min(1),
+    oracle: OracleSchema,
+    /** Optional command that regenerates a variant for a new upstream version. */
+    generator: GeneratorSchema.optional(),
+    /** For `mechanism: fork`: where the modification lives as commits, and how to build it. */
+    fork: ForkSchema.optional(),
+    status: z.enum(GRAFT_STATUSES).default('applied'),
+});
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}

package/dist/template.d.ts

@@ -0,0 +1,4 @@
+import type { GraftFrontmatterInput } from './schema.js';
+/** Render a starter graft.md with every required section and guidance for authors. */
+export declare function renderGraftTemplate(frontmatter: GraftFrontmatterInput): string;
+//# sourceMappingURL=template.d.ts.map

package/dist/template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../src/template.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEzD,sFAAsF;AACtF,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,qBAAqB,GAAG,MAAM,CA8B9E"}

package/dist/template.js

@@ -0,0 +1,34 @@
+import { stringify } from 'yaml';
+/** Render a starter graft.md with every required section and guidance for authors. */
+export function renderGraftTemplate(frontmatter) {
+    const yaml = stringify(frontmatter, { lineWidth: 0 });
+    return `---
+${yaml}---
+
+## Why
+
+<!-- What this modification enables, and why upstream does not (or will not) do it.
+     Link the upstream issue/PR if one exists. -->
+
+## Invariants
+
+<!-- Observable behaviors that must hold. One bullet each. The oracle tests exactly these.
+     Example: "- Every request sent by the client carries an \`x-trace-id\` header." -->
+
+## Where to look
+
+<!-- Describe the upstream area by *behavior*, not file path, so an agent can re-locate it
+     after a refactor. Example: "The function that builds outgoing request headers right
+     before the request is dispatched." -->
+
+## Anchors
+
+<!-- For each anchor a variant matches on: what it is, and why it was chosen over
+     alternatives (prefer stable exported symbols and public strings over code shape). -->
+
+## History
+
+- ${new Date().toISOString().slice(0, 10)}: Graft created against ${frontmatter.rootstock.package}@${frontmatter.rootstock.verified}.
+`;
+}
+//# sourceMappingURL=template.js.map

package/dist/template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../src/template.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAGjC,sFAAsF;AACtF,MAAM,UAAU,mBAAmB,CAAC,WAAkC;IACpE,MAAM,IAAI,GAAG,SAAS,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC;IACtD,OAAO;EACP,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;IAyBF,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,2BAA2B,WAAW,CAAC,SAAS,CAAC,OAAO,IAAI,WAAW,CAAC,SAAS,CAAC,QAAQ;CAClI,CAAC;AACF,CAAC"}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@graftsync/spec",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "The Graft spec: schema, parser and validator for graft intent files and manifests.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brandonroberts/graft.git",
+    "directory": "packages/spec"
+  },
+  "homepage": "https://github.com/brandonroberts/graft#readme",
+  "bugs": "https://github.com/brandonroberts/graft/issues",
+  "keywords": [
+    "graft",
+    "patch",
+    "npm",
+    "upstream",
+    "spec",
+    "schema"
+  ],
+  "engines": {
+    "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "semver": "^7.8.6",
+    "yaml": "^2.9.1",
+    "zod": "^4.6.7"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.