@playcraft/cli 0.1.68 → 0.1.70

package/dist/asset-library/provenance.js

@@ -0,0 +1,169 @@
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { open, realpath } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { ASSET_TRANSFER_CHUNK_BYTES, WORKSPACE_LIBRARY_ATTACHMENT_MAX_BYTES, assetLibraryModelProvenanceSchema, workspaceAssetProvenanceDocumentSchema, canonicalAssetLibraryModelProvenance, } from '@playcraft/common/cloud-workspace/runtime';
+import { createAssetTransfer, putAssetTransferChunk, withAssetTransfer, safeAssetTransferDirectory, } from '../workspace-runtime/workspaces/asset-transfer-storage.js';
+import { publishAssetTransfer } from '../workspace-runtime/workspaces/asset-transfer-publish.js';
+import { observeWorkspaceBinaryFile } from '../workspace-runtime/workspaces/binary-write.js';
+export const WORKSPACE_ASSET_PROVENANCE_PATH = '.playcraft/asset-provenance.json';
+const MAX_DOCUMENT_BYTES = 16 * 1024 * 1024;
+const NOTICE_PATH = 'THIRD_PARTY_ASSETS.md';
+const START = '<!-- playcraft-asset-sources:start -->';
+const END = '<!-- playcraft-asset-sources:end -->';
+const digest = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const json = (value) => Buffer.from(JSON.stringify(value, null, 2) + '\n');
+const missing = (error) => error?.code === 'ENOENT';
+async function projectFile(root, path, maxBytes = MAX_DOCUMENT_BYTES) {
+    try {
+        await safeAssetTransferDirectory(root, dirname(path) === '.' ? '' : dirname(path));
+        const observed = await observeWorkspaceBinaryFile(root, path);
+        if (!observed)
+            return undefined;
+        if (observed.size > maxBytes)
+            throw new Error('asset_provenance_too_large');
+        const handle = await open(join(root, path), constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const stat = await handle.stat();
+            if (!stat.isFile() || stat.nlink !== 1 || stat.size !== observed.size)
+                throw new Error('asset_provenance_changed');
+            const bytes = await handle.readFile();
+            if (digest(bytes) !== observed.contentHash || (await observeWorkspaceBinaryFile(root, path))?.contentHash !== observed.contentHash)
+                throw new Error('asset_provenance_changed');
+            return bytes;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch (error) {
+        if (missing(error))
+            return undefined;
+        throw error;
+    }
+}
+export async function readWorkspaceAssetProvenance(root) {
+    const bytes = await projectFile(await realpath(root), WORKSPACE_ASSET_PROVENANCE_PATH);
+    return bytes ? workspaceAssetProvenanceDocumentSchema.parse(JSON.parse(bytes.toString('utf8'))) : undefined;
+}
+/** Generate portable records. Authority still comes from the immutable server version. */
+export function buildWorkspaceAssetProvenanceFiles(document, existingNotice = '') {
+    const parsed = workspaceAssetProvenanceDocumentSchema.parse(document);
+    const files = {};
+    const rows = [];
+    const clean = (value) => value.replace(/[\r\n|]/g, ' ');
+    for (const asset of [...parsed.assets].sort((a, b) => a.path.localeCompare(b.path, 'en'))) {
+        const licensePath = `licenses/assets/${digest(asset.provenance.licenseText)}.txt`;
+        if (asset.licensePath !== licensePath)
+            throw new Error('asset_provenance_license_path_mismatch');
+        files[licensePath] = Buffer.from(asset.provenance.licenseText);
+        rows.push(`| ${clean(asset.path)} | ${clean(asset.provenance.author)} | ${asset.provenance.sourceUrl} | [CC0-1.0](${licensePath}) | ${asset.provenance.revisionId} |`);
+    }
+    const managed = `${START}\n## Third-party model sources / 第三方模型来源\n\nThese models are third-party CC0 assets. Attribution is not required by CC0; this record preserves their provenance.\n这些模型为第三方 CC0 资产。CC0 不要求署名，本清单用于保留来源记录。\n\n| Path / 路径 | Author / 作者 | Source / 来源 | License / 许可 | Revision / 版本 |\n| --- | --- | --- | --- | --- |\n${rows.join('\n')}\n${END}`;
+    const start = existingNotice.indexOf(START), end = existingNotice.indexOf(END);
+    if ((start < 0) !== (end < 0) || start >= 0 && end < start)
+        throw new Error('asset_provenance_notice_conflict');
+    const notice = start >= 0
+        ? existingNotice.slice(0, start) + managed + existingNotice.slice(end + END.length)
+        : [existingNotice.trimEnd(), managed].filter(Boolean).join('\n\n') + '\n';
+    files[WORKSPACE_ASSET_PROVENANCE_PATH] = json(parsed);
+    files[NOTICE_PATH] = Buffer.from(notice);
+    return files;
+}
+/** Verify source and bytes before declaring an export source-complete. */
+export async function verifyWorkspaceAssetProvenance(root, options = {}) {
+    const rootReal = await realpath(root), document = await readWorkspaceAssetProvenance(rootReal);
+    const recordedPaths = new Set(document?.assets.map(asset => asset.path));
+    for (const path of new Set(options.expectedModelPaths ?? [])) {
+        if (!path.toLowerCase().endsWith('.glb'))
+            throw new Error('asset_provenance_expected_path_invalid');
+        if (await observeWorkspaceBinaryFile(rootReal, path) && !recordedPaths.has(path))
+            throw new Error('asset_provenance_record_missing');
+    }
+    if (!document)
+        return undefined;
+    if (!options.verify)
+        throw new Error('asset_provenance_authority_required');
+    buildWorkspaceAssetProvenanceFiles(document);
+    const verified = new Set();
+    for (const asset of document.assets) {
+        const identity = canonicalAssetLibraryModelProvenance(asset.provenance);
+        if (!verified.has(identity)) {
+            await options.verify(asset.provenance);
+            verified.add(identity);
+        }
+        const model = await observeWorkspaceBinaryFile(rootReal, asset.path);
+        if (model?.contentHash !== asset.provenance.modelSha256)
+            throw new Error('asset_provenance_model_changed');
+        const license = await projectFile(rootReal, asset.licensePath, 64 * 1024);
+        if (!license || !license.equals(Buffer.from(asset.provenance.licenseText)))
+            throw new Error('asset_provenance_license_changed');
+    }
+    return document;
+}
+function transferIdentifier(value) {
+    const hash = digest(value);
+    return `${hash.slice(0, 8)}-${hash.slice(8, 12)}-4${hash.slice(13, 16)}-a${hash.slice(17, 20)}-${hash.slice(20, 32)}`;
+}
+/** Reuse the existing multi-file publication journal for model bytes and provenance together. */
+export async function publishLibraryModels(root, input, options = {}) {
+    if (!input.length || new Set(input.map(model => model.path.toLowerCase())).size !== input.length)
+        throw new Error('invalid_library_model_publication');
+    const rootReal = await realpath(root);
+    for (const model of input) {
+        model.provenance = assetLibraryModelProvenanceSchema.parse(model.provenance);
+        if (!model.path.toLowerCase().endsWith('.glb') || digest(model.bytes) !== model.provenance.modelSha256)
+            throw new Error('library_asset_changed');
+    }
+    const operationId = options.operationId ?? `library-model:${digest(JSON.stringify(input.map(model => [model.path, model.provenance.revisionId])))}`;
+    const transferId = transferIdentifier(operationId);
+    const scope = options.scope ?? { environment: 'local-library', userId: 'local-library',
+        workspaceId: digest(rootReal), directoryName: 'library' };
+    const existing = await withAssetTransfer(rootReal, scope, transferId, async (transfer) => ({
+        manifest: transfer.record.manifest, manifestHash: transfer.record.manifestHash,
+    })).catch(error => { if (error.code === 'asset_transfer_not_found')
+        return undefined; throw error; });
+    if (existing) {
+        for (const model of input)
+            if (!existing.manifest.files.some(file => file.path === model.path && file.contentHash === model.provenance.modelSha256))
+                throw new Error('asset_transfer_manifest_conflict');
+        const receipt = await publishAssetTransfer(rootReal, scope, { transferId, manifestHash: existing.manifestHash }, { operationId, assertCurrent: options.assertCurrent });
+        const saved = await readWorkspaceAssetProvenance(rootReal);
+        for (const model of input) {
+            const entry = saved?.assets.find(asset => asset.path === model.path);
+            if (!entry || canonicalAssetLibraryModelProvenance(entry.provenance) !== canonicalAssetLibraryModelProvenance(model.provenance)
+                || (await observeWorkspaceBinaryFile(rootReal, model.path))?.contentHash !== model.provenance.modelSha256)
+                throw new Error('asset_provenance_model_changed');
+        }
+        return receipt;
+    }
+    if (options.requireExisting)
+        throw new Error('asset_transfer_not_found');
+    const sourceRecord = await projectFile(rootReal, WORKSPACE_ASSET_PROVENANCE_PATH);
+    const current = sourceRecord ? workspaceAssetProvenanceDocumentSchema.parse(JSON.parse(sourceRecord.toString('utf8')))
+        : { schemaVersion: 1, assets: [] };
+    const paths = new Set(input.map(model => model.path.toLowerCase()));
+    const document = workspaceAssetProvenanceDocumentSchema.parse({ schemaVersion: 1,
+        assets: [...current.assets.filter(asset => !paths.has(asset.path.toLowerCase())), ...input.map(model => ({ path: model.path,
+                licensePath: `licenses/assets/${digest(model.provenance.licenseText)}.txt`, provenance: model.provenance }))] });
+    const notice = await projectFile(rootReal, NOTICE_PATH);
+    const records = buildWorkspaceAssetProvenanceFiles(document, notice?.toString('utf8'));
+    const files = [...input.map(model => ({ path: model.path, bytes: model.bytes, expectedContentHash: model.expectedContentHash })),
+        ...await Promise.all(Object.entries(records).map(async ([path, bytes]) => ({ path, bytes,
+            expectedContentHash: path === WORKSPACE_ASSET_PROVENANCE_PATH ? sourceRecord ? digest(sourceRecord) : null
+                : path === NOTICE_PATH ? notice ? digest(notice) : null
+                    : (await observeWorkspaceBinaryFile(rootReal, path))?.contentHash ?? null })))];
+    if (files.reduce((sum, file) => sum + file.bytes.length, 0) > WORKSPACE_LIBRARY_ATTACHMENT_MAX_BYTES)
+        throw new Error('library_asset_too_large');
+    const manifest = { transferId, files: files.map(file => ({ path: file.path, size: file.bytes.length,
+            chunkHashes: Array.from({ length: Math.ceil(file.bytes.length / ASSET_TRANSFER_CHUNK_BYTES) }, (_, index) => digest(file.bytes.subarray(index * ASSET_TRANSFER_CHUNK_BYTES, (index + 1) * ASSET_TRANSFER_CHUNK_BYTES))),
+            contentHash: digest(file.bytes), expectedContentHash: file.expectedContentHash })) };
+    const transfer = await createAssetTransfer(rootReal, scope, manifest);
+    for (const [fileIndex, file] of files.entries())
+        for (const [chunkIndex] of manifest.files[fileIndex].chunkHashes.entries()) {
+            await options.assertCurrent?.();
+            await putAssetTransferChunk(rootReal, scope, transferId, { fileIndex, chunkIndex,
+                contentBase64: file.bytes.subarray(chunkIndex * ASSET_TRANSFER_CHUNK_BYTES, (chunkIndex + 1) * ASSET_TRANSFER_CHUNK_BYTES).toString('base64') });
+        }
+    return publishAssetTransfer(rootReal, scope, { transferId, manifestHash: transfer.manifestHash }, { operationId, assertCurrent: options.assertCurrent, onPublishedFile: options.onPublishedFile });
+}

package/dist/commands/library-messages.js

@@ -2,14 +2,23 @@ const messages = {
     en: {
         topic: 'Find and download authorized shared asset library content',
         list: 'List library assets with filters and pagination', search: 'Search library names and content metadata',
-        get: 'Read asset metadata', files: 'List every file in an asset or bundle', facets: 'Inspect available categories and tags',
-        download: 'Download an asset or a complete bundle with relative dependencies',
+        get: 'Read asset metadata', files: 'List every file in an asset or file bundle', facets: 'Inspect available categories and tags',
+        kits: 'Find asset kits', kit: 'Read an asset kit and check which needs its models cover',
+        kitId: 'Asset kit identifier', kitNeeds: 'Up to 12 comma-separated model needs, each at most 80 characters',
+        invalidKitId: 'Expected a lowercase asset kit identifier with letters, numbers and single hyphens, up to 80 characters.',
+        invalidKitNeeds: 'Expected 1–12 nonempty model needs, each at most 80 characters and at most 1024 characters in total, without control characters.',
+        download: 'Download an asset or a complete file bundle with relative dependencies',
         query: 'Search text', id: 'Library asset identifier', type: 'Asset type', path: 'Library path prefix',
         category: 'Category', subcategory: 'Subcategory', tags: 'Comma-separated tags',
         visibility: 'public | team', team: 'Authorized team identifier', page: 'Page number, starting at 1',
-        limit: 'Results per page (1–100)', sort: 'modifiedAt | createdAt | name | referenceCount | size', order: 'asc | desc',
-        expand: 'Return individual files instead of collapsed bundles',
-        output: 'New file path, or a new directory for a bundle', outputDir: 'New directory for the downloaded content',
+        limit: 'Results per page (1–100)', sort: 'modifiedAt | createdAt | name | referenceCount | size | relevance', order: 'asc | desc',
+        license: 'Required model license', modelCapability: 'Required verified model capability', modelStyle: 'Model style group',
+        maxBytes: 'Maximum model file bytes', maxTriangles: 'Maximum triangle count', revision: 'Exact immutable model revision',
+        projectRoot: 'Project root for model provenance records', invalidRevision: 'Invalid model revision identifier.',
+        projectOutputRequired: 'A curated model must be saved inside its project root. Use --project-root to select it.',
+        resume: 'Resume the saved curated-model transaction for the same revision and destination',
+        expand: 'Return individual files instead of collapsed file bundles',
+        output: 'New file path, or a new directory for a file bundle', outputDir: 'New directory for the downloaded content',
         json: 'Print machine-readable JSON (JavaScript Object Notation, 数据交换格式; always enabled)',
         invalidNumber: 'Expected a positive integer.', invalidId: 'Invalid library asset identifier.',
         invalidManifest: 'The library returned an invalid or unsafe file manifest.',
@@ -20,13 +29,22 @@ const messages = {
     zh: {
         topic: '检索和下载有权访问的共享素材库内容',
         list: '按条件分页列出素材库内容', search: '检索素材名称和内容元数据',
-        get: '读取素材详情', files: '列出素材或素材包内的全部文件', facets: '查看可用分类与标签',
-        download: '下载素材或完整素材包，保留依赖文件的相对路径',
+        get: '读取素材详情', files: '列出素材或文件集合内的全部文件', facets: '查看可用分类与标签',
+        kits: '查找素材包', kit: '读取素材包，并检查模型对所需素材的覆盖情况',
+        kitId: '素材包编号', kitNeeds: '所需素材，逗号分隔，最多 12 项，每项最多 80 个字符',
+        invalidKitId: '素材包编号须使用小写字母、数字和单个连字符，最多 80 个字符。',
+        invalidKitNeeds: '请输入 1～12 项非空素材需求，每项最多 80 个字符，总长最多 1024 个字符，不能包含控制字符。',
+        download: '下载素材或完整文件集合，保留依赖文件的相对路径',
         query: '检索文本', id: '素材库中的素材编号', type: '素材类型', path: '素材库路径前缀',
         category: '分类', subcategory: '子分类', tags: '标签，逗号分隔',
         visibility: 'public（公共）或 team（团队）', team: '有权访问的团队编号', page: '页码，从 1 开始',
-        limit: '每页数量（1–100）', sort: 'modifiedAt | createdAt | name | referenceCount | size', order: 'asc | desc',
-        expand: '返回单独文件，不折叠素材包', output: '新的文件路径；素材包则为新的目录', outputDir: '下载内容的新目录',
+        limit: '每页数量（1–100）', sort: 'modifiedAt | createdAt | name | referenceCount | size | relevance', order: 'asc | desc',
+        license: '模型必须满足的许可', modelCapability: '必须通过验证的模型能力', modelStyle: '模型风格组',
+        maxBytes: '模型文件的最大字节数', maxTriangles: '最大三角面数', revision: '确切的不可变模型版本',
+        projectRoot: '保存模型来源记录的工程根目录', invalidRevision: '模型版本编号无效。',
+        projectOutputRequired: '精选模型需要保存到工程根目录内，可使用 --project-root 指定工程。',
+        resume: '恢复相同版本与目标路径的精选模型保存事务',
+        expand: '返回单独文件，不折叠文件集合', output: '新的文件路径；文件集合则为新的目录', outputDir: '下载内容的新目录',
         json: '输出机器可读的 JSON (JavaScript Object Notation, 数据交换格式)，始终启用',
         invalidNumber: '请输入正整数。', invalidId: '素材库编号无效。',
         invalidManifest: '素材库返回的文件清单无效或包含不安全路径。',

package/dist/commands/library.js

@@ -1,14 +1,29 @@
 import { InvalidArgumentError, Option } from 'commander';
-import { link, lstat, mkdir, mkdtemp, rename, rm } from 'node:fs/promises';
-import { dirname, join, posix, resolve } from 'node:path';
+import { link, lstat, mkdir, mkdtemp, readFile, realpath, rename, rm } from 'node:fs/promises';
+import { basename, dirname, join, posix, relative, resolve, sep } from 'node:path';
+import { assetLibraryModelProvenanceSchema } from '@playcraft/common/cloud-workspace/runtime';
 import { AgentApiClient } from '../utils/agent-api-client.js';
 import { resolveSandboxPath } from '../utils/sandbox-path.js';
 import { libraryMessage as t, LibraryError } from './library-messages.js';
+import { publishLibraryModels, WORKSPACE_ASSET_PROVENANCE_PATH } from '../asset-library/provenance.js';
 function assetId(value) {
     if (!/^(?:\d{1,20}|[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12})$/i.test(value))
         throw new InvalidArgumentError(t('invalidId'));
     return value;
 }
+function kitId(value) {
+    if (value.length > 80 || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value))
+        throw new InvalidArgumentError(t('invalidKitId'));
+    return value;
+}
+function kitNeeds(value) {
+    if ([...value].length > 1024 || /\p{Cc}/u.test(value))
+        throw new InvalidArgumentError(t('invalidKitNeeds'));
+    const needs = value.split(/[,，]/).map(need => need.trim());
+    if (needs.length > 12 || needs.some(need => !need || [...need].length > 80))
+        throw new InvalidArgumentError(t('invalidKitNeeds'));
+    return needs.join(',');
+}
 function positiveInteger(value) {
     if (!/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(Number(value)))
         throw new InvalidArgumentError(t('invalidNumber'));
@@ -26,9 +41,13 @@ function filters(command) {
             throw new InvalidArgumentError(t('limit'));
         return value;
     }, '30')
-        .addOption(new Option('--sort-by <field>', t('sort')).choices(['modifiedAt', 'createdAt', 'name', 'referenceCount', 'size']))
+        .addOption(new Option('--sort-by <field>', t('sort')).choices(['modifiedAt', 'createdAt', 'name', 'referenceCount', 'size', 'relevance']))
         .addOption(new Option('--sort-order <order>', t('order')).choices(['asc', 'desc']))
-        .option('--expand-prefabs', t('expand')).option('--json', t('json'));
+        .option('--expand-prefabs', t('expand'))
+        .addOption(new Option('--license <license>', t('license')).choices(['CC0-1.0']))
+        .addOption(new Option('--model-capability <capability>', t('modelCapability')).choices(['static-prop', 'rigid-parts']))
+        .option('--model-style <style>', t('modelStyle')).option('--max-bytes <bytes>', t('maxBytes'), positiveInteger)
+        .option('--max-triangles <count>', t('maxTriangles'), positiveInteger).option('--json', t('json'));
 }
 function query(options) {
     return Object.fromEntries(Object.entries(options)
@@ -73,18 +92,30 @@ function validatedFiles(manifest) {
                 throw new LibraryError('invalidManifest');
         }
     }
+    if (manifest.provenance) {
+        const provenance = assetLibraryModelProvenanceSchema.safeParse(manifest.provenance);
+        if (!provenance.success || provenance.data.assetId !== manifest.assetId || manifest.kind !== 'file'
+            || manifest.files[0]?.sha256 !== provenance.data.modelSha256 || !manifest.files[0]?.path.toLowerCase().endsWith('.glb'))
+            throw new LibraryError('invalidManifest');
+        manifest.provenance = provenance.data;
+    }
     return manifest.files;
 }
 export async function downloadLibraryAsset(client, id, options) {
     if (Boolean(options.output) === Boolean(options.outputDir))
         throw new LibraryError('outputRequired');
     assetId(id);
-    const manifest = await client.get(`/asset-library/${encodeURIComponent(id)}/files`);
+    if (options.revisionId && !/^[a-f0-9]{64}$/.test(options.revisionId))
+        throw new LibraryError('invalidRevision');
+    const manifestPath = `/asset-library/${encodeURIComponent(id)}/files`;
+    const manifest = await client.get(manifestPath, { provenanceProtocol: '1', ...(options.revisionId ? { revisionId: options.revisionId } : {}) });
     const files = validatedFiles(manifest);
+    if (options.revisionId && manifest.provenance?.revisionId !== options.revisionId)
+        throw new LibraryError('invalidManifest');
     const destination = resolve(resolveSandboxPath(options.output ?? options.outputDir));
     const existing = await lstat(destination).catch(error => { if (error.code === 'ENOENT')
         return undefined; throw error; });
-    if (existing)
+    if (existing && !(manifest.provenance && options.resume))
         throw new LibraryError('outputExists');
     await mkdir(dirname(destination), { recursive: true });
     const staging = await mkdtemp(join(dirname(destination), '.playcraft-library-'));
@@ -93,13 +124,26 @@ export async function downloadLibraryAsset(client, id, options) {
     try {
         for (const file of files) {
             const target = directory ? join(staging, file.path) : join(staging, 'content');
-            const { bytes } = await client.download(`/asset-library/${encodeURIComponent(file.id)}/file`, target);
+            const revision = manifest.provenance ? `?revisionId=${manifest.provenance.revisionId}&provenanceProtocol=1` : '';
+            const { bytes } = await client.download(`/asset-library/${encodeURIComponent(file.id)}/file${revision}`, target);
             downloaded.push({ id: file.id, path: directory ? join(destination, file.path) : destination, bytes });
         }
         // Recheck before publishing the complete bundle; failures never expose a partial download.
-        if (await lstat(destination).catch(error => { if (error.code === 'ENOENT')
+        if (!(manifest.provenance && options.resume) && await lstat(destination).catch(error => { if (error.code === 'ENOENT')
             return undefined; throw error; }))
             throw new LibraryError('outputExists');
+        if (manifest.provenance) {
+            const projectRoot = await realpath(resolve(options.projectRoot ?? process.cwd()));
+            const canonicalDestination = join(await realpath(dirname(destination)), basename(destination));
+            const target = directory ? join(canonicalDestination, files[0].path) : canonicalDestination;
+            const path = relative(projectRoot, target).split(sep).join('/');
+            if (!path || path.startsWith('../') || posix.isAbsolute(path))
+                throw new LibraryError('projectOutputRequired');
+            const bytes = await readFile(directory ? join(staging, files[0].path) : join(staging, 'content'));
+            const receipt = await publishLibraryModels(projectRoot, [{ path, bytes, provenance: manifest.provenance, expectedContentHash: null }], { requireExisting: options.resume });
+            return { assetId: manifest.assetId, kind: manifest.kind, output: destination, files: downloaded,
+                provenance: { path: join(projectRoot, WORKSPACE_ASSET_PROVENANCE_PATH), revisionId: manifest.provenance.revisionId, receipt } };
+        }
         if (directory)
             await rename(staging, destination);
         else
@@ -112,6 +156,11 @@ export async function downloadLibraryAsset(client, id, options) {
 }
 export function registerLibraryCommands(program) {
     const library = program.command('library').description(t('topic'));
+    library.command('kits').description(t('kits')).option('--search <text>', t('query')).option('--json', t('json'))
+        .action((options) => action(() => new AgentApiClient().get('/asset-library/kits', options.search === undefined ? undefined : { search: options.search })));
+    library.command('kit').description(t('kit')).argument('<kitId>', t('kitId'), kitId)
+        .option('--needs <items>', t('kitNeeds'), kitNeeds).option('--json', t('json'))
+        .action((id, options) => action(() => new AgentApiClient().get(`/asset-library/kits/${encodeURIComponent(id)}`, options.needs === undefined ? undefined : { needs: options.needs })));
     filters(library.command('list').description(t('list')))
         .action((options) => action(() => new AgentApiClient().get('/asset-library', query(options))));
     filters(library.command('search').description(t('search')).argument('<query>', t('query')))
@@ -122,9 +171,12 @@ export function registerLibraryCommands(program) {
         .action((options) => action(() => new AgentApiClient().get('/asset-library/facets', query(options))));
     for (const command of ['get', 'files']) {
         library.command(command).description(t(command)).argument('<assetId>', t('id'), assetId).option('--json', t('json'))
-            .action((id) => action(() => new AgentApiClient().get(`/asset-library/${encodeURIComponent(id)}${command === 'files' ? '/files' : ''}`)));
+            .option('--revision-id <revision>', t('revision'))
+            .action((id, options) => action(() => new AgentApiClient().get(`/asset-library/${encodeURIComponent(id)}${command === 'files' ? '/files' : ''}`, { ...(command === 'files' ? { provenanceProtocol: '1' } : {}), ...(options.revisionId ? { revisionId: options.revisionId } : {}) })));
     }
     library.command('download').description(t('download')).argument('<assetId>', t('id'), assetId)
-        .option('--output <path>', t('output')).option('--output-dir <directory>', t('outputDir')).option('--json', t('json'))
+        .option('--output <path>', t('output')).option('--output-dir <directory>', t('outputDir'))
+        .option('--project-root <directory>', t('projectRoot')).option('--revision-id <revision>', t('revision')).option('--json', t('json'))
+        .option('--resume', t('resume'))
         .action((id, options) => action(() => downloadLibraryAsset(new AgentApiClient(), id, options)));
 }

package/dist/model-adaptation/project-template.js

@@ -125,6 +125,40 @@ import { join, relative } from 'node:path';
 const hash = bytes => createHash('sha256').update(bytes).digest('hex');
 const canonical = value => Array.isArray(value) ? '[' + value.map(canonical).join(',') + ']' : value && typeof value === 'object'
   ? '{' + Object.keys(value).sort().map(key => JSON.stringify(key) + ':' + canonical(value[key])).join(',') + '}' : JSON.stringify(value);
+export async function prepareModelAssetSources(root) {
+  const read = async (path, limit = 64 * 1024 * 1024) => {
+    if (typeof path !== 'string' || !path || path.length > 1024 || /[\\\0:]/.test(path) || path.startsWith('/') ||
+      path.split('/').some(part => !part || part === '.' || part === '..')) throw Error('asset_provenance_path_invalid');
+    let current = root;
+    const parts = path.split('/');
+    for (const [index, part] of parts.entries()) {
+      current = join(current, part); const stat = await lstat(current);
+      if (stat.isSymbolicLink() || (index < parts.length - 1 ? !stat.isDirectory() : !stat.isFile() || stat.nlink !== 1 || stat.size > limit))
+        throw Error('asset_provenance_file_invalid');
+    }
+    return readFile(current);
+  };
+  let raw;
+  try { raw = await read('.playcraft/asset-provenance.json', 16 * 1024 * 1024); }
+  catch (error) { if (error.code === 'ENOENT') return undefined; throw error; }
+  const document = JSON.parse(raw.toString('utf8'));
+  if (document.schemaVersion !== 1 || !Array.isArray(document.assets) || document.assets.length > 1024) throw Error('asset_provenance_invalid');
+  const paths = new Set(), licenses = new Map();
+  for (const asset of document.assets) {
+    const provenance = asset.provenance;
+    if (!provenance || provenance.schemaVersion !== 1 || provenance.license !== 'CC0-1.0' ||
+      !/^[a-f0-9]{64}$/.test(provenance.modelSha256) || typeof provenance.licenseText !== 'string' ||
+      Buffer.byteLength(provenance.licenseText) > 64 * 1024 || paths.has(asset.path)) throw Error('asset_provenance_invalid');
+    paths.add(asset.path);
+    if (hash(await read(asset.path)) !== provenance.modelSha256) throw Error('asset_provenance_model_changed');
+    const expectedLicense = 'licenses/assets/' + hash(provenance.licenseText) + '.txt';
+    if (asset.licensePath !== expectedLicense) throw Error('asset_provenance_license_path_mismatch');
+    const license = await read(asset.licensePath, 64 * 1024);
+    if (!license.equals(Buffer.from(provenance.licenseText))) throw Error('asset_provenance_license_changed');
+    licenses.set(asset.licensePath, license);
+  }
+  return { document, licenses, sourceRecordHash: hash(raw), verification: 'matches-recorded-inputs' };
+}
 export async function prepareModelBuild(root) {
   const configRaw = await readFile(join(root, '.playcraft/model-adaptation.json'), 'utf8'), plan = JSON.parse(configRaw);
   const meta = JSON.parse(await readFile(join(root, '.playcraft/model-adaptation-lineage.json'), 'utf8'));
@@ -186,9 +220,28 @@ export async function prepareModelBuild(root) {
 `;
 export const modelProjectVite = String.raw `import { defineConfig } from 'vite';
 import { fileURLToPath } from 'node:url';
-import { prepareModelBuild } from './scripts/prepare-build.mjs';
-export default defineConfig({ base: './', plugins: [{ name: 'model-adaptation-frozen-inputs', async transformIndexHtml() {
-  const evidence = await prepareModelBuild(fileURLToPath(new URL('./', import.meta.url)));
+import { createHash } from 'node:crypto';
+import { prepareModelBuild, prepareModelAssetSources } from './scripts/prepare-build.mjs';
+const root = fileURLToPath(new URL('./', import.meta.url));
+export default defineConfig({ base: './', plugins: [{ name: 'model-adaptation-frozen-inputs', enforce: 'post', async transformIndexHtml() {
+  const evidence = await prepareModelBuild(root);
   return [{ tag: 'script', attrs: { id: 'playcraft-source-evidence', type: 'application/json' }, children: JSON.stringify(evidence).replace(/</g, '\\u003c'), injectTo: 'head' }];
+}, async generateBundle(_options, bundle) {
+  const sources = await prepareModelAssetSources(root);
+  if (!sources) return;
+  const html = bundle['index.html'];
+  if (!html || html.type !== 'asset') throw Error('asset_provenance_delivery_missing');
+  const digest = source => createHash('sha256').update(source).digest('hex');
+  const artifactHash = digest(html.source);
+  const artifacts = Object.values(bundle).map(entry => ({ path: entry.fileName,
+    sha256: digest(entry.type === 'asset' ? entry.source : entry.code) }));
+  for (const [path, bytes] of sources.licenses) artifacts.push({ path, sha256: digest(bytes) });
+  artifacts.sort((a, b) => a.path.localeCompare(b.path, 'en'));
+  this.emitFile({ type: 'asset', fileName: 'asset-sources.json', source: JSON.stringify({
+    schemaVersion: 1, sourceRecordHash: sources.sourceRecordHash, verification: sources.verification,
+    artifact: { path: 'index.html', sha256: artifactHash }, artifacts,
+    assets: sources.document.assets.map(asset => ({ ...asset, deliveryRepresentation: 'embedded-model' }))
+  }, null, 2) + '\n' });
+  for (const [fileName, source] of sources.licenses) this.emitFile({ type: 'asset', fileName, source });
 } }], build: { outDir: 'dist', emptyOutDir: true, assetsInlineLimit: Infinity, sourcemap: false } });
 `;

package/dist/model-adaptation/project.js

@@ -4,6 +4,7 @@ import { createRequire } from 'node:module';
 import { canonicalModelAdaptation, workspaceModelAdaptationSchema } from '@playcraft/common/cloud-workspace/runtime';
 import { inspectModelSourceFiles, modelSourceDigest } from './source.js';
 import { modelProjectAdapter, modelProjectHtml, modelProjectMain, modelProjectPrepare, modelProjectStrings, modelProjectStyle, modelProjectVite } from './project-template.js';
+import { buildWorkspaceAssetProvenanceFiles, readWorkspaceAssetProvenance } from '../asset-library/provenance.js';
 export async function generateModelAdaptationProject(input) {
     input.signal?.throwIfAborted();
     const root = await realpath(resolve(input.projectRoot)), planPath = resolve(root, input.planPath), info = await lstat(planPath);
@@ -31,6 +32,18 @@ export async function generateModelAdaptationProject(input) {
     if (await realpath(dirname(outputRoot)) !== dirname(outputRoot))
         throw new Error('model_adaptation_output_parent_must_be_canonical');
     const json = (value) => JSON.stringify(value, null, 2) + '\n';
+    const importedSources = await readWorkspaceAssetProvenance(root);
+    const sourcePaths = new Set(source.source.files.map(file => file.path));
+    const provenanceAssets = importedSources?.assets.filter(asset => sourcePaths.has(asset.path)).flatMap(asset => {
+        const bytes = source.originalFiles.get(asset.path);
+        if (!bytes || modelSourceDigest(bytes) !== asset.provenance.modelSha256)
+            throw new Error('asset_provenance_model_changed');
+        const original = { ...asset, path: `source/${asset.path}` };
+        return asset.path === parentPlan.source.path && source.packedHash === asset.provenance.modelSha256
+            ? [original, { ...asset, path: 'src/assets/packed-model.glb' }] : [original];
+    }) ?? [];
+    const provenanceFiles = provenanceAssets.length
+        ? buildWorkspaceAssetProvenanceFiles({ schemaVersion: 1, assets: provenanceAssets }) : {};
     const files = {
         'package.json': json({ name: 'playcraft-adapted-model-project', version: '0.0.0', private: true, type: 'module',
             scripts: { dev: 'vite --host 0.0.0.0', build: 'vite build' }, dependencies: { three: '0.183.2', '@noble/hashes': '2.0.1' }, devDependencies: { vite: '7.1.3' } }),
@@ -50,9 +63,10 @@ export async function generateModelAdaptationProject(input) {
             } }),
         'AGENTS.md': '# Adapted model project\n\nSource files and the parent adaptation bytes are immutable copies. Save derived configuration through normal workspace operations. Workspace artifacts belong in root dist/, including the preview at dist/preview/index.html; every resource they depend on must be packaged there. Channel packages come from platform export and never go in dist/. Private inputs and failed evidence stay outside dist/. A static model has no inferred opening capability.\n',
         'README.md': '# Saved-model adaptation project\n\nThis prepares source without installation, building, inference or acceptance. Install pinned dependencies and build normally. The workspace parameter panel edits scalar production values; structural mappings and arrays belong to the adaptation panel. Both save .playcraft/model-adaptation.json. Original source/ files and exact parent plan are retained. Runtime geometry identities are checked by the same core as the model viewer. Skin, animation, morph targets and instancing are unsupported; merged parts need a real split. Preview controls are temporary.\n',
+        ...provenanceFiles,
     };
     const adaptationPaths = Object.keys(files).filter(path => path.startsWith('src/') || path.startsWith('scripts/') ||
-        ['index.html', 'package.json', 'vite.config.mjs', '.playcraft/workspace.json', '.playcraft/model-adaptation.json', '.playcraft/model-adaptation-lineage.json'].includes(path));
+        ['index.html', 'package.json', 'vite.config.mjs', '.playcraft/workspace.json', '.playcraft/model-adaptation.json', '.playcraft/model-adaptation-lineage.json', ...Object.keys(provenanceFiles)].includes(path));
     if (derivedSource.files.length + adaptationPaths.length > 256 || adaptationPaths.length > 64)
         throw new Error('model_adaptation_build_input_bound');
     files['.playcraft/model-build-inputs.json'] = json({ schemaVersion: 1, models: [{ source: derivedSource, adaptationFiles: adaptationPaths.map(path => ({ path })) }] });

package/dist/workspace-runtime/batch/content-changes.js

@@ -1,8 +1,11 @@
+import { WORKSPACE_REMIX_REFERENCES_DIRECTORY } from '@playcraft/common/cloud-workspace/runtime';
 import { gitRead } from './git.js';
 const reference = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
 const excludedDirectories = new Set(['node_modules', 'dist', 'build', 'coverage', 'docs', 'test', 'tests', '__tests__']);
 const contentExtension = /\.(?:[cm]?[jt]sx?|vue|svelte|html?|css|s[ac]ss|less|json5?|ya?ml|xml|glsl|wgsl|vert|frag|lua|py|svg|png|jpe?g|webp|avif|gif|bmp|mp[34]|wav|ogg|m4a|webm|glb|gltf|fbx|obj|bin|atlas|woff2?|ttf|otf)$/i;
 function contentPath(path) {
+    if (path.startsWith(`${WORKSPACE_REMIX_REFERENCES_DIRECTORY}/`))
+        return false;
     const parts = path.split('/');
     if (parts.some(part => part.startsWith('.') || excludedDirectories.has(part)))
         return false;

package/dist/workspace-runtime/batch/freeze.js

@@ -10,6 +10,7 @@ import { assertSourceIdentity, readSourceCandidate, writeSourceCandidate } from
 import { BatchSourceFreezeError, sourceFreezeError } from './source-failure.js';
 import { publishSourceCandidate } from './source-publish.js';
 import { clearDirectoryFreeze, withDirectoryFreeze } from '../server/directory-access.js';
+import { adoptPublicationBinding, publicationBinding, publicationGitOptions } from './publication.js';
 async function usagePercent(path) {
     const disk = await statfs(path);
     if (disk.blocks <= 0)
@@ -32,9 +33,12 @@ export async function freezeBatchSource(state, body, options) {
     if (!parsed.success)
         throw new Error('invalid_batch_request');
     const request = parsed.data;
+    const leaseFence = state.acceptedLeaseFence;
     const frozen = await readSnapshot(state, request.batchId);
     if (frozen) {
         assertSourceIdentity(state, request, frozen, await readSourceCandidate(state, request.batchId));
+        if (request.publication)
+            await adoptPublicationBinding(state, request.workspaceId, request.sourceDirectoryName, request.publication, leaseFence);
         await clearDirectoryFreeze(state, request.batchId);
         return batchSourceFreezeResultSchema.parse({ status: 'frozen', snapshot: frozen });
     }
@@ -47,6 +51,8 @@ export async function freezeBatchSource(state, body, options) {
             const existing = await readSnapshot(state, request.batchId);
             if (existing) {
                 assertSourceIdentity(state, request, existing, pending);
+                if (request.publication)
+                    await adoptPublicationBinding(state, request.workspaceId, request.sourceDirectoryName, request.publication, leaseFence);
                 return batchSourceFreezeResultSchema.parse({ status: 'frozen', snapshot: existing });
             }
             if (!pending && 'resumeOnly' in request && request.resumeOnly === true) {
@@ -55,6 +61,12 @@ export async function freezeBatchSource(state, body, options) {
             if (pending)
                 assertSourceIdentity(state, request, pending.snapshot, pending);
             source = await workspaceRoot(state, request.workspaceId, request.sourceDirectoryName);
+            const binding = publicationBinding(state, request.workspaceId, request.sourceDirectoryName, request.publication);
+            if (request.publication) {
+                if (request.persist !== 'remote_ref')
+                    throw new Error('batch_source_identity_mismatch');
+                publicationGitOptions(state, request.publication);
+            }
             if (pending)
                 candidate = pending;
             else {
@@ -67,7 +79,6 @@ export async function freezeBatchSource(state, body, options) {
                 const captured = await captureIndependentSource(source, cache);
                 // private
                 await writeFile(`${cache}.digest`, captured.digest, { mode: 0o600 });
-                const binding = state.journal.getWorkspace(request.workspaceId);
                 const snapshot = {
                     batchId: request.batchId, commitHash: captured.commitHash, digest: captured.digest,
                     sourceWorkspaceId: request.workspaceId, sourceDirectoryName: request.sourceDirectoryName,
@@ -95,7 +106,9 @@ export async function freezeBatchSource(state, body, options) {
                 outcome: code === 'batch_source_identity_mismatch' || code === 'batch_source_snapshot_mismatch' ? 'unknown' : 'not_published',
             }, error);
         }
-        await publishSourceCandidate(state, candidate, source, options?.objectStore ?? filesystemObjectStore(state));
+        await publishSourceCandidate(state, candidate, source, options?.objectStore ?? filesystemObjectStore(state), request.publication);
+        if (request.publication)
+            await adoptPublicationBinding(state, request.workspaceId, request.sourceDirectoryName, request.publication, leaseFence);
         try {
             await writeSnapshot(state, candidate.snapshot);
         }

package/dist/workspace-runtime/batch/generate.js

@@ -100,7 +100,10 @@ export async function generateBatchMember(state, body) {
             const policy = memberExecutionPolicy(root, tempDir);
             await bindMemberPolicy(state, sessionId, policy, { runId: command.runId, ownerFence: command.ownerFence });
             const modelConfigId = command.model && /^[0-9a-f-]{36}$/i.test(command.model) ? command.model : undefined;
-            const turnPayload = { text: command.prompt, permissionMode: 'auto', ...(modelConfigId ? { modelConfigId } : {}) };
+            const turnPayload = { text: command.prompt, permissionMode: 'auto', ...(modelConfigId ? { modelConfigId } : {}),
+                ...(command.remixReferences?.length ? { context: { files: [], skills: [], remixReferences: command.remixReferences.map(reference => ({
+                            ...reference, directoryName: command.directoryName,
+                        })) } } : {}) };
             const turnKey = operation(state, { kind: 'session.turn', clientRequestId: `batch-turn:${command.runId}`, sessionId, workspaceId: command.workspaceId, directoryName: command.directoryName, payload: turnPayload });
             const prior = state.journal.getOperation(turnKey.scopeKey);
             if (prior && prior.payloadHash !== turnKey.record.payloadHash)

package/dist/workspace-runtime/batch/git.js

@@ -7,17 +7,18 @@ export async function gitRead(root, args) {
     return runGit(root, ['-c', 'credential.helper=', ...args]);
 }
 /** Push and fetch. Local credential helpers copied onto this repo stay in effect. */
-export async function gitWrite(root, args) {
-    return runGit(root, args);
+export async function gitWrite(root, args, options) {
+    return runGit(root, args, options);
 }
-async function runGit(root, args) {
+async function runGit(root, args, options) {
     const { stdout } = await execute('git', [
         '-c', 'core.hooksPath=/dev/null', '-c', 'init.templateDir=', '-c', 'core.fsmonitor=false', '-C', root, ...args,
     ], {
-        timeout: 90_000, maxBuffer: 64 * 1024 * 1024,
+        timeout: options?.timeout ?? 90_000, maxBuffer: 64 * 1024 * 1024,
         env: {
             PATH: process.env.PATH, HOME: dirname(root), GIT_OPTIONAL_LOCKS: '0',
             GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1', GIT_TERMINAL_PROMPT: '0',
+            ...options?.env,
         },
     });
     return stdout;
@@ -38,3 +39,14 @@ export async function copyCredentialHelpers(sourceRoot, destinationRoot) {
         await gitWrite(destinationRoot, ['config', '--local', key, value]);
     }
 }
+/** Remove helpers and URL rewrites copied by an older attempt before using trusted publication credentials. */
+export async function clearCredentialHelpers(root) {
+    const listed = await gitRead(root, ['config', '--local', '--name-only', '--get-regexp', '^(credential\\.|http\\.|url\\.)'])
+        .catch((error) => { if (error.code === 1)
+        return ''; throw error; });
+    for (const key of new Set(listed.split('\n').filter(Boolean))) {
+        if (!/^(credential\.|http\.|url\.)/i.test(key) || /[\r\n\0]/.test(key))
+            throw new Error('batch_source_git_config_invalid');
+        await gitWrite(root, ['config', '--local', '--unset-all', key]);
+    }
+}