@variance-authority/core 0.8.1 → 0.10.0

package/dist/share/line.js

@@ -0,0 +1,184 @@
+/**
+ * A line: the latest of what CI derived on one mainline or one branch.
+ *
+ * A line answers the question a checkout actually has — *what is mainline now*
+ * — by holding one version and replacing it, rather than keeping one artifact
+ * per commit for a reader to walk history in search of. Work is branched off a
+ * mainline and brought up to date with it before it merges, so the latest is
+ * the right answer, and the distance from a checkout to it is the instruction
+ * when it is not.
+ *
+ * A line holds **entries**, each a versioned artifact derived at one commit: the
+ * run report, one record per suite, the suite index. They are entries rather
+ * than one bundle because they arrive from different jobs, and a publish replaces
+ * only what it carries. It also holds the **images** its entries name, by digest,
+ * because an image does not compress and costs nothing to keep once.
+ *
+ * Nothing here collapses a failure into a miss. A reader has to be told whether
+ * nothing was published, it lacks the credentials, the store could not be
+ * reached, or a newer writer left a format it cannot read, because each of those
+ * asks for a different action.
+ */
+import { sha256HexBytes } from '../format/sha256.js';
+const ENTRY = /^([a-z][a-z0-9-]*)-v([1-9][0-9]*)(?:\/([A-Za-z0-9._-]+))?$/;
+const COMMIT = /^[0-9a-f]{4,64}$/;
+const DIGEST = /^[0-9a-f]{64}$/;
+/** Read an entry name, or refuse it. */
+export function parseEntryName(name) {
+    const match = ENTRY.exec(name);
+    if (match === null)
+        return undefined;
+    const qualifier = match[3];
+    return {
+        family: match[1],
+        version: Number(match[2]),
+        ...(qualifier !== undefined && qualifier !== '.' && qualifier !== '..' ? { qualifier } : {}),
+    };
+}
+/** Two entries are the same slot when they differ at most in version. */
+export function sameSlot(a, b) {
+    return a.family === b.family && a.qualifier === b.qualifier;
+}
+/**
+ * The path of a line inside a store, `mainline/release/2.0`.
+ *
+ * Each segment of the branch name is folded to key characters, a
+ * deliberately many-to-one mapping. Two branches whose names differ only in
+ * folded characters share a line, and a reader tells them apart by whether its
+ * `HEAD` contains the commit the line names.
+ */
+export function linePath(line) {
+    const segments = line.name
+        .split('/')
+        .map((part) => part.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^[-.]+|[-.]+$/g, ''))
+        .filter((part) => part !== '');
+    return `${line.kind}/${segments.length === 0 ? 'unnamed' : segments.join('/')}`;
+}
+/** The digest an entry's bytes are held under. */
+export function entryDigest(bytes) {
+    return sha256HexBytes(bytes);
+}
+/**
+ * The manifest as bytes: canonical, ASCII, byte-stable.
+ *
+ * Every field is checked to be ASCII before it is written — names, commits and
+ * digests already are — so no text encoder is needed and two runtimes cannot
+ * write two spellings of one manifest.
+ */
+export function encodeManifest(manifest) {
+    const entries = [...manifest.entries].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    const text = JSON.stringify({
+        format: manifest.format,
+        entries: entries.map((entry) => ({
+            name: entry.name,
+            commit: entry.commit,
+            ...(entry.head !== undefined ? { head: entry.head } : {}),
+            ...(entry.images !== undefined ? { images: [...entry.images].sort() } : {}),
+            digest: entry.digest,
+            size: entry.size,
+        })),
+    });
+    const bytes = new Uint8Array(text.length);
+    for (let i = 0; i < text.length; i += 1) {
+        const code = text.charCodeAt(i);
+        if (code > 0x7e)
+            throw new Error(`a manifest holds ASCII only, and this one does not at ${String(i)}`);
+        bytes[i] = code;
+    }
+    return bytes;
+}
+/**
+ * Read a manifest, or say why it is not one.
+ *
+ * A `format` above 1 is a newer writer, not a broken one, and is answered as
+ * such: the reader's action is to upgrade, not to republish.
+ */
+export function decodeManifest(bytes) {
+    let text = '';
+    for (const byte of bytes) {
+        if (byte > 0x7e)
+            return { kind: 'unreadable', detail: 'the manifest is not ASCII' };
+        text += String.fromCharCode(byte);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { kind: 'unreadable', detail: 'the manifest is not JSON' };
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        return { kind: 'unreadable', detail: 'the manifest is not an object' };
+    }
+    const { format, entries } = parsed;
+    if (typeof format === 'number' && format > 1)
+        return { kind: 'newer', names: [`manifest format ${String(format)}`] };
+    if (format !== 1 || !Array.isArray(entries)) {
+        return { kind: 'unreadable', detail: 'the manifest has no format 1 entry list' };
+    }
+    const held = [];
+    for (const entry of entries) {
+        const checked = heldEntry(entry);
+        if (checked === undefined)
+            return { kind: 'unreadable', detail: 'the manifest holds a malformed entry' };
+        held.push(checked);
+    }
+    return { format: 1, entries: held };
+}
+function heldEntry(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const { name, commit, head, images, digest, size } = value;
+    if (typeof name !== 'string' || parseEntryName(name) === undefined)
+        return undefined;
+    if (typeof commit !== 'string' || !COMMIT.test(commit))
+        return undefined;
+    if (head !== undefined && (typeof head !== 'string' || !COMMIT.test(head)))
+        return undefined;
+    if (typeof digest !== 'string' || !DIGEST.test(digest))
+        return undefined;
+    if (typeof size !== 'number' || !Number.isInteger(size) || size < 0)
+        return undefined;
+    if (images !== undefined) {
+        if (!Array.isArray(images) || !images.every((image) => typeof image === 'string' && DIGEST.test(image))) {
+            return undefined;
+        }
+    }
+    return {
+        name,
+        commit,
+        ...(head !== undefined ? { head: head } : {}),
+        ...(images !== undefined ? { images: images } : {}),
+        digest,
+        size,
+    };
+}
+/** Whether an entry offered for publishing is well formed, and why not. */
+export function entryProblem(entry) {
+    if (parseEntryName(entry.name) === undefined) {
+        return `"${entry.name}" is not <family>-v<version>[/<qualifier>]`;
+    }
+    if (!COMMIT.test(entry.commit))
+        return `${entry.name}: "${entry.commit}" is not a commit`;
+    if (entry.head !== undefined && !COMMIT.test(entry.head))
+        return `${entry.name}: "${entry.head}" is not a commit`;
+    for (const image of entry.images ?? []) {
+        if (!DIGEST.test(image))
+            return `${entry.name}: "${image}" is not a sha-256 digest`;
+    }
+    return undefined;
+}
+/**
+ * Every blob path a manifest names. A backend that holds one line as one tree,
+ * a git ref, keeps exactly these and drops the rest when it writes.
+ */
+export function manifestPaths(manifest) {
+    const paths = new Set();
+    for (const entry of manifest.entries) {
+        paths.add(`entries/${entry.digest}`);
+        for (const image of entry.images ?? [])
+            paths.add(`images/${image}`);
+    }
+    return [...paths].sort();
+}
+//# sourceMappingURL=line.js.map

package/dist/share/line.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"line.js","sourceRoot":"","sources":["../../src/share/line.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * A line: the latest of what CI derived on one mainline or one branch.\n *\n * A line answers the question a checkout actually has — *what is mainline now*\n * — by holding one version and replacing it, rather than keeping one artifact\n * per commit for a reader to walk history in search of. Work is branched off a\n * mainline and brought up to date with it before it merges, so the latest is\n * the right answer, and the distance from a checkout to it is the instruction\n * when it is not.\n *\n * A line holds **entries**, each a versioned artifact derived at one commit: the\n * run report, one record per suite, the suite index. They are entries rather\n * than one bundle because they arrive from different jobs, and a publish replaces\n * only what it carries. It also holds the **images** its entries name, by digest,\n * because an image does not compress and costs nothing to keep once.\n *\n * Nothing here collapses a failure into a miss. A reader has to be told whether\n * nothing was published, it lacks the credentials, the store could not be\n * reached, or a newer writer left a format it cannot read, because each of those\n * asks for a different action.\n */\n\nimport { sha256HexBytes } from '../format/sha256.js';\n\n/** One line a share holds the latest of. */\nexport interface ShareLine {\n  readonly kind: 'mainline' | 'branch';\n  /** The branch name as git spells it, `release/2.0` included. */\n  readonly name: string;\n}\n\n/** An artifact offered to a line. */\nexport interface ShareEntry {\n  /** `<family>-v<version>`, optionally `/<qualifier>`: `report-v1`, `suite-v1/web`. */\n  readonly name: string;\n  /** The commit it was derived at. For a pull request, the merge CI ran on. */\n  readonly commit: string;\n  /** The commit a pull request pointed at, when `commit` is the merge made for it. */\n  readonly head?: string;\n  /** Digests of the images this entry names, which the line keeps while it keeps the entry. */\n  readonly images?: readonly string[];\n  readonly bytes: Uint8Array;\n}\n\n/** An entry as the line holds it: what it is, where its bytes are, and nothing else. */\nexport interface HeldEntry {\n  readonly name: string;\n  readonly commit: string;\n  readonly head?: string;\n  readonly images?: readonly string[];\n  readonly digest: string;\n  readonly size: number;\n}\n\n/** What a line holds now. */\nexport interface LineManifest {\n  readonly format: 1;\n  /** Sorted by name, in code-unit order. */\n  readonly entries: readonly HeldEntry[];\n}\n\n/**\n * Why a line could not answer.\n *\n * - `absent`: nothing was published under that name.\n * - `newer`: something was, in a format this reader does not know.\n * - `refused`: the store answered, and said no.\n * - `unreachable`: the store did not answer, or not in time.\n * - `unreadable`: the store answered with bytes that are not what they claim.\n */\nexport type ShareMiss =\n  | { readonly kind: 'absent' }\n  | { readonly kind: 'newer'; readonly names: readonly string[] }\n  | { readonly kind: 'refused'; readonly detail: string }\n  | { readonly kind: 'unreachable'; readonly detail: string }\n  | { readonly kind: 'unreadable'; readonly detail: string };\n\n/** A path inside a line: an entry's bytes or an image, both by digest. */\nexport type BlobPath = `entries/${string}` | `images/${string}`;\n\n/**\n * The one thing a backend has to provide: a manifest that is replaced only if\n * nobody replaced it first, and the blobs it names.\n *\n * Deliberately below the rules. What may replace what, which images to send and\n * how a reader tells a newer format from nothing are decided once, in\n * {@link publishLine} and {@link readLine}, so a directory, a bucket and a git\n * ref cannot disagree about them.\n */\nexport interface LineCell {\n  /** The manifest and an opaque version to write against, or why not. */\n  load(line: ShareLine): Promise<{ readonly manifest: Uint8Array; readonly version: string } | ShareMiss>;\n  blob(line: ShareLine, path: BlobPath): Promise<Uint8Array | ShareMiss>;\n  /**\n   * Replace the manifest, if the held version is still `expected`.\n   *\n   * `expected` absent means the line must not exist yet. `blobs` holds only\n   * what the held line lacks; every other path the manifest names is already\n   * there, and a backend that builds on the held version relies on that.\n   */\n  store(\n    line: ShareLine,\n    write: {\n      readonly manifest: Uint8Array;\n      readonly blobs: ReadonlyMap<BlobPath, Uint8Array>;\n      readonly expected?: string;\n    },\n  ): Promise<'written' | 'conflict' | ShareMiss>;\n}\n\n/** An entry name, read. */\nexport interface EntryName {\n  readonly family: string;\n  readonly version: number;\n  readonly qualifier?: string;\n}\n\nconst ENTRY = /^([a-z][a-z0-9-]*)-v([1-9][0-9]*)(?:\\/([A-Za-z0-9._-]+))?$/;\nconst COMMIT = /^[0-9a-f]{4,64}$/;\nconst DIGEST = /^[0-9a-f]{64}$/;\n\n/** Read an entry name, or refuse it. */\nexport function parseEntryName(name: string): EntryName | undefined {\n  const match = ENTRY.exec(name);\n  if (match === null) return undefined;\n  const qualifier = match[3];\n  return {\n    family: match[1]!,\n    version: Number(match[2]),\n    ...(qualifier !== undefined && qualifier !== '.' && qualifier !== '..' ? { qualifier } : {}),\n  };\n}\n\n/** Two entries are the same slot when they differ at most in version. */\nexport function sameSlot(a: EntryName, b: EntryName): boolean {\n  return a.family === b.family && a.qualifier === b.qualifier;\n}\n\n/**\n * The path of a line inside a store, `mainline/release/2.0`.\n *\n * Each segment of the branch name is folded to key characters, a\n * deliberately many-to-one mapping. Two branches whose names differ only in\n * folded characters share a line, and a reader tells them apart by whether its\n * `HEAD` contains the commit the line names.\n */\nexport function linePath(line: ShareLine): string {\n  const segments = line.name\n    .split('/')\n    .map((part) => part.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^[-.]+|[-.]+$/g, ''))\n    .filter((part) => part !== '');\n  return `${line.kind}/${segments.length === 0 ? 'unnamed' : segments.join('/')}`;\n}\n\n/** The digest an entry's bytes are held under. */\nexport function entryDigest(bytes: Uint8Array): string {\n  return sha256HexBytes(bytes);\n}\n\n/**\n * The manifest as bytes: canonical, ASCII, byte-stable.\n *\n * Every field is checked to be ASCII before it is written — names, commits and\n * digests already are — so no text encoder is needed and two runtimes cannot\n * write two spellings of one manifest.\n */\nexport function encodeManifest(manifest: LineManifest): Uint8Array {\n  const entries = [...manifest.entries].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));\n  const text = JSON.stringify({\n    format: manifest.format,\n    entries: entries.map((entry) => ({\n      name: entry.name,\n      commit: entry.commit,\n      ...(entry.head !== undefined ? { head: entry.head } : {}),\n      ...(entry.images !== undefined ? { images: [...entry.images].sort() } : {}),\n      digest: entry.digest,\n      size: entry.size,\n    })),\n  });\n  const bytes = new Uint8Array(text.length);\n  for (let i = 0; i < text.length; i += 1) {\n    const code = text.charCodeAt(i);\n    if (code > 0x7e) throw new Error(`a manifest holds ASCII only, and this one does not at ${String(i)}`);\n    bytes[i] = code;\n  }\n  return bytes;\n}\n\n/**\n * Read a manifest, or say why it is not one.\n *\n * A `format` above 1 is a newer writer, not a broken one, and is answered as\n * such: the reader's action is to upgrade, not to republish.\n */\nexport function decodeManifest(bytes: Uint8Array): LineManifest | ShareMiss {\n  let text = '';\n  for (const byte of bytes) {\n    if (byte > 0x7e) return { kind: 'unreadable', detail: 'the manifest is not ASCII' };\n    text += String.fromCharCode(byte);\n  }\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(text);\n  } catch {\n    return { kind: 'unreadable', detail: 'the manifest is not JSON' };\n  }\n  if (typeof parsed !== 'object' || parsed === null) {\n    return { kind: 'unreadable', detail: 'the manifest is not an object' };\n  }\n  const { format, entries } = parsed as { format?: unknown; entries?: unknown };\n  if (typeof format === 'number' && format > 1) return { kind: 'newer', names: [`manifest format ${String(format)}`] };\n  if (format !== 1 || !Array.isArray(entries)) {\n    return { kind: 'unreadable', detail: 'the manifest has no format 1 entry list' };\n  }\n  const held: HeldEntry[] = [];\n  for (const entry of entries as unknown[]) {\n    const checked = heldEntry(entry);\n    if (checked === undefined) return { kind: 'unreadable', detail: 'the manifest holds a malformed entry' };\n    held.push(checked);\n  }\n  return { format: 1, entries: held };\n}\n\nfunction heldEntry(value: unknown): HeldEntry | undefined {\n  if (typeof value !== 'object' || value === null) return undefined;\n  const { name, commit, head, images, digest, size } = value as Record<string, unknown>;\n  if (typeof name !== 'string' || parseEntryName(name) === undefined) return undefined;\n  if (typeof commit !== 'string' || !COMMIT.test(commit)) return undefined;\n  if (head !== undefined && (typeof head !== 'string' || !COMMIT.test(head))) return undefined;\n  if (typeof digest !== 'string' || !DIGEST.test(digest)) return undefined;\n  if (typeof size !== 'number' || !Number.isInteger(size) || size < 0) return undefined;\n  if (images !== undefined) {\n    if (!Array.isArray(images) || !images.every((image) => typeof image === 'string' && DIGEST.test(image))) {\n      return undefined;\n    }\n  }\n  return {\n    name,\n    commit,\n    ...(head !== undefined ? { head: head as string } : {}),\n    ...(images !== undefined ? { images: images as string[] } : {}),\n    digest,\n    size,\n  };\n}\n\n/** Whether an entry offered for publishing is well formed, and why not. */\nexport function entryProblem(entry: ShareEntry): string | undefined {\n  if (parseEntryName(entry.name) === undefined) {\n    return `\"${entry.name}\" is not <family>-v<version>[/<qualifier>]`;\n  }\n  if (!COMMIT.test(entry.commit)) return `${entry.name}: \"${entry.commit}\" is not a commit`;\n  if (entry.head !== undefined && !COMMIT.test(entry.head)) return `${entry.name}: \"${entry.head}\" is not a commit`;\n  for (const image of entry.images ?? []) {\n    if (!DIGEST.test(image)) return `${entry.name}: \"${image}\" is not a sha-256 digest`;\n  }\n  return undefined;\n}\n\n/**\n * Every blob path a manifest names. A backend that holds one line as one tree,\n * a git ref, keeps exactly these and drops the rest when it writes.\n */\nexport function manifestPaths(manifest: LineManifest): BlobPath[] {\n  const paths = new Set<BlobPath>();\n  for (const entry of manifest.entries) {\n    paths.add(`entries/${entry.digest}`);\n    for (const image of entry.images ?? []) paths.add(`images/${image}`);\n  }\n  return [...paths].sort();\n}\n"]}

package/dist/share/publish.d.ts

@@ -0,0 +1,79 @@
+/**
+ * What may replace what on a line, and what a reader is told.
+ *
+ * Decided here, once, over the {@link LineCell} a backend provides, so a
+ * directory, a bucket and a git ref hold a line by the same rules.
+ */
+import { type HeldEntry, type LineCell, type LineManifest, type ShareEntry, type ShareLine, type ShareMiss } from './line.js';
+/**
+ * Whether `descendant` strictly descends from `ancestor`, or `undefined` when
+ * the history needed to say is not at hand. Git owns this answer; the caller
+ * asks it.
+ */
+export type Descends = (descendant: string, ancestor: string) => Promise<boolean | undefined>;
+/** What a publish did, entry by entry. */
+export interface Published {
+    /** Entries this publish wrote. */
+    readonly written: readonly string[];
+    /** Entries the line kept instead, and why. */
+    readonly kept: readonly {
+        readonly name: string;
+        readonly commit: string;
+        readonly because: 'newer-commit' | 'newer-format';
+    }[];
+    /**
+     * Entries written although nobody could say whether the held one was newer.
+     * Replacing is the answer then, because a line that refuses when it cannot
+     * tell is a line one force-push jams for good.
+     */
+    readonly unanswered: readonly string[];
+    /** How many times the manifest was read before a write held. */
+    readonly attempts: number;
+}
+export interface PublishOptions {
+    readonly descends: Descends;
+    /** The bytes of an image the line does not hold yet, by digest. */
+    readonly image: (digest: string) => Promise<Uint8Array>;
+    /** Reads of the manifest before giving up on a line other writers keep moving. Defaults to 8. */
+    readonly attempts?: number;
+}
+/**
+ * Offer entries to a line.
+ *
+ * Each entry replaces the held entry in its slot — same family, same qualifier,
+ * any version — except on a mainline, where the held one is kept when its
+ * commit strictly descends from the offered one: a slow run of an older commit
+ * finishing last. A held entry in a newer format is kept on any line, so an old
+ * CLI cannot take a line back a version. Every other held entry is left as it
+ * is, which is how suites published by different jobs land on one line.
+ *
+ * A write that loses to another writer reads the line again and decides again.
+ */
+export declare function publishLine(cell: LineCell, line: ShareLine, entries: readonly ShareEntry[], options: PublishOptions): Promise<Published | ShareMiss>;
+/** A line as a reader holds it: the manifest, and its blobs on demand. */
+export interface HeldLine {
+    readonly line: ShareLine;
+    readonly manifest: LineManifest;
+    /** The bytes of one entry, checked against the digest the manifest names. */
+    entry(entry: HeldEntry): Promise<Uint8Array | ShareMiss>;
+    image(digest: string): Promise<Uint8Array | ShareMiss>;
+}
+/** Read what a line holds, or why it cannot be read. */
+export declare function readLine(cell: LineCell, line: ShareLine): Promise<HeldLine | ShareMiss>;
+/**
+ * The held entry a reader asked for by name, or why there is none.
+ *
+ * A reader of `suite-v1/web` that finds `suite-v2/web` is told `newer`, not
+ * `absent`: the line has what it wants, in a format it has to upgrade to read.
+ */
+export declare function findEntry(manifest: LineManifest, name: string): HeldEntry | ShareMiss;
+/**
+ * A line cell in this process, for tests and for a run that shares with itself.
+ *
+ * Holds real versions, so a test can stage a writer that moves the line between
+ * another writer's read and its write.
+ */
+export declare function memoryLineCell(): LineCell & {
+    readonly held: Map<string, Uint8Array>;
+};
+//# sourceMappingURL=publish.d.ts.map

package/dist/share/publish.js

@@ -0,0 +1,231 @@
+/**
+ * What may replace what on a line, and what a reader is told.
+ *
+ * Decided here, once, over the {@link LineCell} a backend provides, so a
+ * directory, a bucket and a git ref hold a line by the same rules.
+ */
+import { decodeManifest, encodeManifest, entryDigest, entryProblem, parseEntryName, sameSlot, } from './line.js';
+/**
+ * Offer entries to a line.
+ *
+ * Each entry replaces the held entry in its slot — same family, same qualifier,
+ * any version — except on a mainline, where the held one is kept when its
+ * commit strictly descends from the offered one: a slow run of an older commit
+ * finishing last. A held entry in a newer format is kept on any line, so an old
+ * CLI cannot take a line back a version. Every other held entry is left as it
+ * is, which is how suites published by different jobs land on one line.
+ *
+ * A write that loses to another writer reads the line again and decides again.
+ */
+export async function publishLine(cell, line, entries, options) {
+    for (const entry of entries) {
+        const problem = entryProblem(entry);
+        if (problem !== undefined)
+            throw new Error(`cannot publish ${problem}`);
+    }
+    const limit = options.attempts ?? 8;
+    for (let attempt = 1; attempt <= limit; attempt += 1) {
+        const loaded = await cell.load(line);
+        let held;
+        let expected;
+        if ('manifest' in loaded) {
+            const decoded = decodeManifest(loaded.manifest);
+            // A line a newer writer owns is not this writer's to replace; one that is
+            // unreadable is, since nothing can read it anyway.
+            if ('kind' in decoded) {
+                if (decoded.kind === 'newer')
+                    return decoded;
+                held = { format: 1, entries: [] };
+            }
+            else {
+                held = decoded;
+            }
+            expected = loaded.version;
+        }
+        else if (loaded.kind === 'absent') {
+            held = { format: 1, entries: [] };
+        }
+        else {
+            return loaded;
+        }
+        const plan = await decide(line, held, entries, options.descends);
+        if (plan.write.length === 0) {
+            return { written: [], kept: plan.kept, unanswered: [], attempts: attempt };
+        }
+        const next = nextManifest(held, plan.write);
+        const blobs = await blobsFor(held, next, plan.write, options.image);
+        const outcome = await cell.store(line, {
+            manifest: encodeManifest(next),
+            blobs,
+            ...(expected !== undefined ? { expected } : {}),
+        });
+        if (outcome === 'written') {
+            return {
+                written: plan.write.map((entry) => entry.name),
+                kept: plan.kept,
+                unanswered: plan.unanswered,
+                attempts: attempt,
+            };
+        }
+        if (outcome !== 'conflict')
+            return outcome;
+    }
+    return {
+        kind: 'unreachable',
+        detail: `the line moved under ${String(limit)} writes in a row; nothing was published`,
+    };
+}
+async function decide(line, held, entries, descends) {
+    const write = [];
+    const kept = [];
+    const unanswered = [];
+    for (const entry of entries) {
+        const offered = parseEntryName(entry.name);
+        let occupant;
+        let version = 0;
+        for (const candidate of held.entries) {
+            const slot = parseEntryName(candidate.name);
+            if (sameSlot(slot, offered) && slot.version > version) {
+                occupant = candidate;
+                version = slot.version;
+            }
+        }
+        if (occupant === undefined) {
+            write.push(entry);
+            continue;
+        }
+        if (version > offered.version) {
+            kept.push({ name: occupant.name, commit: occupant.commit, because: 'newer-format' });
+            continue;
+        }
+        // TODO: shards of one run publish at one commit, so each replaces the
+        // last one's `suite-index-v1` and `report-v1`, and the line keeps the index
+        // and report of whichever shard published last, covering its subjects only.
+        // Nothing here merges two entries of one slot.
+        if (line.kind === 'branch' || occupant.commit === entry.commit) {
+            write.push(entry);
+            continue;
+        }
+        const newer = await descends(occupant.commit, entry.commit);
+        if (newer === true) {
+            kept.push({ name: occupant.name, commit: occupant.commit, because: 'newer-commit' });
+            continue;
+        }
+        if (newer === undefined)
+            unanswered.push(entry.name);
+        write.push(entry);
+    }
+    return { write, kept, unanswered };
+}
+function nextManifest(held, write) {
+    const replaced = write.map((entry) => parseEntryName(entry.name));
+    const survivors = held.entries.filter((entry) => !replaced.some((slot) => sameSlot(slot, parseEntryName(entry.name))));
+    const added = write.map((entry) => ({
+        name: entry.name,
+        commit: entry.commit,
+        ...(entry.head !== undefined ? { head: entry.head } : {}),
+        ...(entry.images !== undefined ? { images: [...new Set(entry.images)] } : {}),
+        digest: entryDigest(entry.bytes),
+        size: entry.bytes.length,
+    }));
+    return { format: 1, entries: [...survivors, ...added] };
+}
+/** Only what the held line lacks: entry bytes are new by construction, images often are not. */
+async function blobsFor(held, next, write, image) {
+    const blobs = new Map();
+    const heldDigests = new Set(held.entries.map((entry) => entry.digest));
+    for (const entry of write) {
+        const digest = entryDigest(entry.bytes);
+        if (!heldDigests.has(digest))
+            blobs.set(`entries/${digest}`, entry.bytes);
+    }
+    const heldImages = new Set(held.entries.flatMap((entry) => entry.images ?? []));
+    for (const digest of new Set(next.entries.flatMap((entry) => entry.images ?? []))) {
+        if (!heldImages.has(digest))
+            blobs.set(`images/${digest}`, await image(digest));
+    }
+    return blobs;
+}
+/** Read what a line holds, or why it cannot be read. */
+export async function readLine(cell, line) {
+    const loaded = await cell.load(line);
+    if (!('manifest' in loaded))
+        return loaded;
+    const manifest = decodeManifest(loaded.manifest);
+    if ('kind' in manifest)
+        return manifest;
+    return {
+        line,
+        manifest,
+        async entry(entry) {
+            const bytes = await cell.blob(line, `entries/${entry.digest}`);
+            if (!(bytes instanceof Uint8Array))
+                return bytes;
+            if (entryDigest(bytes) !== entry.digest) {
+                return { kind: 'unreadable', detail: `${entry.name}: the bytes do not match the manifest's digest` };
+            }
+            return bytes;
+        },
+        image(digest) {
+            return cell.blob(line, `images/${digest}`);
+        },
+    };
+}
+/**
+ * The held entry a reader asked for by name, or why there is none.
+ *
+ * A reader of `suite-v1/web` that finds `suite-v2/web` is told `newer`, not
+ * `absent`: the line has what it wants, in a format it has to upgrade to read.
+ */
+export function findEntry(manifest, name) {
+    const wanted = parseEntryName(name);
+    if (wanted === undefined)
+        throw new Error(`"${name}" is not <family>-v<version>[/<qualifier>]`);
+    const exact = manifest.entries.find((entry) => entry.name === name);
+    if (exact !== undefined)
+        return exact;
+    const newer = manifest.entries
+        .filter((entry) => {
+        const held = parseEntryName(entry.name);
+        return sameSlot(held, wanted) && held.version > wanted.version;
+    })
+        .map((entry) => entry.name);
+    return newer.length > 0 ? { kind: 'newer', names: newer } : { kind: 'absent' };
+}
+/**
+ * A line cell in this process, for tests and for a run that shares with itself.
+ *
+ * Holds real versions, so a test can stage a writer that moves the line between
+ * another writer's read and its write.
+ */
+export function memoryLineCell() {
+    const held = new Map();
+    const versions = new Map();
+    const key = (line) => `${line.kind}\u0000${line.name}`;
+    return {
+        held,
+        async load(line) {
+            const manifest = held.get(`${key(line)}\u0000manifest`);
+            if (manifest === undefined)
+                return { kind: 'absent' };
+            return { manifest, version: String(versions.get(key(line)) ?? 0) };
+        },
+        async blob(line, path) {
+            const bytes = held.get(path.startsWith('images/') ? path : `${key(line)}\u0000${path}`);
+            return bytes === undefined ? { kind: 'absent' } : bytes.slice();
+        },
+        async store(line, write) {
+            const current = versions.get(key(line));
+            const now = current === undefined ? undefined : String(current);
+            if (now !== write.expected)
+                return 'conflict';
+            for (const [path, bytes] of write.blobs) {
+                held.set(path.startsWith('images/') ? path : `${key(line)}\u0000${path}`, bytes.slice());
+            }
+            held.set(`${key(line)}\u0000manifest`, write.manifest.slice());
+            versions.set(key(line), (current ?? 0) + 1);
+            return 'written';
+        },
+    };
+}
+//# sourceMappingURL=publish.js.map

package/dist/share/publish.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish.js","sourceRoot":"","sources":["../../src/share/publish.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What may replace what on a line, and what a reader is told.\n *\n * Decided here, once, over the {@link LineCell} a backend provides, so a\n * directory, a bucket and a git ref hold a line by the same rules.\n */\n\nimport {\n  decodeManifest,\n  encodeManifest,\n  entryDigest,\n  entryProblem,\n  parseEntryName,\n  sameSlot,\n  type BlobPath,\n  type HeldEntry,\n  type LineCell,\n  type LineManifest,\n  type ShareEntry,\n  type ShareLine,\n  type ShareMiss,\n} from './line.js';\n\n/**\n * Whether `descendant` strictly descends from `ancestor`, or `undefined` when\n * the history needed to say is not at hand. Git owns this answer; the caller\n * asks it.\n */\nexport type Descends = (descendant: string, ancestor: string) => Promise<boolean | undefined>;\n\n/** What a publish did, entry by entry. */\nexport interface Published {\n  /** Entries this publish wrote. */\n  readonly written: readonly string[];\n  /** Entries the line kept instead, and why. */\n  readonly kept: readonly { readonly name: string; readonly commit: string; readonly because: 'newer-commit' | 'newer-format' }[];\n  /**\n   * Entries written although nobody could say whether the held one was newer.\n   * Replacing is the answer then, because a line that refuses when it cannot\n   * tell is a line one force-push jams for good.\n   */\n  readonly unanswered: readonly string[];\n  /** How many times the manifest was read before a write held. */\n  readonly attempts: number;\n}\n\nexport interface PublishOptions {\n  readonly descends: Descends;\n  /** The bytes of an image the line does not hold yet, by digest. */\n  readonly image: (digest: string) => Promise<Uint8Array>;\n  /** Reads of the manifest before giving up on a line other writers keep moving. Defaults to 8. */\n  readonly attempts?: number;\n}\n\n/**\n * Offer entries to a line.\n *\n * Each entry replaces the held entry in its slot — same family, same qualifier,\n * any version — except on a mainline, where the held one is kept when its\n * commit strictly descends from the offered one: a slow run of an older commit\n * finishing last. A held entry in a newer format is kept on any line, so an old\n * CLI cannot take a line back a version. Every other held entry is left as it\n * is, which is how suites published by different jobs land on one line.\n *\n * A write that loses to another writer reads the line again and decides again.\n */\nexport async function publishLine(\n  cell: LineCell,\n  line: ShareLine,\n  entries: readonly ShareEntry[],\n  options: PublishOptions,\n): Promise<Published | ShareMiss> {\n  for (const entry of entries) {\n    const problem = entryProblem(entry);\n    if (problem !== undefined) throw new Error(`cannot publish ${problem}`);\n  }\n\n  const limit = options.attempts ?? 8;\n  for (let attempt = 1; attempt <= limit; attempt += 1) {\n    const loaded = await cell.load(line);\n    let held: LineManifest;\n    let expected: string | undefined;\n    if ('manifest' in loaded) {\n      const decoded = decodeManifest(loaded.manifest);\n      // A line a newer writer owns is not this writer's to replace; one that is\n      // unreadable is, since nothing can read it anyway.\n      if ('kind' in decoded) {\n        if (decoded.kind === 'newer') return decoded;\n        held = { format: 1, entries: [] };\n      } else {\n        held = decoded;\n      }\n      expected = loaded.version;\n    } else if (loaded.kind === 'absent') {\n      held = { format: 1, entries: [] };\n    } else {\n      return loaded;\n    }\n\n    const plan = await decide(line, held, entries, options.descends);\n    if (plan.write.length === 0) {\n      return { written: [], kept: plan.kept, unanswered: [], attempts: attempt };\n    }\n\n    const next = nextManifest(held, plan.write);\n    const blobs = await blobsFor(held, next, plan.write, options.image);\n    const outcome = await cell.store(line, {\n      manifest: encodeManifest(next),\n      blobs,\n      ...(expected !== undefined ? { expected } : {}),\n    });\n    if (outcome === 'written') {\n      return {\n        written: plan.write.map((entry) => entry.name),\n        kept: plan.kept,\n        unanswered: plan.unanswered,\n        attempts: attempt,\n      };\n    }\n    if (outcome !== 'conflict') return outcome;\n  }\n  return {\n    kind: 'unreachable',\n    detail: `the line moved under ${String(limit)} writes in a row; nothing was published`,\n  };\n}\n\nasync function decide(\n  line: ShareLine,\n  held: LineManifest,\n  entries: readonly ShareEntry[],\n  descends: Descends,\n): Promise<{ write: ShareEntry[]; kept: Published['kept'][number][]; unanswered: string[] }> {\n  const write: ShareEntry[] = [];\n  const kept: Published['kept'][number][] = [];\n  const unanswered: string[] = [];\n  for (const entry of entries) {\n    const offered = parseEntryName(entry.name)!;\n    let occupant: HeldEntry | undefined;\n    let version = 0;\n    for (const candidate of held.entries) {\n      const slot = parseEntryName(candidate.name)!;\n      if (sameSlot(slot, offered) && slot.version > version) {\n        occupant = candidate;\n        version = slot.version;\n      }\n    }\n    if (occupant === undefined) {\n      write.push(entry);\n      continue;\n    }\n    if (version > offered.version) {\n      kept.push({ name: occupant.name, commit: occupant.commit, because: 'newer-format' });\n      continue;\n    }\n    // TODO: shards of one run publish at one commit, so each replaces the\n    // last one's `suite-index-v1` and `report-v1`, and the line keeps the index\n    // and report of whichever shard published last, covering its subjects only.\n    // Nothing here merges two entries of one slot.\n    if (line.kind === 'branch' || occupant.commit === entry.commit) {\n      write.push(entry);\n      continue;\n    }\n    const newer = await descends(occupant.commit, entry.commit);\n    if (newer === true) {\n      kept.push({ name: occupant.name, commit: occupant.commit, because: 'newer-commit' });\n      continue;\n    }\n    if (newer === undefined) unanswered.push(entry.name);\n    write.push(entry);\n  }\n  return { write, kept, unanswered };\n}\n\nfunction nextManifest(held: LineManifest, write: readonly ShareEntry[]): LineManifest {\n  const replaced = write.map((entry) => parseEntryName(entry.name)!);\n  const survivors = held.entries.filter(\n    (entry) => !replaced.some((slot) => sameSlot(slot, parseEntryName(entry.name)!)),\n  );\n  const added: HeldEntry[] = write.map((entry) => ({\n    name: entry.name,\n    commit: entry.commit,\n    ...(entry.head !== undefined ? { head: entry.head } : {}),\n    ...(entry.images !== undefined ? { images: [...new Set(entry.images)] } : {}),\n    digest: entryDigest(entry.bytes),\n    size: entry.bytes.length,\n  }));\n  return { format: 1, entries: [...survivors, ...added] };\n}\n\n/** Only what the held line lacks: entry bytes are new by construction, images often are not. */\nasync function blobsFor(\n  held: LineManifest,\n  next: LineManifest,\n  write: readonly ShareEntry[],\n  image: (digest: string) => Promise<Uint8Array>,\n): Promise<Map<BlobPath, Uint8Array>> {\n  const blobs = new Map<BlobPath, Uint8Array>();\n  const heldDigests = new Set(held.entries.map((entry) => entry.digest));\n  for (const entry of write) {\n    const digest = entryDigest(entry.bytes);\n    if (!heldDigests.has(digest)) blobs.set(`entries/${digest}`, entry.bytes);\n  }\n  const heldImages = new Set(held.entries.flatMap((entry) => entry.images ?? []));\n  for (const digest of new Set(next.entries.flatMap((entry) => entry.images ?? []))) {\n    if (!heldImages.has(digest)) blobs.set(`images/${digest}`, await image(digest));\n  }\n  return blobs;\n}\n\n/** A line as a reader holds it: the manifest, and its blobs on demand. */\nexport interface HeldLine {\n  readonly line: ShareLine;\n  readonly manifest: LineManifest;\n  /** The bytes of one entry, checked against the digest the manifest names. */\n  entry(entry: HeldEntry): Promise<Uint8Array | ShareMiss>;\n  image(digest: string): Promise<Uint8Array | ShareMiss>;\n}\n\n/** Read what a line holds, or why it cannot be read. */\nexport async function readLine(cell: LineCell, line: ShareLine): Promise<HeldLine | ShareMiss> {\n  const loaded = await cell.load(line);\n  if (!('manifest' in loaded)) return loaded;\n  const manifest = decodeManifest(loaded.manifest);\n  if ('kind' in manifest) return manifest;\n  return {\n    line,\n    manifest,\n    async entry(entry) {\n      const bytes = await cell.blob(line, `entries/${entry.digest}`);\n      if (!(bytes instanceof Uint8Array)) return bytes;\n      if (entryDigest(bytes) !== entry.digest) {\n        return { kind: 'unreadable', detail: `${entry.name}: the bytes do not match the manifest's digest` };\n      }\n      return bytes;\n    },\n    image(digest) {\n      return cell.blob(line, `images/${digest}`);\n    },\n  };\n}\n\n/**\n * The held entry a reader asked for by name, or why there is none.\n *\n * A reader of `suite-v1/web` that finds `suite-v2/web` is told `newer`, not\n * `absent`: the line has what it wants, in a format it has to upgrade to read.\n */\nexport function findEntry(manifest: LineManifest, name: string): HeldEntry | ShareMiss {\n  const wanted = parseEntryName(name);\n  if (wanted === undefined) throw new Error(`\"${name}\" is not <family>-v<version>[/<qualifier>]`);\n  const exact = manifest.entries.find((entry) => entry.name === name);\n  if (exact !== undefined) return exact;\n  const newer = manifest.entries\n    .filter((entry) => {\n      const held = parseEntryName(entry.name)!;\n      return sameSlot(held, wanted) && held.version > wanted.version;\n    })\n    .map((entry) => entry.name);\n  return newer.length > 0 ? { kind: 'newer', names: newer } : { kind: 'absent' };\n}\n\n/**\n * A line cell in this process, for tests and for a run that shares with itself.\n *\n * Holds real versions, so a test can stage a writer that moves the line between\n * another writer's read and its write.\n */\nexport function memoryLineCell(): LineCell & { readonly held: Map<string, Uint8Array> } {\n  const held = new Map<string, Uint8Array>();\n  const versions = new Map<string, number>();\n  const key = (line: ShareLine): string => `${line.kind}\\u0000${line.name}`;\n  return {\n    held,\n    async load(line) {\n      const manifest = held.get(`${key(line)}\\u0000manifest`);\n      if (manifest === undefined) return { kind: 'absent' };\n      return { manifest, version: String(versions.get(key(line)) ?? 0) };\n    },\n    async blob(line, path) {\n      const bytes = held.get(path.startsWith('images/') ? path : `${key(line)}\\u0000${path}`);\n      return bytes === undefined ? { kind: 'absent' } : bytes.slice();\n    },\n    async store(line, write) {\n      const current = versions.get(key(line));\n      const now = current === undefined ? undefined : String(current);\n      if (now !== write.expected) return 'conflict';\n      for (const [path, bytes] of write.blobs) {\n        held.set(path.startsWith('images/') ? path : `${key(line)}\\u0000${path}`, bytes.slice());\n      }\n      held.set(`${key(line)}\\u0000manifest`, write.manifest.slice());\n      versions.set(key(line), (current ?? 0) + 1);\n      return 'written';\n    },\n  };\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@variance-authority/core",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "description": "The Variance Authority format, rules, comparison, attribution and verdicts. Pure data in, pure data out, no DOM and no I/O.",
   "keywords": [
     "variance-authority",