@yargote/artifacts-contracts 0.0.0-stage → 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yerson Argote
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,13 @@
-# Temporary Holding Version
+# Artifacts contracts
 
-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.
+`@yargote/artifacts-contracts` contains strict domain schemas, types, `ArtifactError`, snapshot serialization, and pure retained-edit helpers. It has no database, ZIP, server, or CLI dependency. Node 24 or later is required.
+
+```sh
+npm install @yargote/artifacts-contracts@0.1.0-beta.1
+```
+
+The root export contains domain schemas and types. `/workflow` contains `prepareArtifactEdit`, revision comparison, and compact projections. `/serialization` contains canonical JSON and SHA-256. `/http` contains HTTP response schemas, identity, canonical resource validation, and route URL helpers.
+
+The existing `@artifacts/artifacts` root, `/contracts`, and `/workflow` exports re-export these implementations. Store and REST packages share one `ArtifactError` runtime.
+
+This package is MIT licensed. The license applies to this package and does not license the private Artifacts application repository.

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@yargote/artifacts-contracts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-beta.1",
+  "private": false,
+  "type": "module",
+  "description": "Shared schemas and contracts for Artifacts clients.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yersonargotev/artifacts.git",
+    "directory": "packages/contracts"
+  },
+  "homepage": "https://github.com/yersonargotev",
+  "bugs": {
+    "url": "https://github.com/yersonargotev"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./workflow": "./src/workflow.js",
+    "./serialization": "./src/serialization.js",
+    "./http": "./src/http.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "zod": "4.6.5"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta",
+    "provenance": false
+  }
+}

package/src/http.d.ts

@@ -0,0 +1,195 @@
+import { z } from 'zod';
+export declare const identitySchema: z.ZodObject<{
+    userId: z.ZodString;
+    sessionId: z.ZodString;
+    clientId: z.ZodString;
+    scopes: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type Identity = z.infer<typeof identitySchema>;
+export declare const attachmentSummarySchema: z.ZodObject<{
+    path: z.ZodString;
+    mediaType: z.ZodString;
+    encoding: z.ZodEnum<{
+        utf8: "utf8";
+        base64: "base64";
+    }>;
+    decodedBytes: z.ZodNumber;
+    sha256: z.ZodString;
+}, z.core.$strict>;
+export declare const revisionSummarySchema: z.ZodObject<{
+    id: z.ZodString;
+    createdAt: z.ZodISODateTime;
+    parentRevisionId: z.ZodNullable<z.ZodString>;
+    sequence: z.ZodNumber;
+    authorUserId: z.ZodString;
+    authorClientId: z.ZodString;
+    sha256: z.ZodString;
+    metadata: z.ZodObject<{
+        description: z.ZodString;
+        title: z.ZodString;
+    }, z.core.$strict>;
+    content: z.ZodObject<{
+        kind: z.ZodEnum<{
+            text: "text";
+            html: "html";
+            markdown: "markdown";
+        }>;
+        utf8Bytes: z.ZodNumber;
+    }, z.core.$strict>;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        mediaType: z.ZodString;
+        encoding: z.ZodEnum<{
+            utf8: "utf8";
+            base64: "base64";
+        }>;
+        decodedBytes: z.ZodNumber;
+        sha256: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const compactArtifactReadSchema: z.ZodObject<{
+    ownerId: z.ZodString;
+    headRevisionId: z.ZodString;
+    artifactId: z.ZodString;
+    publication: z.ZodNullable<z.ZodObject<{
+        revisionId: z.ZodString;
+        version: z.ZodNumber;
+        url: z.ZodURL;
+    }, z.core.$strict>>;
+    revision: z.ZodObject<{
+        id: z.ZodString;
+        createdAt: z.ZodISODateTime;
+        parentRevisionId: z.ZodNullable<z.ZodString>;
+        sequence: z.ZodNumber;
+        authorUserId: z.ZodString;
+        authorClientId: z.ZodString;
+        sha256: z.ZodString;
+        metadata: z.ZodObject<{
+            description: z.ZodString;
+            title: z.ZodString;
+        }, z.core.$strict>;
+        content: z.ZodObject<{
+            kind: z.ZodEnum<{
+                text: "text";
+                html: "html";
+                markdown: "markdown";
+            }>;
+            utf8Bytes: z.ZodNumber;
+        }, z.core.$strict>;
+        files: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            mediaType: z.ZodString;
+            encoding: z.ZodEnum<{
+                utf8: "utf8";
+                base64: "base64";
+            }>;
+            decodedBytes: z.ZodNumber;
+            sha256: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const artifactSummarySchema: z.ZodObject<{
+    artifactId: z.ZodString;
+    title: z.ZodString;
+    headRevisionId: z.ZodString;
+    createdAt: z.ZodISODateTime;
+    publication: z.ZodNullable<z.ZodObject<{
+        revisionId: z.ZodString;
+        version: z.ZodNumber;
+        url: z.ZodURL;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const listResultSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        artifactId: z.ZodString;
+        title: z.ZodString;
+        headRevisionId: z.ZodString;
+        createdAt: z.ZodISODateTime;
+        publication: z.ZodNullable<z.ZodObject<{
+            revisionId: z.ZodString;
+            version: z.ZodNumber;
+            url: z.ZodURL;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export declare const historyResultSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        parentRevisionId: z.ZodNullable<z.ZodString>;
+        sequence: z.ZodNumber;
+        authorUserId: z.ZodString;
+        authorClientId: z.ZodString;
+        createdAt: z.ZodISODateTime;
+        sha256: z.ZodString;
+        snapshot: z.ZodObject<{
+            metadata: z.ZodObject<{
+                title: z.ZodString;
+                description: z.ZodString;
+                custom: z.ZodOptional<z.ZodJSONSchema>;
+            }, z.core.$strict>;
+            content: z.ZodObject<{
+                kind: z.ZodEnum<{
+                    text: "text";
+                    html: "html";
+                    markdown: "markdown";
+                }>;
+                text: z.ZodString;
+            }, z.core.$strict>;
+            files: z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                mediaType: z.ZodString;
+                encoding: z.ZodEnum<{
+                    utf8: "utf8";
+                    base64: "base64";
+                }>;
+                data: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    nextBeforeSequence: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const summaryHistoryResultSchema: z.ZodObject<{
+    nextBeforeSequence: z.ZodNullable<z.ZodNumber>;
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        createdAt: z.ZodISODateTime;
+        parentRevisionId: z.ZodNullable<z.ZodString>;
+        sequence: z.ZodNumber;
+        authorUserId: z.ZodString;
+        authorClientId: z.ZodString;
+        sha256: z.ZodString;
+        metadata: z.ZodObject<{
+            description: z.ZodString;
+            title: z.ZodString;
+        }, z.core.$strict>;
+        content: z.ZodObject<{
+            kind: z.ZodEnum<{
+                text: "text";
+                html: "html";
+                markdown: "markdown";
+            }>;
+            utf8Bytes: z.ZodNumber;
+        }, z.core.$strict>;
+        files: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            mediaType: z.ZodString;
+            encoding: z.ZodEnum<{
+                utf8: "utf8";
+                base64: "base64";
+            }>;
+            decodedBytes: z.ZodNumber;
+            sha256: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const httpErrorSchema: z.ZodObject<{
+    error: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        details: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare function canonicalResource(value: string): string;
+export declare function protectedResourceMetadataUrl(resource: string): URL;
+export declare function restBase(resource: string): string;

package/src/http.js

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+import { artifactReadSchema, publicationSchema, revisionSchema, snapshotSchema } from "./index.js";
+const identifier = z.string().min(1).max(128);
+const digest = z.string().regex(/^[a-f0-9]{64}$/);
+export const identitySchema = z.strictObject({ userId: identifier, sessionId: identifier, clientId: identifier, scopes: z.array(z.string()) });
+export const attachmentSummarySchema = z.strictObject({ path: z.string(), mediaType: z.string(), encoding: z.enum(['utf8', 'base64']), decodedBytes: z.number().int().nonnegative(), sha256: digest });
+export const revisionSummarySchema = revisionSchema.omit({ snapshot: true }).extend({
+    metadata: snapshotSchema.shape.metadata.pick({ title: true, description: true }),
+    content: z.strictObject({ kind: snapshotSchema.shape.content.shape.kind, utf8Bytes: z.number().int().nonnegative() }),
+    files: z.array(attachmentSummarySchema).max(32),
+});
+export const compactArtifactReadSchema = artifactReadSchema.omit({ revision: true }).extend({ revision: revisionSummarySchema });
+export const artifactSummarySchema = z.strictObject({ artifactId: identifier, title: z.string(), headRevisionId: identifier, createdAt: z.iso.datetime(), publication: publicationSchema.nullable() });
+export const listResultSchema = z.strictObject({ items: z.array(artifactSummarySchema).max(100), nextCursor: identifier.nullable() });
+export const historyResultSchema = z.strictObject({ items: z.array(revisionSchema).max(10), nextBeforeSequence: z.number().int().positive().nullable() });
+export const summaryHistoryResultSchema = historyResultSchema.extend({ items: z.array(revisionSummarySchema).max(10) });
+export const httpErrorSchema = z.strictObject({ error: z.strictObject({ code: z.string().min(1), message: z.string(), details: z.record(z.string(), z.unknown()) }) });
+export function canonicalResource(value) {
+    const url = new URL(value);
+    const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+    if (url.username || url.password || url.search || url.hash || (url.protocol !== 'https:' && !(loopback && url.protocol === 'http:')))
+        throw new TypeError('The server requires HTTPS, or HTTP on an exact loopback host, without credentials, query, or fragment');
+    if ((url.href !== value && url.href.replace(/\/$/, '') !== value) || (url.pathname !== '/' && url.pathname.endsWith('/')))
+        throw new TypeError('Use the exact canonical resource URL without a trailing slash');
+    return value;
+}
+export function protectedResourceMetadataUrl(resource) {
+    const url = new URL(canonicalResource(resource));
+    return new URL(`/.well-known/oauth-protected-resource${url.pathname === '/' ? '' : url.pathname}`, url.origin);
+}
+export function restBase(resource) {
+    return `${canonicalResource(resource).replace(/\/$/, '')}/v1`;
+}

package/src/index.d.ts

@@ -0,0 +1,295 @@
+import { z } from 'zod';
+export declare const snapshotSchema: z.ZodObject<{
+    metadata: z.ZodObject<{
+        title: z.ZodString;
+        description: z.ZodString;
+        custom: z.ZodOptional<z.ZodJSONSchema>;
+    }, z.core.$strict>;
+    content: z.ZodObject<{
+        kind: z.ZodEnum<{
+            text: "text";
+            html: "html";
+            markdown: "markdown";
+        }>;
+        text: z.ZodString;
+    }, z.core.$strict>;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        mediaType: z.ZodString;
+        encoding: z.ZodEnum<{
+            utf8: "utf8";
+            base64: "base64";
+        }>;
+        data: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const createSchema: z.ZodObject<{
+    requestId: z.ZodString;
+    snapshot: z.ZodObject<{
+        metadata: z.ZodObject<{
+            title: z.ZodString;
+            description: z.ZodString;
+            custom: z.ZodOptional<z.ZodJSONSchema>;
+        }, z.core.$strict>;
+        content: z.ZodObject<{
+            kind: z.ZodEnum<{
+                text: "text";
+                html: "html";
+                markdown: "markdown";
+            }>;
+            text: z.ZodString;
+        }, z.core.$strict>;
+        files: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            mediaType: z.ZodString;
+            encoding: z.ZodEnum<{
+                utf8: "utf8";
+                base64: "base64";
+            }>;
+            data: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    response: z.ZodOptional<z.ZodEnum<{
+        full: "full";
+        compact: "compact";
+    }>>;
+}, z.core.$strict>;
+export declare const readSchema: z.ZodObject<{
+    artifactId: z.ZodString;
+    revisionId: z.ZodOptional<z.ZodString>;
+    response: z.ZodOptional<z.ZodEnum<{
+        full: "full";
+        compact: "compact";
+    }>>;
+}, z.core.$strict>;
+export declare const updateSchema: z.ZodObject<{
+    requestId: z.ZodString;
+    artifactId: z.ZodString;
+    expectedRevisionId: z.ZodString;
+    snapshot: z.ZodObject<{
+        metadata: z.ZodObject<{
+            title: z.ZodString;
+            description: z.ZodString;
+            custom: z.ZodOptional<z.ZodJSONSchema>;
+        }, z.core.$strict>;
+        content: z.ZodObject<{
+            kind: z.ZodEnum<{
+                text: "text";
+                html: "html";
+                markdown: "markdown";
+            }>;
+            text: z.ZodString;
+        }, z.core.$strict>;
+        files: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            mediaType: z.ZodString;
+            encoding: z.ZodEnum<{
+                utf8: "utf8";
+                base64: "base64";
+            }>;
+            data: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    response: z.ZodOptional<z.ZodEnum<{
+        full: "full";
+        compact: "compact";
+    }>>;
+}, z.core.$strict>;
+export declare const publishSchema: z.ZodObject<{
+    requestId: z.ZodString;
+    artifactId: z.ZodString;
+    revisionId: z.ZodString;
+    expectedPublicationVersion: z.ZodNumber;
+}, z.core.$strict>;
+export declare const exportSchema: z.ZodObject<{
+    artifactId: z.ZodString;
+    revisionId: z.ZodString;
+}, z.core.$strict>;
+export declare const listSchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodNumber>;
+    cursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const libraryQuerySchema: z.ZodObject<{
+    q: z.ZodDefault<z.ZodString>;
+    status: z.ZodDefault<z.ZodEnum<{
+        all: "all";
+        published: "published";
+        unpublished: "unpublished";
+        pending: "pending";
+    }>>;
+    cursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const historySchema: z.ZodObject<{
+    artifactId: z.ZodString;
+    limit: z.ZodDefault<z.ZodNumber>;
+    beforeSequence: z.ZodOptional<z.ZodNumber>;
+    response: z.ZodOptional<z.ZodEnum<{
+        full: "full";
+        summary: "summary";
+    }>>;
+}, z.core.$strict>;
+export declare const issueGrantSchema: z.ZodObject<{
+    artifactId: z.ZodString;
+    state: z.ZodString;
+}, z.core.$strict>;
+export declare const consumeGrantSchema: z.ZodObject<{
+    artifactId: z.ZodString;
+    state: z.ZodString;
+    code: z.ZodString;
+}, z.core.$strict>;
+export declare const viewerSchema: z.ZodObject<{
+    artifactId: z.ZodString;
+    userId: z.ZodString;
+    sessionId: z.ZodString;
+    expiresAt: z.ZodNumber;
+}, z.core.$strict>;
+export type Snapshot = z.infer<typeof snapshotSchema>;
+export type ReadonlyJsonValue = string | number | boolean | null | {
+    readonly [key: string]: ReadonlyJsonValue;
+} | readonly ReadonlyJsonValue[];
+export type UpdateInput = {
+    readonly requestId: string;
+    readonly artifactId: string;
+    readonly expectedRevisionId: string;
+    readonly snapshot: {
+        readonly metadata: {
+            readonly title: string;
+            readonly description: string;
+            readonly custom?: ReadonlyJsonValue;
+        };
+        readonly content: Readonly<Snapshot['content']>;
+        readonly files: readonly Readonly<Snapshot['files'][number]>[];
+    };
+    readonly response?: 'full' | 'compact';
+};
+export type Actor = Readonly<{
+    userId: string;
+    sessionId: string;
+    clientId: string;
+    scopes: readonly string[];
+}>;
+export type Viewer = z.infer<typeof viewerSchema>;
+export type Publication = z.infer<typeof publicationSchema>;
+export type Revision = z.infer<typeof revisionSchema>;
+export type ArtifactRead = z.infer<typeof artifactReadSchema>;
+export type ArtifactSummary = {
+    artifactId: string;
+    title: string;
+    headRevisionId: string;
+    createdAt: string;
+    publication: Publication | null;
+};
+export type ArtifactLibraryQuery = z.infer<typeof libraryQuerySchema>;
+export type ArtifactLibraryPage = {
+    items: ArtifactSummary[];
+    nextCursor: string | null;
+    counts: {
+        all: number;
+        published: number;
+        unpublished: number;
+        pending: number;
+    };
+};
+export type Archive = {
+    filename: string;
+    mediaType: 'application/zip';
+    base64: string;
+    sha256: string;
+};
+export type ArtifactErrorCode = 'forbidden' | 'not_found' | 'conflict' | 'request_conflict' | 'invalid_grant';
+export declare class ArtifactError extends Error {
+    readonly code: ArtifactErrorCode;
+    readonly details: Record<string, unknown>;
+    constructor(code: ArtifactErrorCode, message: string, details?: Record<string, unknown>);
+}
+export declare function decodeFile(file: {
+    encoding: 'utf8' | 'base64';
+    data: string;
+}): Uint8Array;
+export declare const publicationSchema: z.ZodObject<{
+    revisionId: z.ZodString;
+    version: z.ZodNumber;
+    url: z.ZodURL;
+}, z.core.$strict>;
+export declare const revisionSchema: z.ZodObject<{
+    id: z.ZodString;
+    parentRevisionId: z.ZodNullable<z.ZodString>;
+    sequence: z.ZodNumber;
+    authorUserId: z.ZodString;
+    authorClientId: z.ZodString;
+    createdAt: z.ZodISODateTime;
+    sha256: z.ZodString;
+    snapshot: z.ZodObject<{
+        metadata: z.ZodObject<{
+            title: z.ZodString;
+            description: z.ZodString;
+            custom: z.ZodOptional<z.ZodJSONSchema>;
+        }, z.core.$strict>;
+        content: z.ZodObject<{
+            kind: z.ZodEnum<{
+                text: "text";
+                html: "html";
+                markdown: "markdown";
+            }>;
+            text: z.ZodString;
+        }, z.core.$strict>;
+        files: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            mediaType: z.ZodString;
+            encoding: z.ZodEnum<{
+                utf8: "utf8";
+                base64: "base64";
+            }>;
+            data: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const artifactReadSchema: z.ZodObject<{
+    artifactId: z.ZodString;
+    ownerId: z.ZodString;
+    headRevisionId: z.ZodString;
+    publication: z.ZodNullable<z.ZodObject<{
+        revisionId: z.ZodString;
+        version: z.ZodNumber;
+        url: z.ZodURL;
+    }, z.core.$strict>>;
+    revision: z.ZodObject<{
+        id: z.ZodString;
+        parentRevisionId: z.ZodNullable<z.ZodString>;
+        sequence: z.ZodNumber;
+        authorUserId: z.ZodString;
+        authorClientId: z.ZodString;
+        createdAt: z.ZodISODateTime;
+        sha256: z.ZodString;
+        snapshot: z.ZodObject<{
+            metadata: z.ZodObject<{
+                title: z.ZodString;
+                description: z.ZodString;
+                custom: z.ZodOptional<z.ZodJSONSchema>;
+            }, z.core.$strict>;
+            content: z.ZodObject<{
+                kind: z.ZodEnum<{
+                    text: "text";
+                    html: "html";
+                    markdown: "markdown";
+                }>;
+                text: z.ZodString;
+            }, z.core.$strict>;
+            files: z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                mediaType: z.ZodString;
+                encoding: z.ZodEnum<{
+                    utf8: "utf8";
+                    base64: "base64";
+                }>;
+                data: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const publishResultSchema: z.ZodObject<{
+    revisionId: z.ZodString;
+    version: z.ZodNumber;
+    url: z.ZodURL;
+    artifactId: z.ZodString;
+}, z.core.$strict>;

package/src/index.js

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+const identifier = z.string().min(1).max(128);
+const requestId = z.string().min(8).max(128);
+const fileSchema = z.strictObject({
+    path: z.string().min(1).max(240).refine((path) => path === path.normalize('NFC') && !/[:\\%\x00-\x1f\x7f]/.test(path) && path.split('/').every((part) => part !== '' && part !== '.' && part !== '..'), 'Use a normalized relative file path'),
+    mediaType: z.string().max(128).regex(/^[a-zA-Z0-9!#$&^_.+-]+\/[a-zA-Z0-9!#$&^_.+-]+$/),
+    encoding: z.enum(['utf8', 'base64']),
+    data: z.string().max(1_398_104).refine((data) => data.isWellFormed(), 'File text must contain well-formed Unicode'),
+}).superRefine((file, context) => {
+    if (file.encoding === 'base64' && Buffer.from(file.data, 'base64').toString('base64') !== file.data)
+        context.addIssue({ code: 'custom', path: ['data'], message: 'Use canonical padded base64' });
+});
+export const snapshotSchema = z.strictObject({
+    metadata: z.strictObject({ title: z.string().min(1).max(256), description: z.string().max(8192), custom: z.json().optional() }),
+    content: z.strictObject({ kind: z.enum(['html', 'markdown', 'text']), text: z.string().max(1_048_576).refine((text) => text.isWellFormed(), 'Content must contain well-formed Unicode') }),
+    files: z.array(fileSchema).max(32),
+}).superRefine((snapshot, context) => {
+    const paths = snapshot.files.map((file) => file.path);
+    if (paths.some((path, index) => paths.some((other, otherIndex) => index !== otherIndex && (path === other || other.startsWith(`${path}/`)))))
+        context.addIssue({ code: 'custom', path: ['files'], message: 'File paths must be unique and cannot contain another file' });
+    const bytes = Buffer.byteLength(JSON.stringify(snapshot.metadata)) + Buffer.byteLength(snapshot.content.text) + snapshot.files.reduce((total, file) => total + Buffer.byteLength(file.path) + Buffer.byteLength(file.mediaType) + decodeFile(file).length, 0);
+    if (bytes > 1_048_576)
+        context.addIssue({ code: 'custom', message: 'A revision must fit within 1 MiB of decoded content and metadata' });
+});
+const response = z.enum(['full', 'compact']).optional();
+export const createSchema = z.strictObject({ requestId, snapshot: snapshotSchema, response });
+export const readSchema = z.strictObject({ artifactId: identifier, revisionId: identifier.optional(), response });
+export const updateSchema = z.strictObject({ requestId, artifactId: identifier, expectedRevisionId: identifier, snapshot: snapshotSchema, response });
+export const publishSchema = z.strictObject({ requestId, artifactId: identifier, revisionId: identifier, expectedPublicationVersion: z.number().int().nonnegative() });
+export const exportSchema = z.strictObject({ artifactId: identifier, revisionId: identifier });
+export const listSchema = z.strictObject({ limit: z.number().int().min(1).max(100).default(25), cursor: identifier.optional() });
+export const libraryQuerySchema = z.strictObject({
+    q: z.string().trim().max(256).default(''),
+    status: z.enum(['all', 'published', 'unpublished', 'pending']).default('all'),
+    cursor: identifier.optional(),
+});
+export const historySchema = z.strictObject({ artifactId: identifier, limit: z.number().int().min(1).max(10).default(5), beforeSequence: z.number().int().positive().optional(), response: z.enum(['full', 'summary']).optional() });
+export const issueGrantSchema = z.strictObject({ artifactId: identifier, state: z.string().min(16).max(256) });
+export const consumeGrantSchema = issueGrantSchema.extend({ code: z.string().min(32).max(128) });
+export const viewerSchema = z.strictObject({ artifactId: identifier, userId: identifier, sessionId: identifier, expiresAt: z.number().int().positive() });
+export class ArtifactError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.code = code;
+        this.details = details;
+    }
+}
+export function decodeFile(file) {
+    return Buffer.from(file.data, file.encoding === 'utf8' ? 'utf8' : 'base64');
+}
+export const publicationSchema = z.strictObject({ revisionId: identifier, version: z.number().int().positive(), url: z.url() });
+export const revisionSchema = z.strictObject({ id: identifier, parentRevisionId: identifier.nullable(), sequence: z.number().int().positive(), authorUserId: identifier, authorClientId: identifier, createdAt: z.iso.datetime(), sha256: z.string().regex(/^[a-f0-9]{64}$/), snapshot: snapshotSchema });
+export const artifactReadSchema = z.strictObject({ artifactId: identifier, ownerId: identifier, headRevisionId: identifier, publication: publicationSchema.nullable(), revision: revisionSchema });
+export const publishResultSchema = publicationSchema.extend({ artifactId: identifier });

package/src/serialization.d.ts

@@ -0,0 +1,2 @@
+export declare function canonicalJson(value: unknown): string;
+export declare function sha256(value: string | Uint8Array): Promise<string>;

package/src/serialization.js

@@ -0,0 +1,11 @@
+export function canonicalJson(value) {
+    return JSON.stringify(value, (_key, item) => {
+        if (item && typeof item === 'object' && !Array.isArray(item))
+            return Object.fromEntries(Object.entries(item).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0));
+        return item;
+    });
+}
+export async function sha256(value) {
+    const bytes = typeof value === 'string' ? new TextEncoder().encode(value) : new Uint8Array(value);
+    return Buffer.from(await crypto.subtle.digest('SHA-256', bytes)).toString('hex');
+}

package/src/workflow.d.ts

@@ -0,0 +1,75 @@
+import { type ArtifactRead, type Revision, type Snapshot, type UpdateInput } from './index.ts';
+export type { UpdateInput } from './index.ts';
+export type AttachmentSummary = {
+    path: string;
+    mediaType: string;
+    encoding: 'utf8' | 'base64';
+    decodedBytes: number;
+    sha256: string;
+};
+export type RevisionSummary = Omit<Revision, 'snapshot'> & {
+    metadata: Pick<Snapshot['metadata'], 'title' | 'description'>;
+    content: {
+        kind: Snapshot['content']['kind'];
+        utf8Bytes: number;
+    };
+    files: AttachmentSummary[];
+};
+export type CompactArtifactRead = Omit<ArtifactRead, 'revision'> & {
+    revision: RevisionSummary;
+};
+export type MetadataChange = {
+    field: 'title' | 'description';
+    before: string;
+    after: string;
+} | {
+    field: 'custom';
+    before?: Snapshot['metadata']['custom'];
+    after?: Snapshot['metadata']['custom'];
+};
+export type AttachmentChange = {
+    path: string;
+    change: 'added';
+    before: null;
+    after: AttachmentSummary;
+} | {
+    path: string;
+    change: 'removed';
+    before: AttachmentSummary;
+    after: null;
+} | {
+    path: string;
+    change: 'changed';
+    before: AttachmentSummary;
+    after: AttachmentSummary;
+};
+export type RevisionComparison = {
+    beforeRevisionId: string;
+    afterRevisionId: string;
+    metadata: MetadataChange[];
+    content: {
+        before: Snapshot['content'];
+        after: Snapshot['content'];
+        kindChanged: boolean;
+        textChanged: boolean;
+    };
+    files: AttachmentChange[];
+};
+export declare function summarizeRevision(revision: Revision): Promise<RevisionSummary>;
+export declare function compactArtifactRead(document: ArtifactRead): Promise<CompactArtifactRead>;
+export declare function compareRevisions(before: Revision, after: Revision): Promise<RevisionComparison>;
+export type ArtifactEditClient = {
+    read(input: {
+        artifactId: string;
+    }): Promise<ArtifactRead>;
+};
+export type PrepareArtifactEditInput = {
+    artifactId: string;
+    requestId: string;
+    changes: {
+        metadata?: Partial<Snapshot['metadata']>;
+        content?: Partial<Snapshot['content']>;
+        files?: Snapshot['files'];
+    };
+};
+export declare function prepareArtifactEdit(client: ArtifactEditClient, value: PrepareArtifactEditInput): Promise<UpdateInput>;

package/src/workflow.js

@@ -0,0 +1,97 @@
+import { z } from 'zod';
+import { ArtifactError, artifactReadSchema, createSchema, decodeFile, readSchema, snapshotSchema, updateSchema } from "./index.js";
+import { canonicalJson, sha256 } from "./serialization.js";
+async function summarizeFiles(files) {
+    return Promise.all([...files].sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0).map(async ({ path, mediaType, encoding, data }) => {
+        const bytes = decodeFile({ encoding, data });
+        return { path, mediaType, encoding, decodedBytes: bytes.length, sha256: await sha256(bytes) };
+    }));
+}
+export async function summarizeRevision(revision) {
+    const { snapshot, ...identity } = revision;
+    return {
+        ...identity,
+        metadata: { title: snapshot.metadata.title, description: snapshot.metadata.description },
+        content: { kind: snapshot.content.kind, utf8Bytes: Buffer.byteLength(snapshot.content.text) },
+        files: await summarizeFiles(snapshot.files),
+    };
+}
+export async function compactArtifactRead(document) {
+    const { revision, ...identity } = document;
+    return { ...identity, revision: await summarizeRevision(revision) };
+}
+export async function compareRevisions(before, after) {
+    const metadata = [];
+    for (const field of ['title', 'description']) {
+        if (before.snapshot.metadata[field] !== after.snapshot.metadata[field])
+            metadata.push({ field, before: before.snapshot.metadata[field], after: after.snapshot.metadata[field] });
+    }
+    if (canonicalJson(before.snapshot.metadata.custom) !== canonicalJson(after.snapshot.metadata.custom)) {
+        metadata.push({ field: 'custom', before: structuredClone(before.snapshot.metadata.custom), after: structuredClone(after.snapshot.metadata.custom) });
+    }
+    const [beforeFiles, afterFiles] = await Promise.all([summarizeFiles(before.snapshot.files), summarizeFiles(after.snapshot.files)]);
+    const beforeByPath = new Map(beforeFiles.map((file) => [file.path, file]));
+    const afterByPath = new Map(afterFiles.map((file) => [file.path, file]));
+    const files = [];
+    for (const path of [...new Set([...beforeByPath.keys(), ...afterByPath.keys()])].sort()) {
+        const previous = beforeByPath.get(path);
+        const next = afterByPath.get(path);
+        if (!previous && next)
+            files.push({ path, change: 'added', before: null, after: next });
+        else if (previous && !next)
+            files.push({ path, change: 'removed', before: previous, after: null });
+        else if (previous && next && (previous.sha256 !== next.sha256 || previous.mediaType !== next.mediaType || previous.encoding !== next.encoding))
+            files.push({ path, change: 'changed', before: previous, after: next });
+    }
+    return {
+        beforeRevisionId: before.id,
+        afterRevisionId: after.id,
+        metadata,
+        content: {
+            before: { ...before.snapshot.content },
+            after: { ...after.snapshot.content },
+            kindChanged: before.snapshot.content.kind !== after.snapshot.content.kind,
+            textChanged: before.snapshot.content.text !== after.snapshot.content.text,
+        },
+        files,
+    };
+}
+const prepareEditSchema = z.strictObject({
+    artifactId: readSchema.shape.artifactId,
+    requestId: createSchema.shape.requestId,
+    changes: z.strictObject({
+        metadata: snapshotSchema.shape.metadata.partial().optional(),
+        content: snapshotSchema.shape.content.partial().optional(),
+        files: snapshotSchema.shape.files.optional(),
+    }),
+});
+function freezeJson(value) {
+    if (value && typeof value === 'object') {
+        for (const child of Object.values(value))
+            freezeJson(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+export async function prepareArtifactEdit(client, value) {
+    const input = prepareEditSchema.parse(structuredClone(value));
+    const current = artifactReadSchema.parse(structuredClone(await client.read({ artifactId: input.artifactId })));
+    if (current.artifactId !== input.artifactId)
+        throw new TypeError('Artifact reader returned a different artifact');
+    if (current.revision.id !== current.headRevisionId)
+        throw new ArtifactError('conflict', 'Artifact reader did not return the current head', { currentRevisionId: current.headRevisionId });
+    const snapshot = current.revision.snapshot;
+    const metadata = { ...snapshot.metadata, ...input.changes.metadata };
+    if (Object.hasOwn(input.changes.metadata ?? {}, 'custom') && input.changes.metadata?.custom === undefined)
+        delete metadata.custom;
+    return freezeJson(updateSchema.parse({
+        artifactId: input.artifactId,
+        requestId: input.requestId,
+        expectedRevisionId: current.headRevisionId,
+        snapshot: {
+            metadata,
+            content: { ...snapshot.content, ...input.changes.content },
+            files: input.changes.files ?? snapshot.files,
+        },
+    }));
+}