@sentropic/artifacts 0.1.4 → 0.2.1

package/dist/profile/index.js

@@ -0,0 +1,117 @@
+import { isArtifactId } from '../contracts.js';
+import { ARTIFACT_CAPABILITY_NAMES, ArtifactProfileInputError, PROFILE_CONTRACT_VERSION } from './contracts.js';
+import { copyJson, freezeDeep, isRecord, orderedDigest } from './json.js';
+import { assertCompleteOperation, capabilitySchema } from './schemas.js';
+import { matchesSchema, normalizeArguments } from './validation.js';
+import { RADAR_ARTIFACTS_PROFILE } from './radar.js';
+import { compileValidators } from './validators.js';
+export * from './contracts.js';
+export { RADAR_ARTIFACTS_PROFILE } from './radar.js';
+const compiledProfiles = new WeakSet();
+export function assertCompiledArtifactsProfile(value) {
+    if (typeof value !== 'object' || value === null || !compiledProfiles.has(value)) {
+        throw new Error('invalid compiled artifacts profile');
+    }
+}
+/** Compile once, before any registry, adapter, schema or integrity evidence. */
+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'];
+    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 (new Set(requested).size !== requested.length ||
+        requested.some((name) => !ARTIFACT_CAPABILITY_NAMES.includes(name))) {
+        throw new Error('unknown or duplicate artifacts capability');
+    }
+    const selectedCapabilities = ARTIFACT_CAPABILITY_NAMES.filter((name) => requested.includes(name));
+    // Canonicalize set-like configuration while retaining command array order.
+    profile.selectedCapabilities = selectedCapabilities;
+    const operations = new Set();
+    for (const op of profile.operations) {
+        if (!op || typeof op.operation !== 'string' || operations.has(op.operation) ||
+            !isRecord(op.limits) || !isRecord(op.defaults) ||
+            !ARTIFACT_CAPABILITY_NAMES.includes(`artifacts_${op.operation}`) ||
+            Object.keys(op).some((key) => !['operation', 'limits', 'defaults'].includes(key)) ||
+            Object.values(op.limits).some((n) => typeof n !== 'number' || !Number.isSafeInteger(n) || n <= 0))
+            throw new Error('invalid operation profile');
+        assertCompleteOperation(op);
+        for (const [minimum, maximum] of [['bindingNameMinUnits', 'bindingNameMaxUnits'],
+            ['publishFilesMin', 'publishFilesMax'], ['listLimitMin', 'listLimitMax']]) {
+            if (op.limits[minimum] > op.limits[maximum])
+                throw new Error('inconsistent profile bounds');
+        }
+        operations.add(op.operation);
+    }
+    const rules = profile.rules;
+    const ruleKeys = ['lengthUnit', 'textEncoding', 'callerKeyNormalization', 'rejectLoneSurrogates',
+        'provenance', 'keyDerivationAlgorithm', 'pathMaxBytes', 'forbiddenPathPattern', 'reservedFirstSegments', 'mimeTypes'];
+    if (!rules || rules.lengthUnit !== 'utf16' || rules.textEncoding !== 'utf8' || rules.callerKeyNormalization !== 'none' ||
+        Object.keys(rules).some((key) => !ruleKeys.includes(key)) ||
+        rules.rejectLoneSurrogates !== true || rules.provenance !== 'inline-original' ||
+        typeof rules.keyDerivationAlgorithm !== 'string' || !rules.keyDerivationAlgorithm ||
+        !Number.isSafeInteger(rules.pathMaxBytes) || rules.pathMaxBytes < 1 || rules.pathMaxBytes > 1024 ||
+        !Array.isArray(rules.mimeTypes) || !rules.mimeTypes.length || rules.mimeTypes.some((v) => typeof v !== 'string' || !v) ||
+        !Array.isArray(rules.reservedFirstSegments) || rules.reservedFirstSegments.some((v) => typeof v !== 'string' || !v) ||
+        rules.forbiddenPathPattern !== '[\\\\%?#:\\u0000-\\u001f\\u007f]')
+        throw new Error('invalid profile semantics');
+    if (!profile.contractRevisions || profile.contractRevisions.profile !== PROFILE_CONTRACT_VERSION ||
+        profile.contractRevisions.command !== 'artifacts-command/v1' ||
+        !profile.contractRevisions.authorization || !profile.contractRevisions.outcome ||
+        Object.values(profile.contractRevisions).some((revision) => typeof revision !== 'string' || !revision)) {
+        throw new Error('invalid provider contract revisions');
+    }
+    const schemas = {};
+    const idempotency = {};
+    for (const name of selectedCapabilities) {
+        schemas[name] = capabilitySchema(name, profile);
+        const op = profile.operations.find((entry) => entry.operation === name.slice(10));
+        if (rules.keyDerivationAlgorithm === 'radar-derive-idempotency-v1' && op.limits.idempotencyKeyMaxUnits > 256) {
+            throw new Error('profile/derivation key length mismatch');
+        }
+        const defaults = op.defaults;
+        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 (name === 'artifacts_ensure' || name === 'artifacts_publish' || name === 'artifacts_commit_upload') {
+            idempotency[name] = { required: true, scope: 'principal' };
+        }
+    }
+    const assertSelected = (name) => {
+        if (!selectedCapabilities.includes(name))
+            throw new ArtifactProfileInputError(true);
+    };
+    const compiled = {
+        ...profile, selectedCapabilities, profile, schemas, idempotency,
+        get validators() { return validators; },
+        profileDigest: orderedDigest({ selection: selectedCapabilities, profile, schemas,
+            providerContractRevisions: profile.contractRevisions }),
+        assertSelected,
+        validate(name, args, envelopeKey) {
+            if (!selectedCapabilities.includes(name))
+                throw new ArtifactProfileInputError(true);
+            return normalizeArguments(profile, name, args, schemas[name], envelopeKey);
+        },
+        capabilityForRoute(method, path) {
+            let name;
+            if (method === 'POST' && path === '/ensure')
+                name = 'artifacts_ensure';
+            if (method === 'POST' && path === '/publish')
+                name = 'artifacts_publish';
+            if (method === 'POST' && path === '/list')
+                name = 'artifacts_list';
+            if (method === 'GET' && path.startsWith('/meta/') && isArtifactId(path.slice(6)))
+                name = 'artifacts_get';
+            return name && selectedCapabilities.includes(name) ? name : undefined;
+        },
+    };
+    const validators = compileValidators(compiled);
+    compiledProfiles.add(compiled);
+    return freezeDeep(compiled);
+}

package/dist/profile/json.d.ts

@@ -0,0 +1,10 @@
+import type { JsonValue } from '../contracts.js';
+/** Reject before UTF-8 conversion can replace an unpaired code unit. */
+export declare function assertWellFormed(value: string): void;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** An owned JSON snapshot, refusing non-JSON, accessors and cyclic inputs. */
+export declare function copyJson(value: unknown, ancestors?: Set<object>): JsonValue;
+export declare function freezeDeep<T>(value: T): T;
+/** Command/profile codec: objects sort recursively; arrays retain order. */
+export declare function orderedJson(value: unknown): string;
+export declare function orderedDigest(value: unknown): string;

package/dist/profile/json.js

@@ -0,0 +1,76 @@
+import { createHash } from 'node:crypto';
+import { ArtifactProfileInputError } from './contracts.js';
+/** Reject before UTF-8 conversion can replace an unpaired code unit. */
+export function assertWellFormed(value) {
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const next = value.charCodeAt(++i);
+            if (!(next >= 0xdc00 && next <= 0xdfff))
+                throw new ArtifactProfileInputError();
+        }
+        else if (code >= 0xdc00 && code <= 0xdfff)
+            throw new ArtifactProfileInputError();
+    }
+}
+export function isRecord(value) {
+    return value !== null && typeof value === 'object' &&
+        (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+}
+/** An owned JSON snapshot, refusing non-JSON, accessors and cyclic inputs. */
+export function copyJson(value, ancestors = new Set()) {
+    if (typeof value === 'string') {
+        assertWellFormed(value);
+        return value;
+    }
+    if (value === null || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value !== 'object' || value === null || ancestors.has(value))
+        throw new ArtifactProfileInputError();
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            return Array.from(value, (entry) => copyJson(entry, ancestors));
+        }
+        if (!isRecord(value) || Object.getOwnPropertySymbols(value).length)
+            throw new ArtifactProfileInputError();
+        const out = {};
+        for (const key of Object.keys(value)) {
+            assertWellFormed(key);
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!('value' in descriptor))
+                throw new ArtifactProfileInputError();
+            Object.defineProperty(out, key, { value: copyJson(descriptor.value, ancestors), enumerable: true,
+                writable: true, configurable: true });
+        }
+        return out;
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+export function freezeDeep(value) {
+    if (value !== null && typeof value === 'object') {
+        for (const child of Object.values(value))
+            freezeDeep(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+/** Command/profile codec: objects sort recursively; arrays retain order. */
+export function orderedJson(value) {
+    const canonicalize = (entry) => {
+        if (Array.isArray(entry))
+            return `[${entry.map(canonicalize).join(',')}]`;
+        if (entry !== null && typeof entry === 'object') {
+            return `{${Object.keys(entry).sort().map((key) => `${JSON.stringify(key)}:${canonicalize(entry[key])}`).join(',')}}`;
+        }
+        return JSON.stringify(entry);
+    };
+    return canonicalize(copyJson(value));
+}
+export function orderedDigest(value) {
+    return createHash('sha256').update(orderedJson(value), 'utf8').digest('hex');
+}

package/dist/profile/radar.d.ts

@@ -0,0 +1,3 @@
+import type { EffectiveArtifactProfile } from './contracts.js';
+/** Explicit host input, never an implicit fallback for a missing selection. */
+export declare const RADAR_ARTIFACTS_PROFILE: EffectiveArtifactProfile;

package/dist/profile/radar.js

@@ -0,0 +1,21 @@
+import { freezeDeep } from './json.js';
+/** Explicit host input, never an implicit fallback for a missing selection. */
+export const RADAR_ARTIFACTS_PROFILE = freezeDeep({
+    version: 'artifacts-profile/v1',
+    selectedCapabilities: ['artifacts_ensure', 'artifacts_publish', 'artifacts_list', 'artifacts_get'],
+    operations: [
+        { operation: 'ensure', limits: { bindingNameMinUnits: 1, bindingNameMaxUnits: 128,
+                idempotencyKeyMaxUnits: 256 }, defaults: { parameters: {} } },
+        { operation: 'publish', limits: { idempotencyKeyMaxUnits: 256, publishFilesMin: 1, publishFilesMax: 32,
+                maxDecodedFileBytes: 262144, maxDecodedTotalBytes: 262144 }, defaults: { profile: {} } },
+        { operation: 'list', limits: { listLimitMin: 1, listLimitMax: 100 }, defaults: { limit: 20, offset: 0 } },
+        { operation: 'get', limits: {}, defaults: {} },
+    ],
+    rules: { lengthUnit: 'utf16', textEncoding: 'utf8', callerKeyNormalization: 'none',
+        rejectLoneSurrogates: true, provenance: 'inline-original', keyDerivationAlgorithm: 'radar-derive-idempotency-v1', pathMaxBytes: 1024,
+        forbiddenPathPattern: '[\\\\%?#:\\u0000-\\u001f\\u007f]',
+        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' },
+});

package/dist/profile/schemas.d.ts

@@ -0,0 +1,6 @@
+import type { ArtifactCapabilityName, ArtifactProviderProfile, EffectiveArtifactProfile, ArtifactSchema, OperationProfile } from './contracts.js';
+/** Required configuration includes semantic limits absent from JSON Schema. */
+export declare function assertCompleteOperation(config: OperationProfile): void;
+export declare function operationProfile(profile: ArtifactProviderProfile, operation: string): OperationProfile;
+/** Schemas are generated from the same limits/defaults read by normalization. */
+export declare function capabilitySchema(name: ArtifactCapabilityName, profile: EffectiveArtifactProfile): ArtifactSchema;

package/dist/profile/schemas.js

@@ -0,0 +1,76 @@
+const str = { type: 'string', minLength: 1 };
+const integer = (minimum, maximum) => ({ type: 'integer', minimum,
+    ...(maximum === undefined ? {} : { maximum }) });
+const obj = (properties, required = []) => ({ type: 'object', properties, required, additionalProperties: false });
+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: {} };
+/** Required configuration includes semantic limits absent from JSON Schema. */
+export function assertCompleteOperation(config) {
+    const required = {
+        ensure: { limits: ['bindingNameMinUnits', 'bindingNameMaxUnits', 'idempotencyKeyMaxUnits'],
+            defaults: ['parameters'] },
+        publish: { limits: ['idempotencyKeyMaxUnits', 'publishFilesMin', 'publishFilesMax',
+                'maxDecodedFileBytes', 'maxDecodedTotalBytes'], defaults: ['profile'] },
+        list: { limits: ['listLimitMin', 'listLimitMax'], defaults: ['limit', 'offset'] },
+        commit_upload: { limits: ['idempotencyKeyMaxUnits'], defaults: ['profile'] },
+    };
+    const fields = required[config.operation];
+    if (fields && (fields.limits.some((key) => !Object.hasOwn(config.limits, key)) ||
+        fields.defaults.some((key) => !Object.hasOwn(config.defaults, key)))) {
+        throw new Error(`incomplete operation profile: ${config.operation}`);
+    }
+}
+export function operationProfile(profile, operation) {
+    const configured = profile.operations.find((entry) => entry.operation === operation);
+    if (!configured)
+        throw new Error(`missing operation profile: ${operation}`);
+    return configured;
+}
+/** Schemas are generated from the same limits/defaults read by normalization. */
+export function capabilitySchema(name, profile) {
+    const operation = name.slice('artifacts_'.length);
+    const config = operationProfile(profile, operation);
+    const limits = config.limits;
+    const key = { type: 'string', minLength: 1, maxLength: limits.idempotencyKeyMaxUnits,
+        description: 'Nonblank by JavaScript trim(); length is UTF-16 units; original bytes retained.' };
+    const idOnly = obj({ artifactId: id }, ['artifactId']);
+    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']);
+        case 'publish': {
+            const reserved = profile.rules.reservedFirstSegments.map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|');
+            const path = { type: 'string', minLength: 1, maxLength: profile.rules.pathMaxBytes,
+                allOf: [{ not: { pattern: profile.rules.forbiddenPathPattern } },
+                    { not: { pattern: '(^|/)(\\.\\.?|)(/|$)' } },
+                    { not: { pattern: `^(?:${reserved})(?:/|$)` } }],
+                description: `At most ${profile.rules.pathMaxBytes} UTF-8 bytes; no empty/dot segments, colon or DEL.` };
+            const file = { ...obj({ path, mimeType: { type: 'string', enum: profile.rules.mimeTypes },
+                    text: { type: 'string', maxLength: limits.maxDecodedFileBytes, description: 'UTF-8 decoded-byte budget applies.' },
+                    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']);
+        }
+        case 'list': return obj({ limit: { ...integer(limits.listLimitMin, limits.listLimitMax), default: config.defaults.limit },
+            offset: { ...integer(0), default: config.defaults.offset } });
+        case 'get':
+        case 'get_source':
+        case 'fork':
+        case 'renew':
+        case 'delete':
+        case 'restore': return idOnly;
+        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']);
+        case 'commit_upload': return obj({ artifactId: id, uploadId: str, path: str, mimeType: str,
+            digest: str, size: integer(0), profile: primitiveRecord, idempotencyKey: key }, ['artifactId', 'uploadId', 'path', 'mimeType', 'digest', 'size', 'idempotencyKey']);
+        case 'set_access': return obj({ artifactId: id, action: { type: 'string', enum: ['grant', 'revoke', 'set-public'] },
+            principalId: str, grant: { type: 'string', enum: ['read', 'source'] }, isPublic: { type: 'boolean' } }, ['artifactId', 'action']);
+        case 'promote': return obj({ artifactId: id, releaseId: id, expectedCurrent: id }, ['artifactId', 'releaseId', 'expectedCurrent']);
+        default: throw new Error(`unsupported operation profile: ${operation}`);
+    }
+}

package/dist/profile/validation.d.ts

@@ -0,0 +1,5 @@
+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>>;

package/dist/profile/validation.js

@@ -0,0 +1,104 @@
+import { isArtifactId } from '../contracts.js';
+import { ArtifactProfileInputError } from './contracts.js';
+import { copyJson, freezeDeep, isRecord } from './json.js';
+import { operationProfile } from './schemas.js';
+function requireInput(condition) {
+    if (!condition)
+        throw new ArtifactProfileInputError();
+}
+/** The generated schema vocabulary, evaluated without a platform dependency. */
+export function matchesSchema(value, schema) {
+    const type = schema.type;
+    if (Array.isArray(type))
+        return type.some((entry) => matchesSchema(value, { ...schema, type: entry }));
+    if (type === 'object' && !isRecord(value))
+        return false;
+    if (type === 'array' && !Array.isArray(value))
+        return false;
+    if (type === 'string' && typeof value !== 'string')
+        return false;
+    if (type === 'number' && (typeof value !== 'number' || !Number.isFinite(value)))
+        return false;
+    if (type === 'integer' && !Number.isSafeInteger(value))
+        return false;
+    if (type === 'boolean' && typeof value !== 'boolean')
+        return false;
+    if (type === 'null' && value !== null)
+        return false;
+    if (Array.isArray(schema.enum) && !schema.enum.includes(value))
+        return false;
+    if (schema.not && matchesSchema(value, schema.not))
+        return false;
+    if (Array.isArray(schema.allOf) && !schema.allOf.every((s) => matchesSchema(value, s)))
+        return false;
+    if (Array.isArray(schema.oneOf) && schema.oneOf.filter((s) => matchesSchema(value, s)).length !== 1)
+        return false;
+    if (typeof value === 'number' &&
+        ((typeof schema.minimum === 'number' && value < schema.minimum) ||
+            (typeof schema.maximum === 'number' && value > schema.maximum)))
+        return false;
+    if (typeof value === 'string') {
+        if (typeof schema.minLength === 'number' && value.length < schema.minLength)
+            return false;
+        if (typeof schema.maxLength === 'number' && value.length > schema.maxLength)
+            return false;
+        if (typeof schema.pattern === 'string' && !new RegExp(schema.pattern).test(value))
+            return false;
+    }
+    if (Array.isArray(value)) {
+        if (typeof schema.minItems === 'number' && value.length < schema.minItems)
+            return false;
+        if (typeof schema.maxItems === 'number' && value.length > schema.maxItems)
+            return false;
+        if (schema.items && !value.every((v) => matchesSchema(v, schema.items)))
+            return false;
+    }
+    if (isRecord(value)) {
+        if (Array.isArray(schema.required) && schema.required.some((key) => !Object.hasOwn(value, key)))
+            return false;
+        const properties = (schema.properties ?? {});
+        for (const [key, entry] of Object.entries(value)) {
+            if (schema.propertyNames && !matchesSchema(key, schema.propertyNames))
+                return false;
+            if (Object.hasOwn(properties, key)) {
+                if (!matchesSchema(entry, properties[key]))
+                    return false;
+            }
+            else if (schema.additionalProperties === false)
+                return false;
+            else if (isRecord(schema.additionalProperties) && !matchesSchema(entry, schema.additionalProperties))
+                return false;
+        }
+    }
+    return true;
+}
+export function normalizeArguments(profile, name, input, schema, envelopeKey) {
+    const args = copyJson(input);
+    requireInput(isRecord(args) && matchesSchema(args, schema));
+    const operation = name.slice('artifacts_'.length);
+    const { defaults, limits } = operationProfile(profile, operation);
+    const normalized = { ...copyJson(defaults), ...args };
+    if (operation === 'ensure' || operation === 'publish' || operation === 'commit_upload') {
+        const key = args.idempotencyKey;
+        requireInput(typeof key === 'string' && key.trim().length > 0 && key.length <= limits.idempotencyKeyMaxUnits);
+        requireInput(envelopeKey === undefined || envelopeKey === key);
+    }
+    else
+        requireInput(envelopeKey === undefined);
+    if (Object.hasOwn(args, 'artifactId'))
+        requireInput(isArtifactId(args.artifactId));
+    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 };
+        });
+    }
+    return freezeDeep(normalized);
+}

package/dist/profile/validators.d.ts

@@ -0,0 +1,3 @@
+import { type CompiledArtifactsProfile, type CompiledValidators } from './contracts.js';
+/** Validators close over the same immutable schemas, limits and command compiler. */
+export declare function compileValidators(profile: CompiledArtifactsProfile): CompiledValidators;

package/dist/profile/validators.js

@@ -0,0 +1,51 @@
+import { ArtifactProfileInputError } from './contracts.js';
+import { copyJson, isRecord } from './json.js';
+import { matchesSchema } from './validation.js';
+import { createArtifactCommand } from '../server/command-identity.js';
+/** Validators close over the same immutable schemas, limits and command compiler. */
+export function compileValidators(profile) {
+    const field = (schema, key) => schema?.properties?.[key];
+    const accepts = (check) => {
+        try {
+            return check();
+        }
+        catch (error) {
+            if (error instanceof ArtifactProfileInputError)
+                return false;
+            throw error;
+        }
+    };
+    const keySchemas = Object.values(profile.schemas).flatMap((schema) => {
+        const key = field(schema, 'idempotencyKey');
+        return key ? [key] : [];
+    });
+    return {
+        validateBindingName: (value) => accepts(() => {
+            const schema = field(profile.schemas.artifacts_ensure, 'bindingName');
+            return !!schema && matchesSchema(copyJson(value), schema);
+        }),
+        validateCallerKey: (value) => accepts(() => typeof value === 'string' && !!value.trim() &&
+            keySchemas.length > 0 && keySchemas.every((schema) => matchesSchema(copyJson(value), schema))),
+        validateFileEntry: (entry) => accepts(() => {
+            const schema = field(profile.schemas.artifacts_publish, 'files')?.items;
+            const file = copyJson(entry);
+            if (!schema || !isRecord(file) || !matchesSchema(file, schema))
+                return false;
+            const limits = profile.operations.find((op) => op.operation === 'publish').limits;
+            const size = Object.hasOwn(file, 'text') ? Buffer.byteLength(file.text, 'utf8') :
+                file.bytes.length;
+            return Buffer.byteLength(file.path, 'utf8') <= profile.rules.pathMaxBytes &&
+                size <= limits.maxDecodedFileBytes;
+        }),
+        normalizeCommand(value) {
+            if (!isRecord(value) || typeof value.capability !== 'string' || !isRecord(value.authority) ||
+                !isRecord(value.derivation) || typeof value.derivation.derive !== 'function' ||
+                (value.envelopeKey !== undefined && typeof value.envelopeKey !== 'string') ||
+                Object.keys(value).some((key) => !['capability', 'args', 'authority', 'derivation', 'envelopeKey'].includes(key))) {
+                throw new ArtifactProfileInputError();
+            }
+            const input = value;
+            return createArtifactCommand(profile, input.capability, input.args, input.authority, input.derivation, input.envelopeKey);
+        },
+    };
+}

package/dist/server/authorized-replay.d.ts

@@ -0,0 +1,33 @@
+/**
+ * L5 (immo #861) — guarded ensure replay (spec r2 §§3.1 A5/A7, 3.2).
+ *
+ * Ensure-domain adapter over the L3 finalization coordinator: replay goes
+ * through replayGuarded with the request-bound guard, never through a raw
+ * receipt read. A stored success replays only while currently authorized,
+ * without a quota recharge (the coordinator runs the pre-quota lock groups
+ * on the replay path). Unknown legacy codecs propagate as quarantine for
+ * the L6 migration projection.
+ */
+import type { ArtifactCommitCoordinator, FinalizeRequest, FinalizeResult, InternalIdempotencyKey, StoredCommitReceipt } from './commit/types.js';
+import type { ArtifactInvocationContext } from './commit/types.js';
+/** Durable ensure receipt carried by the success record. */
+export interface EnsureReceipt {
+    readonly artifactId: string;
+    readonly created: boolean;
+}
+/** Guarded replay input: durable key plus the effective command hash. */
+export interface GuardedReplayInput {
+    readonly invocation: ArtifactInvocationContext;
+    readonly internalKey: InternalIdempotencyKey;
+    readonly commandHash: string;
+    readonly policyRevision: string;
+    readonly locks?: FinalizeRequest['locks'];
+    readonly artifactId?: string;
+    readonly bindingName?: string;
+    readonly validateReplayReceipt?: FinalizeRequest['validateReplayReceipt'];
+    readonly noteAbandonedAttempt?: FinalizeRequest['noteAbandonedAttempt'];
+}
+/** Replay one ensure through the coordinator with the request-bound guard. */
+export declare function replayEnsureGuarded(coordinator: ArtifactCommitCoordinator, input: GuardedReplayInput): Promise<FinalizeResult>;
+/** Project a stored ensure receipt; rejects rows that are not ensure receipts. */
+export declare function projectEnsureReceipt(receipt: StoredCommitReceipt): EnsureReceipt;

package/dist/server/authorized-replay.js

@@ -0,0 +1,31 @@
+/** Replay one ensure through the coordinator with the request-bound guard. */
+export async function replayEnsureGuarded(coordinator, input) {
+    return coordinator.replayPrepared({
+        scopeId: input.invocation.storageScopeId,
+        internalKey: input.internalKey,
+        commandHash: input.commandHash,
+        codecVersion: 'artifacts-command/v1',
+        invocationId: input.invocation.invocationId,
+        actorId: input.invocation.actorId,
+        operation: 'ensure',
+        // The binding lock resolves the target before the coordinator builds its guard context.
+        get artifactId() { return input.artifactId ?? null; },
+        bindingName: input.bindingName ?? null,
+        policyRevision: input.policyRevision,
+        locks: input.locks,
+        guard: input.invocation.authorizeCommit,
+        receiptData: undefined,
+        validateReplayReceipt: input.validateReplayReceipt,
+        noteAbandonedAttempt: input.noteAbandonedAttempt,
+        attemptId: input.invocation.invocationId,
+    });
+}
+/** Project a stored ensure receipt; rejects rows that are not ensure receipts. */
+export function projectEnsureReceipt(receipt) {
+    const data = receipt.receipt;
+    if (typeof data?.artifactId !== 'string' || data.artifactId.length === 0 ||
+        typeof data?.created !== 'boolean') {
+        throw new Error('ensure receipt mismatch');
+    }
+    return { artifactId: data.artifactId, created: data.created };
+}

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

@@ -0,0 +1,52 @@
+import { type JsonValue } from '../contracts.js';
+import { type CompiledArtifactsProfile } from '../profile/index.js';
+import { orderedDigest } from '../profile/json.js';
+export declare const COMMAND_CODEC_VERSION: "artifacts-command/v1";
+export type CallerIdempotencyKey = string & {
+    readonly __brand: 'caller-key';
+};
+export type InternalIdempotencyKey = string & {
+    readonly __brand: 'internal-key';
+};
+export interface CommandIdentity {
+    readonly internalKey: InternalIdempotencyKey;
+    readonly commandHash: string;
+    readonly codecVersion: typeof COMMAND_CODEC_VERSION;
+}
+export interface EffectiveArtifactCommand {
+    readonly operation: 'ensure' | 'publish';
+    readonly scopeBinding: string;
+    readonly payload: Readonly<Record<string, JsonValue>>;
+    readonly provenance: {
+        readonly kind: 'inline-original';
+    };
+    readonly identity: CommandIdentity;
+}
+export interface ArtifactCommandAuthority {
+    readonly storageScopeId: string;
+    readonly actorId: string;
+}
+export interface ArtifactKeyDerivationBinding {
+    readonly algorithm: string;
+    derive(input: ArtifactCommandAuthority & {
+        readonly operation: 'ensure' | 'publish';
+        readonly objectId: string;
+        readonly callerKey: CallerIdempotencyKey;
+    }): InternalIdempotencyKey;
+}
+/** Trusted server input for the compiled command normalizer, never tool arguments. */
+export interface ArtifactCommandInput {
+    readonly capability: string;
+    readonly args: unknown;
+    readonly authority: ArtifactCommandAuthority;
+    readonly derivation: ArtifactKeyDerivationBinding;
+    readonly envelopeKey?: string;
+}
+/** Preserve Radar's durable bytes only within an explicitly qualified domain. */
+export declare function createRadarKeyDerivation(config: {
+    readonly storageScopeId: string;
+    readonly actorIds: readonly string[];
+}): 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;