@wirebench/engine 2.2.1 → 3.1.0-rc.1

package/dist/server-api/teams.d.ts

@@ -0,0 +1,306 @@
+/**
+ * The teams-access module's wire shapes (teams-access spec §3.2, §4.2). The server's routes
+ * validate with them (through `jsonSchema()`) and the desktop's `ServerClient` parses answers with
+ * them, so a drift between the two fails typecheck.
+ *
+ * Names arrive untrimmed: Fastify validates the JSON Schema rendering, which cannot carry a
+ * transform, so the handler trims and re-checks the length (`teams-name-invalid`).
+ */
+import { z } from 'zod';
+/**
+ * Crockford base32 ULID, upper case, 26 characters: what `ulidx` mints and what the server's
+ * `RepoStore` accepts. `identityIdSchema` only checks length; every teams route parameter is this.
+ */
+export declare const TEAMS_ID_PATTERN: RegExp;
+/** §6: team and workspace names, after trimming. */
+export declare const MAX_TEAMS_NAME_LENGTH = 80;
+export declare const teamsIdSchema: z.ZodString;
+export declare const teamsNameSchema: z.ZodString;
+export declare const teamRoleSchema: z.ZodEnum<{
+    member: "member";
+    admin: "admin";
+}>;
+export type TeamRole = z.infer<typeof teamRoleSchema>;
+export declare const workspaceRoleSchema: z.ZodEnum<{
+    editor: "editor";
+    admin: "admin";
+    viewer: "viewer";
+}>;
+export type WorkspaceRole = z.infer<typeof workspaceRoleSchema>;
+/** What a team member gets without a grant; `none` hides the workspace from them (§3.1). */
+export declare const defaultRoleSchema: z.ZodEnum<{
+    none: "none";
+    editor: "editor";
+    viewer: "viewer";
+}>;
+export type DefaultRole = z.infer<typeof defaultRoleSchema>;
+export declare const roleSourceSchema: z.ZodEnum<{
+    default: "default";
+    grant: "grant";
+    "server-admin": "server-admin";
+    "team-admin": "team-admin";
+}>;
+export type RoleSource = z.infer<typeof roleSourceSchema>;
+/** A role as the access list shows it: a team member may have `none`. */
+export declare const effectiveRoleSchema: z.ZodEnum<{
+    none: "none";
+    editor: "editor";
+    admin: "admin";
+    viewer: "viewer";
+}>;
+export type EffectiveRole = z.infer<typeof effectiveRoleSchema>;
+export declare const teamSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    myRole: z.ZodEnum<{
+        member: "member";
+        admin: "admin";
+    }>;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
+export type Team = z.infer<typeof teamSchema>;
+export declare const teamsResponseSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    myRole: z.ZodEnum<{
+        member: "member";
+        admin: "admin";
+    }>;
+    createdAt: z.ZodString;
+}, z.core.$strip>>;
+export declare const teamNameRequestSchema: z.ZodObject<{
+    name: z.ZodString;
+}, z.core.$strip>;
+export type TeamNameRequest = z.infer<typeof teamNameRequestSchema>;
+export declare const teamParamsSchema: z.ZodObject<{
+    teamId: z.ZodString;
+}, z.core.$strip>;
+export declare const teamMemberSchema: z.ZodObject<{
+    userId: z.ZodString;
+    email: z.ZodString;
+    displayName: z.ZodString;
+    role: z.ZodEnum<{
+        member: "member";
+        admin: "admin";
+    }>;
+    disabled: z.ZodBoolean;
+    addedAt: z.ZodString;
+}, z.core.$strip>;
+export type TeamMember = z.infer<typeof teamMemberSchema>;
+export declare const teamMembersResponseSchema: z.ZodArray<z.ZodObject<{
+    userId: z.ZodString;
+    email: z.ZodString;
+    displayName: z.ZodString;
+    role: z.ZodEnum<{
+        member: "member";
+        admin: "admin";
+    }>;
+    disabled: z.ZodBoolean;
+    addedAt: z.ZodString;
+}, z.core.$strip>>;
+export declare const memberAddRequestSchema: z.ZodObject<{
+    email: z.ZodString;
+    role: z.ZodEnum<{
+        member: "member";
+        admin: "admin";
+    }>;
+}, z.core.$strip>;
+export type MemberAddRequest = z.infer<typeof memberAddRequestSchema>;
+export declare const memberRoleRequestSchema: z.ZodObject<{
+    role: z.ZodEnum<{
+        member: "member";
+        admin: "admin";
+    }>;
+}, z.core.$strip>;
+export type MemberRoleRequest = z.infer<typeof memberRoleRequestSchema>;
+export declare const memberParamsSchema: z.ZodObject<{
+    teamId: z.ZodString;
+    userId: z.ZodString;
+}, z.core.$strip>;
+export declare const teamInvitationSchema: z.ZodObject<{
+    id: z.ZodString;
+    email: z.ZodString;
+    role: z.ZodEnum<{
+        member: "member";
+        admin: "admin";
+    }>;
+    createdBy: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    expiresAt: z.ZodString;
+}, z.core.$strip>;
+export type TeamInvitation = z.infer<typeof teamInvitationSchema>;
+export declare const teamInvitationsResponseSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    email: z.ZodString;
+    role: z.ZodEnum<{
+        member: "member";
+        admin: "admin";
+    }>;
+    createdBy: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    expiresAt: z.ZodString;
+}, z.core.$strip>>;
+export declare const teamInvitationCreateRequestSchema: z.ZodObject<{
+    email: z.ZodString;
+    role: z.ZodEnum<{
+        member: "member";
+        admin: "admin";
+    }>;
+}, z.core.$strip>;
+export type TeamInvitationCreateRequest = z.infer<typeof teamInvitationCreateRequestSchema>;
+/** The link is in this answer and nowhere else: the server stores only the secret's hash. */
+export declare const teamInvitationCreatedSchema: z.ZodObject<{
+    id: z.ZodString;
+    email: z.ZodString;
+    role: z.ZodEnum<{
+        member: "member";
+        admin: "admin";
+    }>;
+    url: z.ZodString;
+    expiresAt: z.ZodString;
+}, z.core.$strip>;
+export type TeamInvitationCreated = z.infer<typeof teamInvitationCreatedSchema>;
+export declare const teamInvitationParamsSchema: z.ZodObject<{
+    teamId: z.ZodString;
+    id: z.ZodString;
+}, z.core.$strip>;
+export declare const teamWorkspaceSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    teamId: z.ZodString;
+    teamName: z.ZodString;
+    defaultRole: z.ZodEnum<{
+        none: "none";
+        editor: "editor";
+        viewer: "viewer";
+    }>;
+    myRole: z.ZodEnum<{
+        editor: "editor";
+        admin: "admin";
+        viewer: "viewer";
+    }>;
+    source: z.ZodEnum<{
+        default: "default";
+        grant: "grant";
+        "server-admin": "server-admin";
+        "team-admin": "team-admin";
+    }>;
+    recordDesktopActivity: z.ZodDefault<z.ZodBoolean>;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
+export type TeamWorkspace = z.infer<typeof teamWorkspaceSchema>;
+export declare const teamWorkspacesResponseSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    teamId: z.ZodString;
+    teamName: z.ZodString;
+    defaultRole: z.ZodEnum<{
+        none: "none";
+        editor: "editor";
+        viewer: "viewer";
+    }>;
+    myRole: z.ZodEnum<{
+        editor: "editor";
+        admin: "admin";
+        viewer: "viewer";
+    }>;
+    source: z.ZodEnum<{
+        default: "default";
+        grant: "grant";
+        "server-admin": "server-admin";
+        "team-admin": "team-admin";
+    }>;
+    recordDesktopActivity: z.ZodDefault<z.ZodBoolean>;
+    createdAt: z.ZodString;
+}, z.core.$strip>>;
+export declare const teamWorkspaceCreateRequestSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    name: z.ZodString;
+    defaultRole: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+        editor: "editor";
+        viewer: "viewer";
+    }>>;
+}, z.core.$strip>;
+export type TeamWorkspaceCreateRequest = z.infer<typeof teamWorkspaceCreateRequestSchema>;
+export declare const teamWorkspaceUpdateRequestSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    defaultRole: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+        editor: "editor";
+        viewer: "viewer";
+    }>>;
+    recordDesktopActivity: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type TeamWorkspaceUpdateRequest = z.infer<typeof teamWorkspaceUpdateRequestSchema>;
+export declare const teamWorkspaceParamsSchema: z.ZodObject<{
+    workspaceId: z.ZodString;
+}, z.core.$strip>;
+/** One team member as a workspace admin sees them: what they can do, why, and any grant. */
+export declare const accessEntrySchema: z.ZodObject<{
+    userId: z.ZodString;
+    email: z.ZodString;
+    displayName: z.ZodString;
+    teamRole: z.ZodEnum<{
+        member: "member";
+        admin: "admin";
+    }>;
+    disabled: z.ZodBoolean;
+    effectiveRole: z.ZodEnum<{
+        none: "none";
+        editor: "editor";
+        admin: "admin";
+        viewer: "viewer";
+    }>;
+    source: z.ZodOptional<z.ZodEnum<{
+        default: "default";
+        grant: "grant";
+        "server-admin": "server-admin";
+        "team-admin": "team-admin";
+    }>>;
+    grant: z.ZodOptional<z.ZodEnum<{
+        editor: "editor";
+        admin: "admin";
+        viewer: "viewer";
+    }>>;
+}, z.core.$strip>;
+export type AccessEntry = z.infer<typeof accessEntrySchema>;
+export declare const accessResponseSchema: z.ZodArray<z.ZodObject<{
+    userId: z.ZodString;
+    email: z.ZodString;
+    displayName: z.ZodString;
+    teamRole: z.ZodEnum<{
+        member: "member";
+        admin: "admin";
+    }>;
+    disabled: z.ZodBoolean;
+    effectiveRole: z.ZodEnum<{
+        none: "none";
+        editor: "editor";
+        admin: "admin";
+        viewer: "viewer";
+    }>;
+    source: z.ZodOptional<z.ZodEnum<{
+        default: "default";
+        grant: "grant";
+        "server-admin": "server-admin";
+        "team-admin": "team-admin";
+    }>>;
+    grant: z.ZodOptional<z.ZodEnum<{
+        editor: "editor";
+        admin: "admin";
+        viewer: "viewer";
+    }>>;
+}, z.core.$strip>>;
+export declare const accessParamsSchema: z.ZodObject<{
+    workspaceId: z.ZodString;
+    userId: z.ZodString;
+}, z.core.$strip>;
+export declare const setAccessRequestSchema: z.ZodObject<{
+    role: z.ZodEnum<{
+        editor: "editor";
+        admin: "admin";
+        viewer: "viewer";
+    }>;
+}, z.core.$strip>;
+export type SetAccessRequest = z.infer<typeof setAccessRequestSchema>;

package/dist/server-api/teams.js

@@ -0,0 +1,113 @@
+/**
+ * The teams-access module's wire shapes (teams-access spec §3.2, §4.2). The server's routes
+ * validate with them (through `jsonSchema()`) and the desktop's `ServerClient` parses answers with
+ * them, so a drift between the two fails typecheck.
+ *
+ * Names arrive untrimmed: Fastify validates the JSON Schema rendering, which cannot carry a
+ * transform, so the handler trims and re-checks the length (`teams-name-invalid`).
+ */
+import { z } from 'zod';
+import { emailSchema } from './identity.js';
+/**
+ * Crockford base32 ULID, upper case, 26 characters: what `ulidx` mints and what the server's
+ * `RepoStore` accepts. `identityIdSchema` only checks length; every teams route parameter is this.
+ */
+export const TEAMS_ID_PATTERN = /^[0-9A-HJKMNP-TV-Z]{26}$/;
+/** §6: team and workspace names, after trimming. */
+export const MAX_TEAMS_NAME_LENGTH = 80;
+export const teamsIdSchema = z.string().regex(TEAMS_ID_PATTERN);
+export const teamsNameSchema = z.string().min(1).max(MAX_TEAMS_NAME_LENGTH);
+export const teamRoleSchema = z.enum(['member', 'admin']);
+export const workspaceRoleSchema = z.enum(['viewer', 'editor', 'admin']);
+/** What a team member gets without a grant; `none` hides the workspace from them (§3.1). */
+export const defaultRoleSchema = z.enum(['none', 'viewer', 'editor']);
+export const roleSourceSchema = z.enum(['server-admin', 'team-admin', 'grant', 'default']);
+/** A role as the access list shows it: a team member may have `none`. */
+export const effectiveRoleSchema = z.enum(['none', 'viewer', 'editor', 'admin']);
+// ---- teams -------------------------------------------------------------------------------
+export const teamSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    /** A server admin sees every team as `admin`. */
+    myRole: teamRoleSchema,
+    createdAt: z.string(),
+});
+export const teamsResponseSchema = z.array(teamSchema);
+export const teamNameRequestSchema = z.object({ name: teamsNameSchema });
+export const teamParamsSchema = z.object({ teamId: teamsIdSchema });
+// ---- members -----------------------------------------------------------------------------
+export const teamMemberSchema = z.object({
+    userId: z.string(),
+    email: z.string(),
+    displayName: z.string(),
+    role: teamRoleSchema,
+    /** §16 question 4: a disabled user stays listed, marked, and removable. */
+    disabled: z.boolean(),
+    addedAt: z.string(),
+});
+export const teamMembersResponseSchema = z.array(teamMemberSchema);
+export const memberAddRequestSchema = z.object({ email: emailSchema, role: teamRoleSchema });
+export const memberRoleRequestSchema = z.object({ role: teamRoleSchema });
+export const memberParamsSchema = z.object({ teamId: teamsIdSchema, userId: teamsIdSchema });
+// ---- invitations -------------------------------------------------------------------------
+export const teamInvitationSchema = z.object({
+    id: z.string(),
+    email: z.string(),
+    role: teamRoleSchema,
+    createdBy: z.string().nullable(),
+    createdAt: z.string(),
+    expiresAt: z.string(),
+});
+export const teamInvitationsResponseSchema = z.array(teamInvitationSchema);
+export const teamInvitationCreateRequestSchema = z.object({ email: emailSchema, role: teamRoleSchema });
+/** The link is in this answer and nowhere else: the server stores only the secret's hash. */
+export const teamInvitationCreatedSchema = z.object({
+    id: z.string(),
+    email: z.string(),
+    role: teamRoleSchema,
+    url: z.string().url(),
+    expiresAt: z.string(),
+});
+export const teamInvitationParamsSchema = z.object({ teamId: teamsIdSchema, id: teamsIdSchema });
+// ---- workspaces --------------------------------------------------------------------------
+export const teamWorkspaceSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    teamId: z.string(),
+    teamName: z.string(),
+    defaultRole: defaultRoleSchema,
+    myRole: workspaceRoleSchema,
+    source: roleSourceSchema,
+    /** Whether the desktop uploads request and run metadata for this workspace to the audit log. */
+    recordDesktopActivity: z.boolean().default(false),
+    createdAt: z.string(),
+});
+export const teamWorkspacesResponseSchema = z.array(teamWorkspaceSchema);
+export const teamWorkspaceCreateRequestSchema = z.object({
+    /** The workspace manifest's ULID, so the server id equals the local one (server-sync §3.2). */
+    id: teamsIdSchema.optional(),
+    name: teamsNameSchema,
+    defaultRole: defaultRoleSchema.optional(),
+});
+export const teamWorkspaceUpdateRequestSchema = z.object({
+    name: teamsNameSchema.optional(),
+    defaultRole: defaultRoleSchema.optional(),
+    recordDesktopActivity: z.boolean().optional(),
+});
+export const teamWorkspaceParamsSchema = z.object({ workspaceId: teamsIdSchema });
+// ---- access ------------------------------------------------------------------------------
+/** One team member as a workspace admin sees them: what they can do, why, and any grant. */
+export const accessEntrySchema = z.object({
+    userId: z.string(),
+    email: z.string(),
+    displayName: z.string(),
+    teamRole: teamRoleSchema,
+    disabled: z.boolean(),
+    effectiveRole: effectiveRoleSchema,
+    /** Absent exactly when `effectiveRole` is `none`. */
+    source: roleSourceSchema.optional(),
+    grant: workspaceRoleSchema.optional(),
+});
+export const accessResponseSchema = z.array(accessEntrySchema);
+export const accessParamsSchema = z.object({ workspaceId: teamsIdSchema, userId: teamsIdSchema });
+export const setAccessRequestSchema = z.object({ role: workspaceRoleSchema });

package/dist/snapshot/diff.d.ts

@@ -0,0 +1,30 @@
+/** How a snapshot body is compared: semantically for `json`/`xml`, exactly for `text`. */
+export type SnapshotFormat = 'json' | 'xml' | 'text';
+/** One difference {@link diffSnapshot} found between the golden and the actual body. */
+export interface SnapshotChange {
+    readonly kind: 'added' | 'removed' | 'changed';
+    readonly path: string;
+    readonly expected?: string;
+    readonly actual?: string;
+}
+/** The result of comparing a golden body against a newly received one. */
+export interface SnapshotDiff {
+    readonly format: SnapshotFormat;
+    readonly changes: readonly SnapshotChange[];
+    readonly ignored: number;
+    readonly error?: string;
+}
+/**
+ * Semantically compares a golden body against a newly received one. JSON
+ * and XML are compared structurally (see {@link diffJson} and
+ * {@link diffXml}); anything else, or a body that fails to parse in its
+ * declared format, falls back to an exact text comparison and — for the
+ * parse-failure case — sets `error`.
+ *
+ * Changes that a rule in `options.ignore` covers are dropped from the
+ * result and counted in `ignored` instead.
+ */
+export declare function diffSnapshot(golden: string, actual: string, options: {
+    format: SnapshotFormat;
+    ignore: readonly string[];
+}): SnapshotDiff;

package/dist/snapshot/diff.js

@@ -0,0 +1,75 @@
+import { isWirebenchError } from '../errors.js';
+import { truncateValue } from './format.js';
+import { diffJson } from './json-diff.js';
+import { diffXml } from './xml-diff.js';
+import { matchesIgnoreRule } from './ignore.js';
+/** Normalises line endings before an exact text comparison. */
+function normalizeLineEndings(text) {
+    return text.replace(/\r\n/g, '\n');
+}
+function diffText(golden, actual) {
+    const normalizedGolden = normalizeLineEndings(golden);
+    const normalizedActual = normalizeLineEndings(actual);
+    if (normalizedGolden === normalizedActual) {
+        return [];
+    }
+    return [
+        {
+            kind: 'changed',
+            path: '/',
+            expected: truncateValue(normalizedGolden),
+            actual: truncateValue(normalizedActual),
+        },
+    ];
+}
+/** Applies every truncation the spec asks for to a change's `expected`/`actual` values. */
+function truncateChange(change) {
+    return {
+        ...change,
+        ...(change.expected !== undefined ? { expected: truncateValue(change.expected) } : {}),
+        ...(change.actual !== undefined ? { actual: truncateValue(change.actual) } : {}),
+    };
+}
+/**
+ * Semantically compares a golden body against a newly received one. JSON
+ * and XML are compared structurally (see {@link diffJson} and
+ * {@link diffXml}); anything else, or a body that fails to parse in its
+ * declared format, falls back to an exact text comparison and — for the
+ * parse-failure case — sets `error`.
+ *
+ * Changes that a rule in `options.ignore` covers are dropped from the
+ * result and counted in `ignored` instead.
+ */
+export function diffSnapshot(golden, actual, options) {
+    let format = options.format;
+    let changes;
+    let error;
+    try {
+        switch (format) {
+            case 'json':
+                changes = diffJson(JSON.parse(golden), JSON.parse(actual));
+                break;
+            case 'xml':
+                changes = diffXml(golden, actual);
+                break;
+            default:
+                changes = diffText(golden, actual);
+        }
+    }
+    catch (cause) {
+        format = 'text';
+        error = isWirebenchError(cause) || cause instanceof Error ? cause.message : String(cause);
+        changes = diffText(golden, actual);
+    }
+    let ignored = 0;
+    const kept = [];
+    for (const change of changes) {
+        if (options.ignore.some((rule) => matchesIgnoreRule(change.path, rule))) {
+            ignored += 1;
+        }
+        else {
+            kept.push(truncateChange(change));
+        }
+    }
+    return { format, changes: kept, ignored, ...(error !== undefined ? { error } : {}) };
+}

package/dist/snapshot/format.d.ts

@@ -0,0 +1,17 @@
+import type { SnapshotFormat } from './diff.js';
+/** Values truncate to this many characters when shown in a {@link SnapshotChange}. */
+export declare const MAX_VALUE_LENGTH = 200;
+/**
+ * Truncates `value` to at most {@link MAX_VALUE_LENGTH} characters, the
+ * ellipsis that marks a cut included. Used for every `expected`/`actual`
+ * value a snapshot diff reports, so a large body never balloons the diff
+ * output.
+ */
+export declare function truncateValue(value: string): string;
+/**
+ * Decides whether a snapshot body should be compared as JSON, XML or plain
+ * text. `contentType` (when given) takes priority, since it's the type
+ * recorded alongside the golden; otherwise the trimmed body's first
+ * character decides.
+ */
+export declare function detectSnapshotFormat(body: string, contentType?: string): SnapshotFormat;

package/dist/snapshot/format.js

@@ -0,0 +1,40 @@
+/** Values truncate to this many characters when shown in a {@link SnapshotChange}. */
+export const MAX_VALUE_LENGTH = 200;
+/**
+ * Truncates `value` to at most {@link MAX_VALUE_LENGTH} characters, the
+ * ellipsis that marks a cut included. Used for every `expected`/`actual`
+ * value a snapshot diff reports, so a large body never balloons the diff
+ * output.
+ */
+export function truncateValue(value) {
+    if (value.length <= MAX_VALUE_LENGTH) {
+        return value;
+    }
+    return `${value.slice(0, MAX_VALUE_LENGTH - 1)}…`;
+}
+/**
+ * Decides whether a snapshot body should be compared as JSON, XML or plain
+ * text. `contentType` (when given) takes priority, since it's the type
+ * recorded alongside the golden; otherwise the trimmed body's first
+ * character decides.
+ */
+export function detectSnapshotFormat(body, contentType) {
+    if (contentType !== undefined) {
+        // Media types are case-insensitive (RFC 9110 §8.3.1).
+        const type = contentType.toLowerCase();
+        if (type.includes('json')) {
+            return 'json';
+        }
+        if (type.includes('xml')) {
+            return 'xml';
+        }
+    }
+    const trimmed = body.trim();
+    if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+        return 'json';
+    }
+    if (trimmed.startsWith('<')) {
+        return 'xml';
+    }
+    return 'text';
+}

package/dist/snapshot/golden-file.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Reads and writes a request's golden response: the `<slug>.golden.yaml` sidecar beside its request
+ * file (snapshot regression, #34). Shared by the desktop's Snapshot tab and the runner's `--baseline`
+ * (#36) and `--update-baseline` (#217), so the file is read and written one way. Uses `node:fs`, so it is exported from the main entry only —
+ * never from the `@wirebench/engine/snapshot` subpath, which the renderer imports.
+ *
+ * An ancestor folder swapped for a symlink between the containment check and the rename is not
+ * guarded: Node has no `openat` (#219).
+ */
+import type { Project } from '../project/model.js';
+export interface GoldenFile {
+    readonly contentType?: string;
+    readonly savedAt: string;
+    readonly ignore: readonly string[];
+    readonly body: string;
+}
+export type GoldenRead = {
+    readonly status: 'none';
+} | {
+    readonly status: 'present';
+    readonly golden: GoldenFile;
+} | {
+    readonly status: 'unreadable';
+    readonly reason: 'not-a-file' | 'malformed';
+};
+/**
+ * The golden saved for `requestId` in the project saved at `projectDir`. `none` when the request
+ * has no file location, its folder leaves the project, its `*.request.yaml` is not on disk, or no
+ * sidecar exists. The sidecar's own name is checked with `lstat`, never followed, and read through
+ * the one handle that was checked.
+ */
+export declare function readGoldenFile(projectDir: string, project: Project, requestId: string): Promise<GoldenRead>;
+export type GoldenWrite = {
+    readonly status: 'written';
+    readonly file: string;
+} | {
+    readonly status: 'refused';
+    readonly reason: 'unsaved' | 'not-a-file';
+};
+/**
+ * Saves `golden` as `requestId`'s sidecar, atomically: a uniquely named temp file, then a rename
+ * over it. Refuses an unsaved request, and a sidecar path that holds a symlink, a folder or
+ * anything but a regular file (it is never followed). A failed write removes the temp file and throws.
+ */
+export declare function writeGoldenFile(projectDir: string, project: Project, requestId: string, golden: GoldenFile): Promise<GoldenWrite>;