@sentropic/artifacts 0.2.5 → 0.2.6

package/dist/profile/contracts.d.ts

@@ -1,7 +1,7 @@
 import type { JsonValue } from '../contracts.js';
 import type { EffectiveArtifactCommand } from '../server/command-identity.js';
 export declare const PROFILE_CONTRACT_VERSION: "artifacts-profile/v1";
-export declare const ARTIFACT_CAPABILITY_NAMES: readonly ["artifacts_get_template", "artifacts_get_api_guide", "artifacts_ensure", "artifacts_publish", "artifacts_create_upload", "artifacts_commit_upload", "artifacts_list", "artifacts_get", "artifacts_get_source", "artifacts_fork", "artifacts_set_access", "artifacts_promote", "artifacts_renew", "artifacts_delete", "artifacts_restore"];
+export declare const ARTIFACT_CAPABILITY_NAMES: readonly ["artifacts_get_template", "artifacts_get_api_guide", "artifacts_ensure", "artifacts_publish", "artifacts_create_upload", "artifacts_commit_upload", "artifacts_list", "artifacts_get", "artifacts_get_source", "artifacts_fork", "artifacts_set_access", "artifacts_promote", "artifacts_renew", "artifacts_delete", "artifacts_restore", "artifacts_list_versions", "artifacts_revert"];
 export type ArtifactCapabilityName = (typeof ARTIFACT_CAPABILITY_NAMES)[number];
 export type ArtifactSchema = Readonly<Record<string, unknown>>;
 export interface OperationProfile {
@@ -22,6 +22,12 @@ export interface ArtifactProfileRules {
     readonly mimeTypes: readonly string[];
 }
 export interface ArtifactProviderProfile {
+    /** Trusted public contract revision; independent from the host policy revision. */
+    readonly profileRevisionId?: string;
+    /** Explicit projection switchover; omitted profiles retain the v1 wire shape. */
+    readonly resultEnvelopeVersion?: 1 | 2;
+    /** Require caller-supplied CAS preconditions on every publication writer. */
+    readonly requireExpectedCurrentReleaseId?: boolean;
     readonly version: typeof PROFILE_CONTRACT_VERSION;
     readonly selectedCapabilities: readonly string[];
     readonly operations: readonly OperationProfile[];
@@ -42,7 +48,9 @@ export interface CompiledArtifactsProfile extends EffectiveArtifactProfile {
         readonly required: true;
         readonly scope: 'principal';
     }>>>;
-    validate(name: string, args: unknown, envelopeKey?: string): Readonly<Record<string, JsonValue>>;
+    validate(name: string, args: unknown, envelopeKey?: string, options?: {
+        deferPrecondition: true;
+    }): Readonly<Record<string, JsonValue>>;
     assertSelected(name: string): asserts name is ArtifactCapabilityName;
     capabilityForRoute(method: string, path: string): ArtifactCapabilityName | undefined;
 }
@@ -53,15 +61,17 @@ export interface CompiledValidators {
     readonly normalizeCommand: (command: unknown) => EffectiveArtifactCommand;
 }
 /** Projection fields are data-only; invocation correlation is added by L6. */
+export declare const PRECONDITION_REQUIRED_MESSAGE = "expectedCurrentReleaseId is required by the active artifact profile. Re-read this artifact with artifacts_get or artifacts_list, then send expectedCurrentReleaseId using the currentReleaseId returned by that read. Send null only if the read confirms that there is no current release. Before editing an existing release, read it with artifacts_get_source and use that releaseId. The server will not infer this value.";
 export declare class ArtifactProfileInputError extends Error {
+    readonly details?: Record<string, unknown> | undefined;
     readonly kind: 'operational' | 'ordinary';
     readonly status: number;
     readonly httpStatus: number;
-    readonly variant: 'unselected_operation' | 'invalid_request';
+    readonly variant: 'unselected_operation' | 'invalid_request' | 'precondition_required';
     readonly publicCode: string;
-    readonly category: 'invalid_request' | 'capability_unselected';
+    readonly category: 'invalid_request' | 'capability_unselected' | 'precondition_required';
     readonly retriable = false;
     readonly phase: 'selection' | 'entry';
     readonly commitState = "not_committed";
-    constructor(unselected?: boolean);
+    constructor(unselected?: boolean, preconditionRequired?: boolean, details?: Record<string, unknown> | undefined);
 }

package/dist/profile/contracts.js

@@ -4,10 +4,12 @@ export const ARTIFACT_CAPABILITY_NAMES = [
     'artifacts_publish', 'artifacts_create_upload', 'artifacts_commit_upload',
     'artifacts_list', 'artifacts_get', 'artifacts_get_source', 'artifacts_fork',
     'artifacts_set_access', 'artifacts_promote', 'artifacts_renew',
-    'artifacts_delete', 'artifacts_restore',
+    'artifacts_delete', 'artifacts_restore', 'artifacts_list_versions', 'artifacts_revert',
 ];
 /** Projection fields are data-only; invocation correlation is added by L6. */
+export const PRECONDITION_REQUIRED_MESSAGE = 'expectedCurrentReleaseId is required by the active artifact profile. Re-read this artifact with artifacts_get or artifacts_list, then send expectedCurrentReleaseId using the currentReleaseId returned by that read. Send null only if the read confirms that there is no current release. Before editing an existing release, read it with artifacts_get_source and use that releaseId. The server will not infer this value.';
 export class ArtifactProfileInputError extends Error {
+    details;
     kind;
     status;
     httpStatus;
@@ -17,15 +19,16 @@ export class ArtifactProfileInputError extends Error {
     retriable = false;
     phase;
     commitState = 'not_committed';
-    constructor(unselected = false) {
-        super(unselected ? 'capability_unavailable' : 'invalid_request');
+    constructor(unselected = false, preconditionRequired = false, details) {
+        super(unselected ? 'capability_unavailable' : preconditionRequired ? 'precondition_required' : 'invalid_request');
+        this.details = details;
         this.name = 'ArtifactProfileInputError';
         this.kind = unselected ? 'operational' : 'ordinary';
-        this.status = unselected ? 503 : 400;
+        this.status = unselected ? 503 : preconditionRequired ? 428 : 400;
         this.httpStatus = this.status;
-        this.variant = unselected ? 'unselected_operation' : 'invalid_request';
+        this.variant = unselected ? 'unselected_operation' : preconditionRequired ? 'precondition_required' : 'invalid_request';
         this.publicCode = this.message;
-        this.category = unselected ? 'capability_unselected' : 'invalid_request';
+        this.category = unselected ? 'capability_unselected' : preconditionRequired ? 'precondition_required' : 'invalid_request';
         this.phase = unselected ? 'selection' : 'entry';
     }
 }

package/dist/profile/index.js

@@ -18,11 +18,29 @@ export function compileArtifactsProfile(input) {
     const snapshot = copyJson(input);
     const profile = { ...snapshot,
         rules: snapshot.rules === undefined ? copyJson(RADAR_ARTIFACTS_PROFILE.rules) : snapshot.rules };
-    const allowed = ['version', 'selectedCapabilities', 'operations', 'contractRevisions', 'rules'];
+    const allowed = ['version', 'selectedCapabilities', 'operations', 'contractRevisions', 'rules',
+        'requireExpectedCurrentReleaseId', 'profileRevisionId', 'resultEnvelopeVersion'];
     if (Object.keys(profile).some((key) => !allowed.includes(key)) || profile.version !== PROFILE_CONTRACT_VERSION ||
         !Array.isArray(profile.selectedCapabilities) || !Array.isArray(profile.operations))
         throw new Error('invalid artifacts profile');
     const requested = profile.selectedCapabilities;
+    if (profile.profileRevisionId && profile.resultEnvelopeVersion !== 2 && requested.some(name => ['artifacts_list_versions', 'artifacts_revert'].includes(name)))
+        throw new Error('part 1 requires the v2 profile');
+    if ((profile.profileRevisionId !== undefined && (typeof profile.profileRevisionId !== 'string' ||
+        !profile.profileRevisionId.trim() || profile.profileRevisionId.length > 160 || profile.resultEnvelopeVersion === undefined)) ||
+        (profile.resultEnvelopeVersion !== undefined && (!profile.profileRevisionId ||
+            ![1, 2].includes(profile.resultEnvelopeVersion))) ||
+        (profile.resultEnvelopeVersion === 2 && (profile.requireExpectedCurrentReleaseId !== true ||
+            profile.contractRevisions?.outcome !== 'artifacts-outcome/v2'))) {
+        throw new Error('inconsistent artifact profile descriptor');
+    }
+    if (profile.requireExpectedCurrentReleaseId !== undefined && typeof profile.requireExpectedCurrentReleaseId !== 'boolean') {
+        throw new Error('invalid publication precondition policy');
+    }
+    if (profile.requireExpectedCurrentReleaseId && requested.some(name => [
+        'artifacts_promote', 'artifacts_restore', 'artifacts_create_upload', 'artifacts_commit_upload', 'artifacts_fork',
+    ].includes(name)))
+        throw new Error('strict profile contains a writer without CAS');
     if (new Set(requested).size !== requested.length ||
         requested.some((name) => !ARTIFACT_CAPABILITY_NAMES.includes(name))) {
         throw new Error('unknown or duplicate artifacts capability');
@@ -73,13 +91,16 @@ export function compileArtifactsProfile(input) {
             throw new Error('profile/derivation key length mismatch');
         }
         const defaults = op.defaults;
+        if (profile.requireExpectedCurrentReleaseId && Object.hasOwn(defaults, 'expectedCurrentReleaseId')) {
+            throw new Error('publication preconditions cannot be defaulted');
+        }
         const schema = schemas[name];
         const props = schema.properties;
         for (const [key, value] of Object.entries(defaults)) {
             if (!Object.hasOwn(props, key) || !matchesSchema(value, props[key]))
                 throw new Error('profile/schema default mismatch');
         }
-        if (['artifacts_ensure', 'artifacts_publish', 'artifacts_commit_upload', 'artifacts_set_access', 'artifacts_delete'].includes(name)) {
+        if (['artifacts_ensure', 'artifacts_publish', 'artifacts_commit_upload', 'artifacts_set_access', 'artifacts_delete', 'artifacts_revert'].includes(name)) {
             idempotency[name] = { required: true, scope: 'principal' };
         }
     }
@@ -93,10 +114,10 @@ export function compileArtifactsProfile(input) {
         profileDigest: orderedDigest({ selection: selectedCapabilities, profile, schemas,
             providerContractRevisions: profile.contractRevisions }),
         assertSelected,
-        validate(name, args, envelopeKey) {
+        validate(name, args, envelopeKey, options) {
             if (!selectedCapabilities.includes(name))
                 throw new ArtifactProfileInputError(true);
-            return normalizeArguments(profile, name, args, schemas[name], envelopeKey);
+            return normalizeArguments(profile, name, args, schemas[name], envelopeKey, options);
         },
         capabilityForRoute(method, path) {
             let name;
@@ -112,8 +133,16 @@ export function compileArtifactsProfile(input) {
                 name = 'artifacts_set_access';
             if (method === 'POST' && path === '/delete')
                 name = 'artifacts_delete';
+            if (method === 'POST' && path === '/revert')
+                name = 'artifacts_revert';
+            if (method === 'POST' && path === '/list_versions')
+                name = 'artifacts_list_versions';
             if (method === 'GET' && path.startsWith('/meta/') && isArtifactId(path.slice(6)))
                 name = 'artifacts_get';
+            if (method === 'GET' && path.startsWith('/versions/') && isArtifactId(path.slice(10)))
+                name = 'artifacts_list_versions';
+            if (method === 'GET' && path.startsWith('/source/') && isArtifactId(path.slice(8)))
+                name = 'artifacts_get_source';
             return name && selectedCapabilities.includes(name) ? name : undefined;
         },
     };

package/dist/profile/radar.js

@@ -10,6 +10,9 @@ export const RADAR_ARTIFACTS_PROFILE = freezeDeep({
                 maxDecodedFileBytes: 262144, maxDecodedTotalBytes: 262144 }, defaults: { profile: {} } },
         { operation: 'list', limits: { listLimitMin: 1, listLimitMax: 100 }, defaults: { limit: 20, offset: 0 } },
         { operation: 'get', limits: {}, defaults: {} },
+        { operation: 'list_versions', limits: {}, defaults: {} },
+        { operation: 'get_source', limits: {}, defaults: {} },
+        { operation: 'revert', limits: { idempotencyKeyMaxUnits: 256 }, defaults: {} },
     ],
     rules: { lengthUnit: 'utf16', textEncoding: 'utf8', callerKeyNormalization: 'none',
         rejectLoneSurrogates: true, provenance: 'inline-original', keyDerivationAlgorithm: 'radar-derive-idempotency-v1', pathMaxBytes: 1024,
@@ -17,5 +20,5 @@ export const RADAR_ARTIFACTS_PROFILE = freezeDeep({
         reservedFirstSegments: ['api', '__artifacts', 'livez', 'health'],
         mimeTypes: ['text/html', 'text/css', 'text/javascript', 'application/json'] },
     contractRevisions: { profile: 'artifacts-profile/v1', command: 'artifacts-command/v1',
-        authorization: 'artifacts-authorization/v1', outcome: 'artifacts-outcome/v1' },
+        authorization: 'artifacts-authorization/v1', outcome: 'artifacts-outcome/v2' },
 });

package/dist/profile/schemas.js

@@ -5,6 +5,13 @@ const obj = (properties, required = []) => ({ type: 'object', properties, requir
 const id = { type: 'string', pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' };
 const primitiveRecord = { type: 'object',
     additionalProperties: { type: ['string', 'number', 'boolean', 'null'] }, default: {} };
+/** Artifact display metadata: one short word for the icon. */
+const metadata = {
+    title: { type: 'string', minLength: 1, maxLength: 160, description: 'Artifact display title.' },
+    description: { type: 'string', maxLength: 2000, description: 'Short artifact description.' },
+    icon: { type: ['string', 'null'], pattern: '^[a-z][a-z0-9-]{0,31}$',
+        description: 'One short lowercase word.' },
+};
 /** Required configuration includes semantic limits absent from JSON Schema. */
 export function assertCompleteOperation(config) {
     const required = {
@@ -16,6 +23,7 @@ export function assertCompleteOperation(config) {
         commit_upload: { limits: ['idempotencyKeyMaxUnits'], defaults: ['profile'] },
         set_access: { limits: ['idempotencyKeyMaxUnits'], defaults: [] },
         delete: { limits: ['idempotencyKeyMaxUnits'], defaults: [] },
+        revert: { limits: ['idempotencyKeyMaxUnits'], defaults: [] },
     };
     const fields = required[config.operation];
     if (fields && (fields.limits.some((key) => !Object.hasOwn(config.limits, key)) ||
@@ -32,6 +40,7 @@ export function operationProfile(profile, operation) {
 /** Schemas are generated from the same limits/defaults read by normalization. */
 export function capabilitySchema(name, profile) {
     const operation = name.slice('artifacts_'.length);
+    const part1 = profile.profileRevisionId === undefined || profile.resultEnvelopeVersion === 2;
     const config = operationProfile(profile, operation);
     const limits = config.limits;
     const key = { type: 'string', minLength: 1, maxLength: limits.idempotencyKeyMaxUnits,
@@ -40,7 +49,7 @@ export function capabilitySchema(name, profile) {
     switch (operation) {
         case 'ensure': return obj({ bindingName: { type: 'string', minLength: limits.bindingNameMinUnits,
                 maxLength: limits.bindingNameMaxUnits }, parameters: { ...obj({}), default: config.defaults.parameters },
-            idempotencyKey: key }, ['bindingName', 'idempotencyKey']);
+            idempotencyKey: key, ...(part1 ? metadata : {}) }, ['bindingName', 'idempotencyKey']);
         case 'publish': {
             const reserved = profile.rules.reservedFirstSegments.map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|');
             const path = { type: 'string', minLength: 1, maxLength: profile.rules.pathMaxBytes,
@@ -53,9 +62,20 @@ export function capabilitySchema(name, profile) {
                     bytes: { type: 'array', maxItems: limits.maxDecodedFileBytes, items: integer(0, 255) } }, ['path', 'mimeType']),
                 oneOf: [{ required: ['text'], not: { required: ['bytes'] } },
                     { required: ['bytes'], not: { required: ['text'] } }] };
-            return obj({ artifactId: id, idempotencyKey: key, files: { type: 'array', items: file,
-                    minItems: limits.publishFilesMin, maxItems: limits.publishFilesMax },
-                profile: { ...primitiveRecord, default: config.defaults.profile } }, ['artifactId', 'files', 'idempotencyKey']);
+            const edit = obj({ path, oldStr: { type: 'string', minLength: 1, maxLength: limits.maxDecodedFileBytes,
+                    description: 'Must occur exactly once in the current file text.' },
+                newStr: { type: 'string', maxLength: limits.maxDecodedFileBytes } }, ['path', 'oldStr', 'newStr']);
+            return { ...obj({ artifactId: id, idempotencyKey: key,
+                    files: { type: 'array', items: file, minItems: limits.publishFilesMin, maxItems: limits.publishFilesMax,
+                        description: 'Full file set; required unless edits is supplied.' },
+                    ...(part1 ? { edits: { type: 'array', items: edit, minItems: 1, maxItems: 100,
+                            description: 'Small old/new edits applied to the current release text files; required unless files is supplied.' } } : {}),
+                    expectedCurrentReleaseId: { ...id, type: ['string', 'null'], description: 'Compare the current release atomically; null requires an unpublished artifact.' },
+                    profile: { ...primitiveRecord, default: config.defaults.profile },
+                    ...(part1 ? metadata : {}) }, ['artifactId', 'idempotencyKey', ...(!part1 ? ['files'] : []),
+                    ...(profile.requireExpectedCurrentReleaseId ? ['expectedCurrentReleaseId'] : [])]),
+                oneOf: [{ required: ['files'], not: { required: ['edits'] } },
+                    { required: ['edits'], not: { required: ['files'] } }] };
         }
         case 'list': return obj({ limit: { ...integer(limits.listLimitMin, limits.listLimitMax), default: config.defaults.limit },
             offset: { ...integer(0), default: config.defaults.offset } });
@@ -63,10 +83,16 @@ export function capabilitySchema(name, profile) {
         case 'fork':
         case 'renew':
         case 'restore': return idOnly;
+        case 'list_versions': return profile.resultEnvelopeVersion !== 2 ? idOnly : obj({ artifactId: id,
+            limit: { ...integer(1, 100), default: 20 }, cursor: { ...str, maxLength: 4096 } }, ['artifactId']);
         case 'get_source': return obj({ artifactId: id, releaseId: id,
             paths: { type: 'array', minItems: 1, maxItems: 32, items: { ...str, maxLength: profile.rules.pathMaxBytes } } }, ['artifactId']);
         case 'delete': return obj({ artifactId: id, expectedCurrentReleaseId: { ...id, type: ['string', 'null'] },
-            idempotencyKey: key, confirmationRef: { ...str, maxLength: 4096 } }, ['artifactId', 'expectedCurrentReleaseId', 'idempotencyKey']);
+            idempotencyKey: key, confirmationRef: { ...str, maxLength: 4096 } }, ['artifactId', 'idempotencyKey', ...(profile.requireExpectedCurrentReleaseId ? ['expectedCurrentReleaseId'] : [])]);
+        case 'revert': {
+            const target = profile.resultEnvelopeVersion === 2 ? 'targetReleaseId' : 'releaseId';
+            return obj({ artifactId: id, [target]: id, expectedCurrentReleaseId: { ...id, type: ['string', 'null'] }, idempotencyKey: key }, ['artifactId', target, 'idempotencyKey', ...(profile.requireExpectedCurrentReleaseId ? ['expectedCurrentReleaseId'] : [])]);
+        }
         case 'get_template': return obj({ templateId: str }, ['templateId']);
         case 'get_api_guide': return obj({ version: str });
         case 'create_upload': return obj({ artifactId: id, mimeType: str, maxSize: integer(1) }, ['artifactId', 'mimeType']);

package/dist/profile/validation.d.ts

@@ -2,4 +2,6 @@ import { type JsonValue } from '../contracts.js';
 import { type EffectiveArtifactProfile, type ArtifactSchema } from './contracts.js';
 /** The generated schema vocabulary, evaluated without a platform dependency. */
 export declare function matchesSchema(value: unknown, schema: ArtifactSchema): boolean;
-export declare function normalizeArguments(profile: EffectiveArtifactProfile, name: string, input: unknown, schema: ArtifactSchema, envelopeKey?: string): Readonly<Record<string, JsonValue>>;
+export declare function normalizeArguments(profile: EffectiveArtifactProfile, name: string, input: unknown, schema: ArtifactSchema, envelopeKey?: string, options?: {
+    deferPrecondition: true;
+}): Readonly<Record<string, JsonValue>>;

package/dist/profile/validation.js

@@ -72,13 +72,22 @@ export function matchesSchema(value, schema) {
     }
     return true;
 }
-export function normalizeArguments(profile, name, input, schema, envelopeKey) {
+export function normalizeArguments(profile, name, input, schema, envelopeKey, options) {
     const args = copyJson(input);
+    if (profile.requireExpectedCurrentReleaseId && ['artifacts_publish', 'artifacts_revert', 'artifacts_delete'].includes(name) &&
+        isRecord(args) && !Object.hasOwn(args, 'expectedCurrentReleaseId')) {
+        if (!options?.deferPrecondition)
+            throw new ArtifactProfileInputError(false, true, {
+                profileRevisionId: profile.profileRevisionId ?? profile.version, resultEnvelopeVersion: profile.resultEnvelopeVersion ?? 1,
+                requiredField: 'expectedCurrentReleaseId', readTools: ['artifacts_get', 'artifacts_list'],
+            });
+        schema = { ...schema, required: schema.required.filter(key => key !== 'expectedCurrentReleaseId') };
+    }
     requireInput(isRecord(args) && matchesSchema(args, schema));
     const operation = name.slice('artifacts_'.length);
     const { defaults, limits } = operationProfile(profile, operation);
     const normalized = { ...copyJson(defaults), ...args };
-    if (['ensure', 'publish', 'commit_upload', 'set_access', 'delete'].includes(operation)) {
+    if (['ensure', 'publish', 'commit_upload', 'set_access', 'delete', 'revert'].includes(operation)) {
         const key = args.idempotencyKey;
         requireInput(typeof key === 'string' && key.trim().length > 0 && key.length <= limits.idempotencyKeyMaxUnits);
         requireInput(envelopeKey === undefined || envelopeKey === key);
@@ -91,18 +100,28 @@ export function normalizeArguments(profile, name, input, schema, envelopeKey) {
         const paths = args.paths;
         requireInput(new Set(paths).size === paths.length && paths.every((path) => Buffer.byteLength(path, 'utf8') <= profile.rules.pathMaxBytes));
     }
+    if (Object.hasOwn(args, 'releaseId'))
+        requireInput(isArtifactId(args.releaseId));
+    if (Object.hasOwn(args, 'expectedCurrentReleaseId'))
+        requireInput(args.expectedCurrentReleaseId === null || isArtifactId(args.expectedCurrentReleaseId));
     if (operation === 'publish') {
-        const paths = new Set();
-        let total = 0;
-        normalized.files = args.files.map((file) => {
-            const path = file.path;
-            requireInput(!paths.has(path) && Buffer.byteLength(path, 'utf8') <= profile.rules.pathMaxBytes);
-            paths.add(path);
-            const bytes = Object.hasOwn(file, 'text') ? Array.from(Buffer.from(file.text, 'utf8')) : file.bytes;
-            total += bytes.length;
-            requireInput(bytes.length <= limits.maxDecodedFileBytes && total <= limits.maxDecodedTotalBytes);
-            return { path, mimeType: file.mimeType, bytes };
-        });
+        const hasFiles = Object.hasOwn(args, 'files');
+        const hasEdits = Object.hasOwn(args, 'edits');
+        // Exactly one content source: a full file set, or small edits on the current release.
+        requireInput(hasFiles !== hasEdits);
+        if (hasFiles) {
+            const paths = new Set();
+            let total = 0;
+            normalized.files = args.files.map((file) => {
+                const path = file.path;
+                requireInput(!paths.has(path) && Buffer.byteLength(path, 'utf8') <= profile.rules.pathMaxBytes);
+                paths.add(path);
+                const bytes = Object.hasOwn(file, 'text') ? Array.from(Buffer.from(file.text, 'utf8')) : file.bytes;
+                total += bytes.length;
+                requireInput(bytes.length <= limits.maxDecodedFileBytes && total <= limits.maxDecodedTotalBytes);
+                return { path, mimeType: file.mimeType, bytes };
+            });
+        }
     }
     return freezeDeep(normalized);
 }

package/dist/server/access.d.ts

@@ -15,6 +15,12 @@ export interface GrantRecord {
     principalId: string;
     grant: AccessGrant;
 }
+/** Display metadata of one artifact (title/description/icon); cosmetic, owner-set. */
+export interface ArtifactMetadata {
+    title?: string;
+    description?: string;
+    icon?: string | null;
+}
 export interface ArtifactAcl {
     bindingName?: string;
     createdAt?: string;
@@ -28,6 +34,8 @@ export interface ArtifactAcl {
     isPublic: boolean;
     withdrawn: boolean;
     grants: GrantRecord[];
+    /** Display metadata returned by get/list; persisted by the host store. */
+    metadata?: ArtifactMetadata;
 }
 export interface AclStore {
     getArtifactAcl(artifactId: string): Promise<ArtifactAcl | undefined>;

package/dist/server/command-identity.d.ts

@@ -8,7 +8,7 @@ export type CallerIdempotencyKey = string & {
 export type InternalIdempotencyKey = string & {
     readonly __brand: 'internal-key';
 };
-export type ArtifactCommandOperation = 'ensure' | 'publish' | 'set_access' | 'delete';
+export type ArtifactCommandOperation = 'ensure' | 'publish' | 'set_access' | 'delete' | 'revert';
 export interface CommandIdentity {
     readonly internalKey: InternalIdempotencyKey;
     readonly commandHash: string;
@@ -50,4 +50,6 @@ export declare function createRadarKeyDerivation(config: {
 }): ArtifactKeyDerivationBinding;
 export declare const commandDigest: typeof orderedDigest;
 /** No caller hash, actor, scope, transport or audit identifier enters this API through arguments. */
-export declare function createArtifactCommand(profile: CompiledArtifactsProfile, name: string, args: unknown, authority: ArtifactCommandAuthority, derivation: ArtifactKeyDerivationBinding, envelopeKey?: string): EffectiveArtifactCommand;
+export declare function createArtifactCommand(profile: CompiledArtifactsProfile, name: string, args: unknown, authority: ArtifactCommandAuthority, derivation: ArtifactKeyDerivationBinding, envelopeKey?: string, options?: {
+    deferPrecondition: true;
+}): EffectiveArtifactCommand;

package/dist/server/command-identity.js

@@ -20,7 +20,7 @@ export function createRadarKeyDerivation(config) {
             if (other === actor || !other.startsWith(`${actor}|`))
                 continue;
             const [operation, objectId] = other.slice(actor.length + 1).split('|');
-            if ((operation === 'ensure' && objectId === '') || (['publish', 'set_access', 'delete'].includes(operation) && isArtifactId(objectId))) {
+            if ((operation === 'ensure' && objectId === '') || (['publish', 'set_access', 'delete', 'revert'].includes(operation) && isArtifactId(objectId))) {
                 throw new Error('ambiguous Radar actor domain');
             }
         }
@@ -30,7 +30,7 @@ export function createRadarKeyDerivation(config) {
         derive(input) {
             const { storageScopeId, actorId, operation, objectId, callerKey } = input;
             if (storageScopeId !== scope || !actors.has(actorId) ||
-                !['ensure', 'publish', 'set_access', 'delete'].includes(operation) ||
+                !['ensure', 'publish', 'set_access', 'delete', 'revert'].includes(operation) ||
                 (operation === 'ensure' ? objectId !== '' : !isArtifactId(objectId)))
                 throw new ArtifactProfileInputError();
             assertWellFormed(callerKey);
@@ -43,12 +43,12 @@ export function createRadarKeyDerivation(config) {
 }
 export const commandDigest = orderedDigest;
 /** No caller hash, actor, scope, transport or audit identifier enters this API through arguments. */
-export function createArtifactCommand(profile, name, args, authority, derivation, envelopeKey) {
+export function createArtifactCommand(profile, name, args, authority, derivation, envelopeKey, options) {
     assertCompiledArtifactsProfile(profile);
     if (derivation.algorithm !== profile.profile.rules.keyDerivationAlgorithm)
         throw new Error('profile/derivation mismatch');
-    const normalized = profile.validate(name, args, envelopeKey);
-    if (!['artifacts_ensure', 'artifacts_publish', 'artifacts_set_access', 'artifacts_delete'].includes(name))
+    const normalized = profile.validate(name, args, envelopeKey, options);
+    if (!['artifacts_ensure', 'artifacts_publish', 'artifacts_set_access', 'artifacts_delete', 'artifacts_revert'].includes(name))
         throw new ArtifactProfileInputError(true);
     const operation = name.slice('artifacts_'.length);
     const { idempotencyKey, confirmationRef: _proof, ...payload } = normalized;

package/dist/server/commit/coordinator.js

@@ -407,7 +407,7 @@ export function createArtifactCommitCoordinator(options) {
                     ok: false,
                     failure: failure('conflict', request, phase, 'not_committed', {
                         key: request.internalKey,
-                    }, { variant: 'key_contention' }),
+                    }, { variant: 'command_conflict' }),
                 };
             }
             return coordinator.replayPrepared(request);
@@ -514,7 +514,7 @@ export function createArtifactCommitCoordinator(options) {
                         ok: false,
                         failure: failure('conflict', request, 'lock', 'not_committed', {
                             key: request.internalKey,
-                        }, { variant: 'key_contention' }),
+                        }, { variant: 'command_conflict' }),
                     };
                 }
                 phase = 'guard';
@@ -583,6 +583,7 @@ export function createArtifactCommitCoordinator(options) {
                 if (recheckRevision !== request.policyRevision) {
                     return abortWith(request, phase, settle, revokedOutcome(request));
                 }
+                request.assertPrecondition?.();
                 phase = 'commit';
                 const commitFailure = await commitUnit(request, active, settle);
                 if (commitFailure !== undefined)
@@ -618,6 +619,12 @@ export function createArtifactCommitCoordinator(options) {
             }
         },
         async replayPrepared(request) {
+            return await coordinator.findReplayPrepared(request) ?? { ok: false,
+                failure: failure('provider_error', request, 'lock', 'not_committed', {
+                    lost: 'replay without a success row',
+                }, { variant: 'unclassified' }) };
+        },
+        async findReplayPrepared(request) {
             validateRequest(request, 'replay');
             await observeAt('before_connection_acquire', request.invocationId);
             let phase = 'acquire';
@@ -646,12 +653,8 @@ export function createArtifactCommitCoordinator(options) {
                 // the barrier denies on the looked-up row instead of vanishing it.
                 await observeAt('after_replay_lookup_before_guard', request.invocationId);
                 if (existing === undefined) {
-                    return abortWith(request, phase, settle, {
-                        ok: false,
-                        failure: failure('provider_error', request, phase, 'not_committed', {
-                            lost: 'replay without a success row',
-                        }, { variant: 'unclassified' }),
-                    });
+                    const error = await settle.abort();
+                    return error === undefined ? undefined : unknownOutcome(request, phase, error);
                 }
                 if (existing.codecVersion !== COMMAND_CODEC_VERSION) {
                     const settleError = await settle.abort();
@@ -667,7 +670,7 @@ export function createArtifactCommitCoordinator(options) {
                         ok: false,
                         failure: failure('conflict', request, phase, 'not_committed', {
                             key: request.internalKey,
-                        }, { variant: 'key_contention' }),
+                        }, { variant: 'command_conflict' }),
                     });
                 }
                 phase = 'guard';

package/dist/server/commit/types.d.ts

@@ -242,6 +242,8 @@ export interface FinalizeRequest {
     readonly locks?: Partial<Record<ParticipantLockClass, CommitLockFn[]>>;
     /** Provisional writes before the guard decision. */
     readonly provisional?: (client: FinalizeTxClient) => Promise<void>;
+    /** Domain CAS, evaluated under retained locks after current authorization. Never runs on replay. */
+    readonly assertPrecondition?: () => void;
     /** Intent completion inside the unit, after the success insert. */
     readonly finishIntents?: (client: FinalizeTxClient) => Promise<void>;
     /** Preparation-abandonment hook, invoked on loser/denial paths. */
@@ -372,6 +374,8 @@ export interface ArtifactCommitCoordinator {
     /** Provider-internal prepared units; domain effects remain inside the same transaction. */
     finalizePrepared(request: FinalizeRequest): Promise<FinalizeResult>;
     replayPrepared(request: FinalizeRequest): Promise<FinalizeResult>;
+    /** Guard an existing receipt before preparing content; absence has no side effects. */
+    findReplayPrepared(request: FinalizeRequest): Promise<FinalizeResult | undefined>;
 }
 /** Unknown legacy codec on a found success row: L6 projects the migration condition. */
 export declare class CommitQuarantineError extends Error {

package/dist/server/edits.d.ts

@@ -0,0 +1,17 @@
+export interface EditableFile {
+    readonly path: string;
+    readonly mimeType: string;
+    /** Decoded text for text mime types; undefined for binary files (not editable). */
+    text?: string;
+    readonly bytes: Uint8Array;
+}
+export interface EditOperation {
+    readonly path: string;
+    readonly oldStr: string;
+    readonly newStr: string;
+}
+/**
+ * Apply edits to a copy of the file list. Throws ArtifactOperationError
+ * ('edit_mismatch') on the first violation; the input files are never mutated.
+ */
+export declare function applyEdits(files: readonly EditableFile[], edits: readonly EditOperation[]): EditableFile[];

package/dist/server/edits.js

@@ -0,0 +1,43 @@
+/**
+ * Parity P0 — small old/new edits on publish.
+ *
+ * Edits apply to the current release's text files without resending the
+ * whole file set. `oldStr` must occur exactly once in the file text; any
+ * other count (or an unknown/non-text path) raises a typed `edit_mismatch`
+ * before anything is staged, so a failed call changes nothing. The edited
+ * files then become the new release through the same commit path.
+ */
+import { ArtifactOperationError } from './failures.js';
+function countOccurrences(haystack, needle) {
+    if (needle.length === 0)
+        return 0;
+    let count = 0;
+    let index = haystack.indexOf(needle);
+    while (index !== -1) {
+        count += 1;
+        index = haystack.indexOf(needle, index + Math.max(1, needle.length));
+    }
+    return count;
+}
+/**
+ * Apply edits to a copy of the file list. Throws ArtifactOperationError
+ * ('edit_mismatch') on the first violation; the input files are never mutated.
+ */
+export function applyEdits(files, edits) {
+    const result = files.map((file) => ({ ...file }));
+    for (const [editIndex, edit] of edits.entries()) {
+        const file = result.find((entry) => entry.path === edit.path);
+        if (file === undefined || file.text === undefined) {
+            throw new ArtifactOperationError('edit_mismatch', { edit: { path: edit.path, occurrences: -1,
+                    editIndex, reason: file === undefined ? 'file_missing' : 'not_text' } });
+        }
+        const occurrences = countOccurrences(file.text, edit.oldStr);
+        if (occurrences !== 1) {
+            throw new ArtifactOperationError('edit_mismatch', { edit: { path: edit.path, occurrences,
+                    editIndex, reason: occurrences === 0 ? 'missing' : 'ambiguous' } });
+        }
+        file.text = file.text.slice(0, file.text.indexOf(edit.oldStr)) + edit.newStr +
+            file.text.slice(file.text.indexOf(edit.oldStr) + edit.oldStr.length);
+    }
+    return result;
+}