@artkit-ai/core 0.1.0 → 0.2.0

package/src/engine.ts

@@ -1,14 +1,13 @@
 import { z } from 'zod';
+import type { AdapterContext, AnyFormatAdapter, ChangeSummary, LintIssue } from './adapter.js';
 import { diffFields } from './diff.js';
 import { type Artifact, localeSchema, titleSchema } from './envelope.js';
 import { ArtifactError, type ErrorIssue, formatPath, zodIssuesToErrorIssues } from './errors.js';
 import { t } from './i18n.js';
-import { findDuplicateIds, IdAllocator } from './ids.js';
-import type { AnyArtifactKind, ApplyContext, ChangeSummary, IdContext, LintIssue } from './kind.js';
 import type { ArtifactRegistry } from './registry.js';
 import { jsonByteSize, jsonDepth, MAX_INPUT_DEPTH, sanitizeDeep } from './sanitize.js';
 
-/** Envelope operations, available for every kind and handled by the core (spec §8.4). */
+/** Envelope operations, available for every format and handled by the core (spec §9.3). */
 export const envelopeOperationSchema = z.discriminatedUnion('op', [
   z.object({ op: z.literal('set_title'), title: titleSchema }).strict(),
   z.object({ op: z.literal('set_theme'), themeId: z.string().min(1).max(64) }).strict(),
@@ -46,88 +45,52 @@ export function operationNames(schema: z.ZodType): string[] {
   return names;
 }
 
-export interface PreparedContent<Content = unknown> {
-  content: Content;
-  ids: string[];
-  lint: LintIssue[];
-}
-
-export interface EngineOptions {
-  locale?: string;
-}
-
-function idContext(allocator: IdAllocator): IdContext {
-  return {
-    nextId: (prefix) => allocator.next(prefix),
-    hasId: (id) => allocator.has(id),
-    reserveId: (id) => allocator.reserve(id),
-  };
-}
-
 function checkDepth(value: unknown, path: string, locale?: string): void {
   if (jsonDepth(value) > MAX_INPUT_DEPTH) {
-    throw new ArtifactError(
-      'LIMIT_EXCEEDED',
-      t(locale, 'LIMIT_EXCEEDED', { limit: 'depth', max: MAX_INPUT_DEPTH, found: `>${MAX_INPUT_DEPTH}` }),
-      {
-        issues: [
-          {
-            path,
-            message: t(locale, 'LIMIT_EXCEEDED', {
-              limit: 'depth',
-              max: MAX_INPUT_DEPTH,
-              found: `>${MAX_INPUT_DEPTH}`,
-            }),
-          },
-        ],
-        details: { limit: 'depth', max: MAX_INPUT_DEPTH },
-      },
-    );
+    const message = t(locale, 'LIMIT_EXCEEDED', {
+      limit: 'depth',
+      max: MAX_INPUT_DEPTH,
+      found: `>${MAX_INPUT_DEPTH}`,
+    });
+    throw new ArtifactError('LIMIT_EXCEEDED', message, {
+      issues: [{ path, message }],
+      details: { limit: 'depth', max: MAX_INPUT_DEPTH },
+    });
   }
 }
 
-/** Schema + integrity + unique ids + limits. Throws INVALID_CONTENT or LIMIT_EXCEEDED. */
+/** Adapter validation + limits. Throws INVALID_CONTENT or LIMIT_EXCEEDED. Returns the normalized content. */
 export function validateContent(
   registry: ArtifactRegistry,
-  kind: AnyArtifactKind,
+  adapter: AnyFormatAdapter,
   raw: unknown,
-  locale?: string,
+  ctx: AdapterContext,
 ): unknown {
-  const parsed = kind.contentSchema.safeParse(raw);
-  if (!parsed.success) {
-    throw new ArtifactError('INVALID_CONTENT', t(locale, 'INVALID_CONTENT'), {
-      issues: zodIssuesToErrorIssues(parsed.error.issues, locale, 'content'),
-    });
-  }
-  // The parsed value carries schema defaults, so stored content is always normalized.
-  const content = parsed.data;
-  const issues: ErrorIssue[] = [...(kind.validate?.(content, locale) ?? [])].map((issue) => ({
-    ...issue,
-    path: issue.path.startsWith('content') ? issue.path : issue.path ? `content.${issue.path}` : 'content',
-  }));
-  for (const id of findDuplicateIds(kind.ids(content))) {
-    // Kinds may already report duplicates with a precise path; don't repeat them.
-    if (issues.some((issue) => issue.message.includes(`"${id}"`) || issue.message.includes(`'${id}'`)))
-      continue;
-    issues.push({
-      path: 'content',
-      message: t(locale, 'DUPLICATE_ID', { id }),
-      hint: t(locale, 'DUPLICATE_ID_HINT'),
+  const result = adapter.validate(raw, ctx);
+  if (!result.ok) {
+    throw new ArtifactError('INVALID_CONTENT', t(ctx.locale, 'INVALID_CONTENT'), {
+      issues: result.issues.map((issue) => ({
+        ...issue,
+        path: issue.path.startsWith('content')
+          ? issue.path
+          : issue.path
+            ? `content.${issue.path}`
+            : 'content',
+      })),
     });
   }
-  if (issues.length > 0) throw new ArtifactError('INVALID_CONTENT', t(locale, 'INVALID_CONTENT'), { issues });
-  checkLimits(registry, kind, content, locale);
-  return content;
+  checkLimits(registry, adapter, result.content, ctx.locale);
+  return result.content;
 }
 
 export function checkLimits(
   registry: ArtifactRegistry,
-  kind: AnyArtifactKind,
+  adapter: AnyFormatAdapter,
   content: unknown,
   locale?: string,
 ): void {
-  const limits = registry.limits(kind.kind);
-  const measured = kind.measure?.(content) ?? {};
+  const limits = registry.limits(adapter.format);
+  const measured = adapter.measure?.(content) ?? {};
   for (const [key, max] of Object.entries(limits)) {
     const found = measured[key];
     if (found !== undefined && found > max) {
@@ -140,62 +103,55 @@ export function checkLimits(
   }
 }
 
+export interface PreparedContent<Content = unknown> {
+  content: Content;
+  lint: LintIssue[];
+}
+
 /**
  * Turns raw content (from the model, a user or an alternative input) into valid content:
- * sanitize → normalize ids → derive → validate → limits. Pure.
+ * sanitize → validate → limits → lint. Pure.
  */
 export function prepareContent(
   registry: ArtifactRegistry,
-  kindName: string,
+  formatName: string,
   raw: unknown,
-  options: EngineOptions & { theme?: string } = {},
+  options: { locale?: string; themeId?: string } = {},
 ): PreparedContent {
-  const locale = options.locale;
-  const kind = registry.get(kindName, locale);
+  const locale = options.locale ?? 'en';
+  const adapter = registry.get(formatName, locale);
+  const theme = registry.theme(options.themeId ?? 'default', locale);
   checkDepth(raw, 'content', locale);
-  const sanitized = sanitizeDeep(raw);
-  const allocator = new IdAllocator(collectExplicitIds(sanitized));
-  let content = kind.normalize
-    ? kind.normalize(structuredClone(sanitized), idContext(allocator))
-    : structuredClone(sanitized);
-  const parsed = kind.contentSchema.safeParse(content);
-  if (!parsed.success) {
-    throw new ArtifactError('INVALID_CONTENT', t(locale, 'INVALID_CONTENT'), {
-      issues: zodIssuesToErrorIssues(parsed.error.issues, locale, 'content'),
+  const ctx: AdapterContext = { locale, theme, fail: failIn(locale, 0) };
+  const content = validateContent(registry, adapter, sanitizeDeep(raw), ctx);
+  return { content, lint: adapter.lint(content as never, { locale, theme }) };
+}
+
+function failIn(locale: string, index: number) {
+  return (message: string, options?: { hint?: string; path?: string }): never => {
+    throw new ArtifactError('OPERATION_FAILED', t(locale, 'OPERATION_FAILED', { index }), {
+      issues: [
+        {
+          path: options?.path ? `operations[${index}].${options.path}` : `operations[${index}]`,
+          message,
+          ...(options?.hint ? { hint: options.hint } : {}),
+        },
+      ],
+      details: { index },
     });
-  }
-  content = parsed.data;
-  kind.derive?.(content);
-  content = validateContent(registry, kind, content, locale);
-  const theme = registry.theme(options.theme ?? 'default', locale);
-  return {
-    content,
-    ids: [...kind.ids(content)],
-    lint: kind.lint(content, { locale: locale ?? 'en', theme }),
   };
 }
 
-/** Collects string values of `id` fields anywhere in raw input, so generated ids never collide with them. */
-function collectExplicitIds(value: unknown, out: string[] = [], depth = 0): string[] {
-  if (depth > MAX_INPUT_DEPTH) return out;
-  if (Array.isArray(value)) for (const item of value) collectExplicitIds(item, out, depth + 1);
-  else if (value !== null && typeof value === 'object') {
-    for (const [key, item] of Object.entries(value)) {
-      if (key === 'id' && typeof item === 'string') out.push(item);
-      else collectExplicitIds(item, out, depth + 1);
-    }
-  }
-  return out;
-}
+export type ParsedOperation = { kind: 'envelope'; op: EnvelopeOperation } | { kind: 'content'; op: unknown };
 
 export interface BatchResult<Content = unknown> {
   content: Content;
-  schemaVersion: number;
+  formatVersion: string;
   title: string;
   themeId: string;
   locale: string;
-  /** Ids that exist after the batch and did not exist before. */
-  createdIds: string[];
+  /** Anchors, declarations, ranges or sheets created by the batch. */
+  createdRefs: string[];
   diff: ChangeSummary[];
   lint: LintIssue[];
 }
@@ -203,11 +159,11 @@ export interface BatchResult<Content = unknown> {
 /** Parses and sanitizes a batch. Throws INVALID_OPERATION with the index of the first bad operation. */
 export function parseOperations(
   registry: ArtifactRegistry,
-  kindName: string,
+  formatName: string,
   operations: unknown,
   locale?: string,
-): unknown[] {
-  const kind = registry.get(kindName, locale);
+): ParsedOperation[] {
+  const adapter = registry.get(formatName, locale);
   if (!Array.isArray(operations)) {
     throw new ArtifactError('INVALID_OPERATION', t(locale, 'INVALID_OPERATIONS'), {
       issues: [
@@ -243,12 +199,20 @@ export function parseOperations(
     });
   }
   checkDepth(operations, 'operations', locale);
-  const names = [...ENVELOPE_OPERATIONS, ...operationNames(kind.operationSchema)];
+  const names = [...ENVELOPE_OPERATIONS, ...operationNames(adapter.operationSchema)];
   return operations.map((raw, index) => {
     const op = sanitizeDeep(raw);
-    const schema: z.ZodType = isEnvelopeOperation(op) ? envelopeOperationSchema : kind.operationSchema;
-    const parsed = schema.safeParse(op);
-    if (parsed.success) return parsed.data;
+    if (isEnvelopeOperation(op)) {
+      const parsed = envelopeOperationSchema.safeParse(op);
+      if (parsed.success) return { kind: 'envelope', op: parsed.data };
+      throw invalidOperation(
+        index,
+        zodIssuesToErrorIssues(parsed.error.issues, locale, `operations[${index}]`),
+        locale,
+      );
+    }
+    const parsed = adapter.operationSchema.safeParse(op);
+    if (parsed.success) return { kind: 'content', op: parsed.data };
     const issues = zodIssuesToErrorIssues(parsed.error.issues, locale, `operations[${index}]`);
     const opName = (op as { op?: unknown } | null)?.op;
     if (typeof opName !== 'string' || !names.includes(opName)) {
@@ -258,10 +222,14 @@ export function parseOperations(
         hint: t(locale, 'ZOD_INVALID_VALUE_HINT', { values: names.join(', ') }),
       });
     }
-    throw new ArtifactError('INVALID_OPERATION', t(locale, 'INVALID_OPERATION', { index }), {
-      issues: dedupeIssues(issues),
-      details: { index },
-    });
+    throw invalidOperation(index, dedupeIssues(issues), locale);
+  });
+}
+
+function invalidOperation(index: number, issues: ErrorIssue[], locale?: string): ArtifactError {
+  return new ArtifactError('INVALID_OPERATION', t(locale, 'INVALID_OPERATION', { index }), {
+    issues,
+    details: { index },
   });
 }
 
@@ -276,82 +244,75 @@ function dedupeIssues(issues: ErrorIssue[]): ErrorIssue[] {
 }
 
 /**
- * Applies a batch atomically and purely (spec §8.2 steps 4–8): validate every operation, clone,
- * apply in sequence, derive, revalidate the whole content and limits, then diff and lint.
- * Any failure throws and leaves the input untouched.
+ * Applies a batch atomically (spec §9.1, steps 4–7). Operations run in order: runs of content operations go to the
+ * adapter, envelope operations and `replace_content` are handled here. Any failure throws and leaves the input
+ * untouched, since everything works on copies.
  */
-export function applyOperations(
+export async function applyOperations(
   registry: ArtifactRegistry,
-  artifact: Pick<Artifact, 'kind' | 'content' | 'title' | 'themeId' | 'locale'>,
+  artifact: Pick<Artifact, 'format' | 'content' | 'title' | 'themeId' | 'locale'>,
   operations: unknown,
-  options: EngineOptions = {},
-): BatchResult {
+  options: { locale?: string } = {},
+): Promise<BatchResult> {
   const locale = options.locale ?? artifact.locale;
-  const kind = registry.get(artifact.kind, locale);
-  const parsedOps = parseOperations(registry, artifact.kind, operations, locale);
+  const adapter = registry.get(artifact.format, locale);
+  const parsed = parseOperations(registry, artifact.format, operations, locale);
 
   const before = artifact.content;
-  let draft: unknown = structuredClone(before);
   const envelope = { title: artifact.title, themeId: artifact.themeId, locale: artifact.locale };
-  const beforeIds = new Set<string>(kind.ids(before));
-  const allocator = new IdAllocator(beforeIds);
+  let draft: unknown = structuredClone(before);
+  const createdRefs: string[] = [];
+  const warnings: LintIssue[] = [];
 
-  parsedOps.forEach((op, index) => {
-    // `hasId` reflects the draft as it is now, so an id removed earlier in the batch can be reused
-    // explicitly; `nextId` still never hands out an id seen in this batch, keeping generated ids stable.
-    const present = new Set<string>(kind.ids(draft));
-    const ctx: ApplyContext = {
-      nextId: (prefix) => {
-        const id = allocator.next(prefix);
-        present.add(id);
-        return id;
-      },
-      hasId: (id) => present.has(id),
-      reserveId: (id) => {
-        allocator.reserve(id);
-        present.add(id);
-      },
-      locale,
-      fail(message, failOptions) {
-        throw new ArtifactError('OPERATION_FAILED', t(locale, 'OPERATION_FAILED', { index }), {
+  let index = 0;
+  while (index < parsed.length) {
+    const item = parsed[index];
+    if (item?.kind === 'envelope') {
+      const envelopeOp = item.op;
+      if (envelopeOp.op === 'replace_content') {
+        checkDepth(envelopeOp.content, `operations[${index}].content`, locale);
+        draft = replaceContent(registry, adapter, sanitizeDeep(envelopeOp.content), locale, index);
+      } else {
+        applyEnvelopeOperation(registry, envelope, envelopeOp, index, locale);
+      }
+      index += 1;
+      continue;
+    }
+    // Consecutive content operations form one run for the adapter.
+    const run: unknown[] = [];
+    while (index < parsed.length && parsed[index]?.kind === 'content') {
+      run.push(parsed[index]?.op);
+      index += 1;
+    }
+    const theme = registry.theme(envelope.themeId, locale);
+    const ctx: AdapterContext = { locale, theme, fail: failIn(locale, index - run.length) };
+    try {
+      const result = await adapter.apply(draft as never, run as never[], ctx);
+      draft = result.content;
+      createdRefs.push(...result.createdRefs);
+      warnings.push(...result.warnings);
+    } catch (error) {
+      if (error instanceof ArtifactError) throw error;
+      throw new ArtifactError(
+        'OPERATION_FAILED',
+        t(locale, 'OPERATION_FAILED', { index: index - run.length }),
+        {
           issues: [
             {
-              path: failOptions?.path ? `operations[${index}].${failOptions.path}` : `operations[${index}]`,
-              message,
-              ...(failOptions?.hint ? { hint: failOptions.hint } : {}),
+              path: `operations[${index - run.length}]`,
+              message: t(locale, 'OPERATION_FAILED', { index: index - run.length }),
             },
           ],
-          details: { index },
-        });
-      },
-    };
-    if (isEnvelopeOperation(op)) {
-      draft = applyEnvelopeOperation(
-        registry,
-        kind,
-        draft,
-        envelope,
-        op as EnvelopeOperation,
-        index,
-        allocator,
-        locale,
+          details: { index: index - run.length },
+          cause: error,
+        },
       );
-      return;
     }
-    try {
-      kind.apply(draft, op, ctx);
-    } catch (error) {
-      if (error instanceof ArtifactError) throw error;
-      throw new ArtifactError('OPERATION_FAILED', t(locale, 'OPERATION_FAILED', { index }), {
-        issues: [{ path: `operations[${index}]`, message: t(locale, 'OPERATION_FAILED', { index }) }],
-        details: { index },
-        cause: error,
-      });
-    }
-  });
+  }
 
-  kind.derive?.(draft);
-  draft = validateContent(registry, kind, draft, locale);
+  const finalTheme = registry.theme(envelope.themeId, locale);
+  const finalCtx: AdapterContext = { locale: envelope.locale, theme: finalTheme, fail: failIn(locale, 0) };
+  draft = validateContent(registry, adapter, draft, finalCtx);
   const envelopeBytes = jsonByteSize({ ...envelope, content: draft });
   if (envelopeBytes > registry.batch.maxEnvelopeBytes) {
     const message = t(locale, 'LIMIT_EXCEEDED', {
@@ -365,13 +326,11 @@ export function applyOperations(
     });
   }
 
-  const afterIds = [...kind.ids(draft)];
-  const theme = registry.theme(envelope.themeId, locale);
   return {
     content: draft,
-    schemaVersion: kind.version,
+    formatVersion: adapter.formatVersion,
     ...envelope,
-    createdIds: afterIds.filter((id) => !beforeIds.has(id)),
+    createdRefs: [...new Set(createdRefs)],
     diff: [
       ...diffFields(
         'envelope',
@@ -380,26 +339,45 @@ export function applyOperations(
         ['title', 'themeId', 'locale'],
         locale,
       ),
-      ...kind.diff(before, draft, locale),
+      ...adapter.diff(before as never, draft as never, locale),
     ],
-    lint: kind.lint(draft, { locale: envelope.locale, theme }),
+    lint: [...warnings, ...adapter.lint(draft as never, { locale: envelope.locale, theme: finalTheme })],
   };
 }
 
+function replaceContent(
+  registry: ArtifactRegistry,
+  adapter: ReturnType<ArtifactRegistry['get']>,
+  content: unknown,
+  locale: string,
+  index: number,
+): unknown {
+  const theme = registry.theme('default', locale);
+  const result = adapter.validate(content, { locale, theme, fail: failIn(locale, index) });
+  if (!result.ok) {
+    throw new ArtifactError('INVALID_OPERATION', t(locale, 'INVALID_OPERATION', { index }), {
+      issues: result.issues.map((issue) => ({
+        ...issue,
+        path: `operations[${index}].content.${issue.path}`,
+      })),
+      details: { index },
+    });
+  }
+  checkLimits(registry, adapter, result.content, locale);
+  return result.content;
+}
+
 function applyEnvelopeOperation(
   registry: ArtifactRegistry,
-  kind: AnyArtifactKind,
-  draft: unknown,
   envelope: { title: string; themeId: string; locale: string },
-  op: EnvelopeOperation,
+  op: Exclude<EnvelopeOperation, { op: 'replace_content' }>,
   index: number,
-  allocator: IdAllocator,
   locale: string,
-): unknown {
+): void {
   switch (op.op) {
     case 'set_title':
       envelope.title = op.title;
-      return draft;
+      return;
     case 'set_theme':
       if (!registry.hasTheme(op.themeId)) {
         throw new ArtifactError('OPERATION_FAILED', t(locale, 'OPERATION_FAILED', { index }), {
@@ -419,62 +397,37 @@ function applyEnvelopeOperation(
         });
       }
       envelope.themeId = op.themeId;
-      return draft;
+      return;
     case 'set_locale':
       envelope.locale = op.locale;
-      return draft;
-    case 'replace_content': {
-      checkDepth(op.content, `operations[${index}].content`, locale);
-      const raw = sanitizeDeep(op.content);
-      for (const id of collectExplicitIds(raw)) allocator.reserve(id);
-      const normalized = kind.normalize
-        ? kind.normalize(structuredClone(raw), idContext(allocator))
-        : structuredClone(raw);
-      const parsed = kind.contentSchema.safeParse(normalized);
-      if (!parsed.success) {
-        throw new ArtifactError('INVALID_OPERATION', t(locale, 'INVALID_OPERATION', { index }), {
-          issues: zodIssuesToErrorIssues(parsed.error.issues, locale, `operations[${index}].content`),
-          details: { index },
-        });
-      }
-      return parsed.data;
-    }
+      return;
   }
 }
 
 /**
- * Targets an operation batch touches, for automatic rebase (spec §8.3). Uses the kind's `targets` when it
- * covers every operation, otherwise the diff produced by applying the batch on its base.
+ * Areas a batch touches, for automatic rebase (spec §9.2). Derived from the diff produced by applying the batch on
+ * its base, plus the envelope fields it sets. `replace_content` touches everything.
  */
-export function batchTargets(
-  kind: AnyArtifactKind,
-  operations: unknown[],
-  baseDiff: ChangeSummary[],
-): Set<string> {
+export function batchTargets(operations: ParsedOperation[], baseDiff: ChangeSummary[]): Set<string> {
   const targets = new Set<string>();
-  const kindOps = operations.filter((op) => !isEnvelopeOperation(op));
-  for (const op of operations) {
-    if (!isEnvelopeOperation(op)) continue;
-    const name = (op as EnvelopeOperation).op;
-    if (name === 'replace_content') targets.add('*');
-    else
-      targets.add(`envelope:${name === 'set_title' ? 'title' : name === 'set_theme' ? 'themeId' : 'locale'}`);
-  }
-  if (kind.targets && kindOps.length > 0) {
-    for (const op of kindOps) for (const target of kind.targets(op)) targets.add(target);
-  } else {
-    for (const change of baseDiff) targets.add(change.target);
+  for (const item of operations) {
+    if (item.kind === 'envelope') {
+      const op = item.op;
+      if (op.op === 'replace_content') targets.add('*');
+      else
+        targets.add(
+          `envelope:${op.op === 'set_title' ? 'title' : op.op === 'set_theme' ? 'themeId' : 'locale'}`,
+        );
+    }
   }
+  for (const change of baseDiff) targets.add(change.target);
   return targets;
 }
 
 /** True when two target sets overlap. `*` overlaps everything. */
 export function targetsOverlap(a: Set<string>, b: Set<string>): boolean {
   if ((a.has('*') && b.size > 0) || (b.has('*') && a.size > 0)) return true;
-  for (const target of a) {
-    if (b.has(target)) return true;
-    // A target nested in another (`cell:Resumo!A1` vs `sheet:Resumo`) is handled by kinds emitting both.
-  }
+  for (const target of a) if (b.has(target)) return true;
   return false;
 }
 

package/src/envelope.ts

@@ -1,10 +1,6 @@
 import { z } from 'zod';
 import { artifactIdSchema } from './ids.js';
 
-export const ARTIFACT_STATUSES = ['draft', 'pending_approval', 'published', 'archived'] as const;
-export type ArtifactStatus = (typeof ARTIFACT_STATUSES)[number];
-export const artifactStatusSchema = z.enum(ARTIFACT_STATUSES);
-
 export const actorSchema = z.object({
   type: z.enum(['agent', 'user', 'system']),
   id: z.string().min(1).max(128),
@@ -25,19 +21,20 @@ export const metaSchema = z.object({
   createdBy: actorSchema,
   updatedBy: actorSchema,
   tags: z.array(z.string().max(64)).max(32).default([]),
-  /** Last approved version, kept as the reference while a newer draft waits for approval (spec §15.3). */
-  publishedVersion: z.number().int().min(1).optional(),
 });
 export type ArtifactMeta = z.infer<typeof metaSchema>;
 
-/** Envelope (spec §6.1). Only `content` is produced by the model; everything else is system-owned. */
+/**
+ * Envelope. Only `content` is produced by the model; everything else is system-owned. The library keeps the current
+ * content and a `version` counter for optimistic concurrency. It keeps no history: saving and versioning belong to the
+ * harness, which receives the save action from the editor (see `onSave` in `@artkit-ai/react`).
+ */
 export const envelopeSchema = z.object({
   id: artifactIdSchema,
-  kind: z.string().min(1).max(64),
-  schemaVersion: z.number().int().min(1),
+  format: z.string().min(1).max(64),
+  formatVersion: z.string().min(1).max(64),
   version: z.number().int().min(1),
   title: titleSchema,
-  status: artifactStatusSchema,
   locale: localeSchema,
   themeId: z.string().min(1).max(64),
   content: z.unknown(),
@@ -46,11 +43,10 @@ export const envelopeSchema = z.object({
 
 export interface Artifact<Content = unknown> {
   id: string;
-  kind: string;
-  schemaVersion: number;
+  format: string;
+  formatVersion: string;
   version: number;
   title: string;
-  status: ArtifactStatus;
   locale: string;
   themeId: string;
   content: Content;
@@ -60,10 +56,9 @@ export interface Artifact<Content = unknown> {
 /** Lightweight reference carried in chat messages and lists (no content). */
 export interface ArtifactSummary {
   id: string;
-  kind: string;
+  format: string;
   title: string;
   version: number;
-  status: ArtifactStatus;
   locale: string;
   updatedAt: string;
 }
@@ -71,23 +66,10 @@ export interface ArtifactSummary {
 export function summarize(artifact: Artifact): ArtifactSummary {
   return {
     id: artifact.id,
-    kind: artifact.kind,
+    format: artifact.format,
     title: artifact.title,
     version: artifact.version,
-    status: artifact.status,
     locale: artifact.locale,
     updatedAt: artifact.meta.updatedAt,
   };
 }
-
-/** Allowed lifecycle transitions (spec §15.3). */
-export const STATUS_TRANSITIONS: Record<ArtifactStatus, readonly ArtifactStatus[]> = {
-  draft: ['pending_approval', 'published', 'archived'],
-  pending_approval: ['published', 'draft', 'archived'],
-  published: ['archived', 'draft'],
-  archived: ['draft'],
-};
-
-export function canTransition(from: ArtifactStatus, to: ArtifactStatus): boolean {
-  return STATUS_TRANSITIONS[from].includes(to);
-}