abelien-harness 0.3.0 → 0.4.0

package/skills/abelien-harness/scripts/generate3d-host.mjs

@@ -0,0 +1,398 @@
+// Trusted host library only. F4 remains authoritative for authorization, lease,
+// accounting and adoption. This module binds that invocation to one provider send.
+import fs from 'node:fs';
+import path from 'node:path';
+import { canonicalJson, createStore, fail, sha256Hex } from './ab.mjs';
+import {
+  assertVerified, effectiveSubmit, loadProfiles, resolveCredential, submitFlow,
+  statusFlow, artifactLocation, downloadArtifact, validateGlb,
+} from './generate3d.mjs';
+
+export const HOSTED_GENERATION_PROTOCOL = 1;
+export const HOSTED_GENERATION_AUTHORITY_PROTOCOL = 1;
+export const HOSTED_GENERATION_QUALIFICATION_PROTOCOL = 1;
+const HASH = /^[a-f0-9]{64}$/;
+const DEFAULT_MAX_ARTIFACT_BYTES = 128 * 1024 * 1024;
+const MAX_IMAGE_BYTES = 20 * 1024 * 1024;
+const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.webp']);
+const SAFE_ERROR_CODES = new Set([
+  'UPLOAD_FAILED', 'HTTP_FAILED', 'HTTP_STATUS', 'TASK_FAILED', 'TASK_PENDING',
+  'CREDENTIAL_MISSING', 'DOWNLOAD_FAILED', 'ZIP_INVALID', 'GLB_INVALID',
+  'GENERATION_ABORTED', 'GENERATION_PROFILE_DRIFT', 'ARTIFACT_HASH_MISMATCH',
+  'GENERATION_AUTHORITY_STALE',
+  'GENERATION_QUALIFICATION_INVALID',
+]);
+
+function cleanError(error) {
+  const code = SAFE_ERROR_CODES.has(error?.code) ? error.code : 'GENERATION_IO_FAILED';
+  return fail(code, `Hosted generation failed: ${code}`);
+}
+
+function diagnostic(deps, phase, identity, error) {
+  if (typeof deps.onDiagnostic !== 'function') return;
+  const redact = value => {
+    let text = String(value ?? '').slice(0, 32_768);
+    for (const secret of Object.values(deps.env ?? {})) {
+      if (typeof secret === 'string' && secret.length >= 6) text = text.split(secret).join('[redacted]');
+    }
+    return text.replace(/https?:\/\/[^\s"'<>]+/gi, '[redacted-url]')
+      .replace(/Bearer\s+[^\s"',}]+/gi, 'Bearer [redacted]');
+  };
+  try {
+    const event = {phase, requestId: identity.requestId, inputDigest: identity.inputDigest,
+      error: {code: cleanError(error).code, message: redact(error?.message),
+        stack: redact(error?.stack), details: redact(JSON.stringify(error?.details ?? null))}};
+    // Private trusted observer only. Public results and gen3d resources remain code-only.
+    const result = deps.onDiagnostic(event);
+    result?.catch?.(() => {});
+  } catch { /* Observability failure cannot change paid execution/recovery. */ }
+}
+
+function hostDeps(deps) {
+  if (!deps || typeof deps.workdir !== 'string' || !path.isAbsolute(deps.workdir)) {
+    throw fail('GENERATION_INPUT_INVALID', 'Host workdir must be an absolute private invocation directory');
+  }
+  const maxArtifactBytes = deps.maxArtifactBytes ?? DEFAULT_MAX_ARTIFACT_BYTES;
+  if (!Number.isSafeInteger(maxArtifactBytes) || maxArtifactBytes < 1 || maxArtifactBytes > DEFAULT_MAX_ARTIFACT_BYTES) {
+    throw fail('GENERATION_INPUT_INVALID', 'Invalid artifact byte limit');
+  }
+  const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
+  return {
+    workdir: deps.workdir, env: deps.env ?? {}, credentialPolicy: 'env-only',
+    requireGlb: true, maxArtifactBytes, signal: deps.signal,
+    fetchImpl: async (url, init = {}) => {
+      if (deps.signal?.aborted) throw fail('GENERATION_ABORTED', 'Generation interrupted');
+      // The host must apply its outbound origin/DNS policy in fetchImpl.
+      // No credential-bearing redirects, including signed artifact downloads.
+      return fetchImpl(url, {...init, redirect: 'error'});
+    },
+  };
+}
+
+/** Offline profile information, not a price quote or an authorization. */
+function modelInfo(profiles, {provider, model: modelId}) {
+  const profile = profiles[provider];
+  if (!profile) throw fail('PROVIDER_NOT_FOUND', 'Provider not found');
+  const model = profile.models[modelId];
+  if (!model || model.available === false) throw fail('MODEL_NOT_FOUND', 'Model not available');
+  const configuration = {
+    provider, model: modelId, transport: profile.transport,
+    input: model.input, imageEncoding: profile.imageEncoding,
+    images: profile.images ?? null, upload: profile.upload ?? null,
+    submit: effectiveSubmit(profile, model), poll: model.poll ?? profile.poll,
+    download: profile.download,
+  };
+  return {
+    provider, model: modelId, input: model.input,
+    verified: model.verified ?? profile.verified,
+    estCostUsd: model.benchmark?.usd ?? null, historicalEstimate: true,
+    profileDigest: sha256Hex(canonicalJson(configuration)), providerIdempotency: false,
+  };
+}
+
+export function inspectHostedModel(deps, identity) {
+  return modelInfo(loadProfiles(hostDeps(deps)), identity);
+}
+function freezeSnapshot(value) {
+  if (value && typeof value === 'object') {
+    for (const child of Object.values(value)) freezeSnapshot(child);
+    Object.freeze(value);
+  }
+  return value;
+}
+
+// An operator qualification is a trusted module dependency, never a model input,
+// generic CLI flag or environment bypass. The controller verifies the immutable
+// loaded release and supplies its digest independently of the manifest. Existing
+// request claims remain the sole send ledger; this admits exactly that request.
+function qualificationAdmission(deps, request, model, images) {
+  if (deps.qualification === undefined) return null;
+  const manifest = deps.qualification?.manifest;
+  const keys = ['schemaVersion', 'purpose', 'requestId', 'inputDigest', 'provider', 'model',
+    'profileDigest', 'imageSha256', 'releaseDigest', 'expiresAt', 'maxCreates', 'maxCredits'];
+  const invalid = () => { throw fail('GENERATION_QUALIFICATION_INVALID', 'Exact trusted qualification admission is required'); };
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)
+    || Object.keys(manifest).sort().join('|') !== keys.sort().join('|')) invalid();
+  if (manifest.schemaVersion !== 1 || manifest.purpose !== 'provider_qualification'
+    || manifest.requestId !== request.requestId || manifest.inputDigest !== request.inputDigest
+    || manifest.provider !== model.provider || manifest.model !== model.model
+    || manifest.profileDigest !== model.profileDigest || !HASH.test(manifest.releaseDigest ?? '')
+    || manifest.releaseDigest !== deps.qualification.releaseDigest
+    || !Array.isArray(manifest.imageSha256)
+    || canonicalJson(manifest.imageSha256) !== canonicalJson(images.map(image => image.sha256))
+    || manifest.maxCreates !== 1 || !Number.isSafeInteger(manifest.maxCredits) || manifest.maxCredits <= 0) invalid();
+  const expires = Date.parse(manifest.expiresAt);
+  if (!Number.isFinite(expires) || new Date(expires).toISOString() !== manifest.expiresAt
+    || expires <= (deps.now?.() ?? Date.now())) invalid();
+  const snapshot = freezeSnapshot(JSON.parse(JSON.stringify(manifest)));
+  return {manifest: snapshot, manifestDigest: sha256Hex(canonicalJson(snapshot))};
+}
+
+function identityPaths(deps, {requestId, inputDigest}) {
+  if (typeof requestId !== 'string' || !requestId.trim() || requestId.length > 512 ||
+      typeof inputDigest !== 'string' || !HASH.test(inputDigest)) {
+    throw fail('GENERATION_INPUT_INVALID', 'An exact invocation requestId and SHA-256 inputDigest are required');
+  }
+  const key = sha256Hex(requestId);
+  const localId = `g3d-host-${key}`;
+  return {
+    requestId, inputDigest, localId, id: `gen3d:${localId}`,
+    claim: path.join(deps.workdir, '.abelien', 'gen3d-send-claims', `${key}.json`),
+  };
+}
+
+function readClaim(paths) {
+  try {
+    const claim = JSON.parse(fs.readFileSync(paths.claim, 'utf8'));
+    if (claim.hosted?.requestId !== paths.requestId || claim.hosted.inputDigest !== paths.inputDigest) {
+      throw fail('GENERATION_IDENTITY_CONFLICT', 'Invocation identity does not match the original request');
+    }
+    if (claim.hosted.protocol !== HOSTED_GENERATION_PROTOCOL || !HASH.test(claim.hosted.requestDigest)) {
+      throw fail('GENERATION_STATE_UNREADABLE', 'Submission claim cannot be verified; do not resubmit');
+    }
+    return claim;
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    if (error?.code?.startsWith('GENERATION_')) throw error;
+    throw fail('GENERATION_STATE_UNREADABLE', 'Submission claim cannot be read; do not resubmit');
+  }
+}
+
+function readBody(deps, paths, claim) {
+  if (!claim) return null;
+  const index = path.join(deps.workdir, '.abelien', 'store', 'index.json');
+  const body = fs.existsSync(index) ? createStore(deps.workdir).get(paths.id)?.body : null;
+  if (body && (body.hosted?.requestDigest !== claim.hosted.requestDigest ||
+      body.hosted?.inputDigest !== paths.inputDigest || body.hosted?.requestId !== paths.requestId)) {
+    throw fail('GENERATION_IDENTITY_CONFLICT', 'Stored resource does not match submission claim');
+  }
+  // A crash after exclusive claim and before store persistence is ambiguous. The
+  // immutable claim is sufficient to prohibit another send, never to prove success.
+  return body ?? claim;
+}
+
+function publicResult(paths, body) {
+  const status = body.status;
+  return {
+    id: paths.id, requestId: paths.requestId, inputDigest: paths.inputDigest,
+    requestDigest: body.hosted.requestDigest, profileDigest: body.hosted.profileDigest,
+    provider: body.provider, model: body.model, status,
+    ...(body.providerTaskId ? {providerTaskId: body.providerTaskId} : {}),
+    recovery: body.providerTaskId ? 'poll' : status === 'failed' ? 'none' : 'unknown',
+    providerIdempotency: false,
+    ...(body.errorCode ? {errorCode: body.errorCode} : {}),
+    ...(body.artifact ? {artifact: body.artifact} : {}),
+  };
+}
+
+/** No provider call and no credential read. Null means never claimed here. */
+export function lookupHostedGeneration(deps, identity) {
+  const trusted = hostDeps(deps), paths = identityPaths(trusted, identity);
+  const body = readBody(trusted, paths, readClaim(paths));
+  return body ? publicResult(paths, body) : null;
+}
+
+function claimExclusive(file, value) {
+  fs.mkdirSync(path.dirname(file), {recursive: true, mode: 0o700});
+  const tmpDir = fs.mkdtempSync(path.join(path.dirname(file), '.claim-'));
+  const tmp = path.join(tmpDir, 'claim.json');
+  try {
+    const fd = fs.openSync(tmp, 'wx', 0o600);
+    try { fs.writeFileSync(fd, canonicalJson(value)); fs.fsyncSync(fd); }
+    finally { fs.closeSync(fd); }
+    // Atomic no-replace publication: readers never observe a half-written claim.
+    try { fs.linkSync(tmp, file); }
+    catch (error) { if (error.code === 'EEXIST') return false; throw error; }
+    const dir = fs.openSync(path.dirname(file), 'r');
+    try { fs.fsyncSync(dir); } finally { fs.closeSync(dir); }
+    return true;
+  } finally { fs.rmSync(tmpDir, {recursive: true, force: true}); }
+}
+
+/** Exactly one paid send per requestId. Calling again only reads the original result. */
+export async function submitHostedGeneration(deps, request) {
+  const trusted = hostDeps(deps), paths = identityPaths(trusted, request);
+  const oldClaim = readClaim(paths);
+  if (oldClaim && (oldClaim.provider !== request.provider || oldClaim.model !== request.model)) {
+    throw fail('GENERATION_IDENTITY_CONFLICT', 'Provider/model changed for the same invocation');
+  }
+  trusted.profileSnapshot = freezeSnapshot(loadProfiles(trusted));
+  const model = modelInfo(trusted.profileSnapshot, request);
+  if (!Array.isArray(request.images) || request.images.length !== model.input.count) {
+    throw fail('IMAGE_COUNT', 'Image count does not match the selected model');
+  }
+  const prompt = request.prompt;
+  if (prompt !== undefined && typeof prompt !== 'string') throw fail('GENERATION_INPUT_INVALID', 'Prompt must be a string');
+  const requestDigestOf = sources => sha256Hex(canonicalJson({
+    requestId: paths.requestId, inputDigest: paths.inputDigest,
+    provider: request.provider, model: request.model, profileDigest: model.profileDigest,
+    images: sources.map(source => ({view: source.view, sha256: source.sha256, bytes: source.bytes})),
+    promptDigest: prompt === undefined ? null : sha256Hex(prompt),
+  }));
+  if (oldClaim) {
+    // Repeat submit: the immutable claim already records each source digest and byte
+    // length, so the original request digest is recomputable without re-reading the
+    // source files. Recovery must not depend on the host still holding them, and
+    // nothing on this path can dispatch a second paid send.
+    const recorded = Array.isArray(oldClaim.images) ? oldClaim.images : null;
+    const replayed = recorded !== null && recorded.length === request.images.length
+      && recorded.every((source, index) => source?.view === model.input.views[index]
+        && source?.sha256 === request.images[index]?.sha256
+        && Number.isSafeInteger(source?.bytes) && source.bytes >= 0);
+    if (!replayed || requestDigestOf(recorded) !== oldClaim.hosted.requestDigest) {
+      throw fail('GENERATION_IDENTITY_CONFLICT', 'Request content changed');
+    }
+    return publicResult(paths, readBody(trusted, paths, oldClaim));
+  }
+  const images = request.images.map((image, index) => {
+    if (!image || typeof image.path !== 'string' || !path.isAbsolute(image.path) ||
+        !HASH.test(image.sha256 ?? '') || !IMAGE_EXTENSIONS.has(path.extname(image.path).toLowerCase())) {
+      throw fail('GENERATION_INPUT_INVALID', 'Images require private absolute paths and SHA-256 hashes');
+    }
+    let bytes;
+    try {
+      if (fs.statSync(image.path).size > MAX_IMAGE_BYTES) throw Error('too large');
+      bytes = fs.readFileSync(image.path);
+    } catch { throw fail('IMAGE_READ', 'Image could not be read within the size limit'); }
+    if (bytes.length > MAX_IMAGE_BYTES) throw fail('IMAGE_READ', 'Image exceeds byte limit');
+    if (sha256Hex(bytes) !== image.sha256) throw fail('IMAGE_HASH_MISMATCH', 'Source image changed');
+    return {bytes, sha256: image.sha256, view: model.input.views[index], extension: path.extname(image.path).toLowerCase()};
+  });
+  const requestDigest = requestDigestOf(images.map(image => ({view: image.view, sha256: image.sha256, bytes: image.bytes.length})));
+  if (request.confirmSpend !== true) throw fail('SPEND_CONFIRM_REQUIRED', 'Host must confirm existing spend authorization');
+  if (typeof deps.beforePaidSubmit !== 'function') throw fail('GENERATION_AUTHORITY_REQUIRED', 'Trusted final paid authority callback is required');
+  const qualification = qualificationAdmission(deps, request, model, images);
+  if (!qualification) assertVerified({...model, name: model.provider}, false, `model ${model.provider}/${model.model}`);
+  // Never mutate the installed catalog or borrow its provider-level verification.
+  // Only this frozen engine call receives the operator's exact admission.
+  const submitProfileSnapshot = qualification ? freezeSnapshot({
+    ...trusted.profileSnapshot,
+    [request.provider]: {...trusted.profileSnapshot[request.provider], models: {
+      ...trusted.profileSnapshot[request.provider].models,
+      [request.model]: {...trusted.profileSnapshot[request.provider].models[request.model], verified: true},
+    }},
+  }) : trusted.profileSnapshot;
+  if (deps.signal?.aborted) throw fail('GENERATION_ABORTED', 'Generation interrupted before dispatch');
+  const profile = trusted.profileSnapshot[request.provider];
+  if (!resolveCredential(trusted, profile).value) throw fail('CREDENTIAL_MISSING', 'Explicit host credential is missing');
+
+  // Freeze bytes before any await/upload. Source paths can later change without
+  // changing the paid request or its persisted image identities.
+  const inputRoot = path.join(trusted.workdir, '.abelien', 'gen3d-inputs');
+  fs.mkdirSync(inputRoot, {recursive: true, mode: 0o700});
+  const inputDir = fs.mkdtempSync(path.join(inputRoot, 'input-'));
+  const files = images.map((image, index) => {
+    const file = path.join(inputDir, `${index}${image.extension}`);
+    fs.writeFileSync(file, image.bytes, {mode: 0o400}); return file;
+  });
+  const flags = {image: files, ...(prompt === undefined ? {} : {prompt}), 'confirm-spend': true};
+  let claimed = false, sent = false;
+  try {
+    // Exact existing engine validation, including unsupported prompt and templates,
+    // before irrevocably claiming this invocation.
+    await submitFlow(trusted, {provider: request.provider, model: request.model, flags: {...flags, 'dry-run': true}});
+    if (deps.signal?.aborted) throw fail('GENERATION_ABORTED', 'Generation interrupted before dispatch');
+    const now = new Date().toISOString();
+    const initial = {
+      provider: request.provider, model: request.model, transport: 'rest', status: 'unknown',
+      images: images.map((image,index) => ({path: files[index], view: image.view, sha256: image.sha256, bytes: image.bytes.length})),
+      submitAt: now, updatedAt: now,
+      hosted: {protocol: HOSTED_GENERATION_PROTOCOL, requestId: paths.requestId, inputDigest: paths.inputDigest,
+        requestDigest, profileDigest: model.profileDigest, ...(qualification ? {qualification} : {})},
+    };
+    claimed = claimExclusive(paths.claim, initial);
+    if (!claimed) {
+      const claim = readClaim(paths);
+      if (claim.hosted.requestDigest !== requestDigest) throw fail('GENERATION_IDENTITY_CONFLICT', 'Concurrent request content changed');
+      return publicResult(paths, readBody(trusted, paths, claim));
+    }
+    const store = createStore(trusted.workdir);
+    store.put('gen3d', paths.localId, initial);
+    try {
+      await submitFlow({...trusted,
+        profileSnapshot: submitProfileSnapshot,
+        beforeSubmit: async () => {
+          if (deps.signal?.aborted) throw fail('GENERATION_ABORTED', 'Generation interrupted before dispatch');
+          // Uploads can be slow. The trusted F4 host must recheck the original
+          // lease/fence, baseline and cancellation immediately before paid send.
+          try { await deps.beforePaidSubmit?.(); }
+          catch (error) {
+            diagnostic(deps, 'authority', paths, error);
+            throw fail('GENERATION_AUTHORITY_STALE', 'Original paid authorization is no longer current');
+          }
+          if (deps.signal?.aborted) throw fail('GENERATION_ABORTED', 'Generation interrupted before dispatch');
+          if (qualification) qualificationAdmission({...deps, qualification: {
+            manifest: qualification.manifest, releaseDigest: qualification.manifest.releaseDigest,
+          }}, request, model, images);
+          sent = true;
+          store.put('gen3d', paths.localId, {...initial, sendStartedAt: new Date().toISOString()});
+        },
+        store: {
+          put(kind, _localId, body) {
+            if (kind !== 'gen3d') throw fail('GENERATION_IDENTITY_CONFLICT', 'Unexpected resource kind');
+            if (typeof body.providerTaskId !== 'string' || !/^[A-Za-z0-9_.:-]{1,256}$/.test(body.providerTaskId)) {
+              throw fail('TASK_FAILED', 'Provider returned an invalid task identity');
+            }
+            return store.put(kind, paths.localId, {...body, hosted: initial.hosted});
+          },
+        },
+      }, {provider: request.provider, model: request.model, flags});
+    } catch (error) {
+      diagnostic(deps, sent ? 'submit' : 'prepare', paths, error);
+      // Errors after dispatch (including malformed success) cannot prove no charge.
+      // A known persisted provider ID must never be discarded by an error path.
+      const current = store.get(paths.id)?.body;
+      if (!current?.providerTaskId) store.put('gen3d', paths.localId, {
+        ...initial, status: sent ? 'unknown' : 'failed', errorCode: cleanError(error).code,
+        updatedAt: new Date().toISOString(),
+      });
+    }
+    return publicResult(paths, readBody(trusted, paths, initial));
+  } finally {
+    if (!claimed) fs.rmSync(inputDir, {recursive: true, force: true});
+  }
+}
+
+function storedContext(deps, identity) {
+  const trusted = hostDeps(deps), paths = identityPaths(trusted, identity);
+  const body = readBody(trusted, paths, readClaim(paths));
+  if (!body) throw fail('RESOURCE_NOT_FOUND', 'Hosted generation was not submitted');
+  trusted.profileSnapshot = freezeSnapshot(loadProfiles(trusted));
+  const model = modelInfo(trusted.profileSnapshot, body);
+  if (model.profileDigest !== body.hosted.profileDigest) throw fail('GENERATION_PROFILE_DRIFT', 'Provider configuration changed; reconcile original request');
+  return {trusted, paths, body};
+}
+
+/** At most one status operation. Unknown requests with no task ID stay offline. */
+export async function statusHostedGeneration(deps, identity) {
+  const {trusted, paths, body} = storedContext(deps, identity);
+  if (!body.providerTaskId || body.status === 'succeeded' || body.status === 'failed') return publicResult(paths, body);
+  try { await statusFlow(trusted, {id: paths.id}); } catch (error) {
+    diagnostic(deps, 'status', paths, error); throw cleanError(error);
+  }
+  return lookupHostedGeneration(trusted, identity);
+}
+
+/** Only fetch a known successful task; never a waiting loop or a new submit. */
+export async function fetchHostedGeneration(deps, identity) {
+  const {trusted, paths, body} = storedContext(deps, identity);
+  if (!body.providerTaskId || body.status !== 'succeeded') throw fail('TASK_PENDING', 'Artifact is not ready; use status with the original request');
+  if (body.artifact) {
+    let bytes;
+    try { bytes = fs.readFileSync(body.artifact.path); } catch { throw fail('ARTIFACT_HASH_MISMATCH', 'Persisted artifact is missing'); }
+    if (bytes.length !== body.artifact.bytes || sha256Hex(bytes) !== body.artifact.sha256) {
+      throw fail('ARTIFACT_HASH_MISMATCH', 'Persisted artifact changed');
+    }
+    validateGlb(bytes);
+    return publicResult(paths, body);
+  }
+  try {
+    const {url, download} = await artifactLocation(trusted, {id: paths.id});
+    const artifact = await downloadArtifact(trusted, {download}, url,
+      path.join(trusted.workdir, '.abelien', 'artifacts', 'gen3d', paths.localId), paths.localId);
+    const store = createStore(trusted.workdir);
+    const current = store.get(paths.id).body;
+    store.put('gen3d', paths.localId, {...current, artifact, status: 'succeeded', updatedAt: new Date().toISOString()});
+    return lookupHostedGeneration(trusted, identity);
+  } catch (error) { diagnostic(deps, 'fetch', paths, error); throw cleanError(error); }
+}

package/skills/abelien-harness/scripts/generate3d.mjs

@@ -126,6 +126,10 @@ export function validateProfile(p) {
 // （mock baseUrl 等），CLI 不暴露；校验先于合并（override 可放松 https 钉子指向 http mock），
 // 指向未知名显式 PROVIDER_NOT_FOUND（拒绝静默吞掉测试笔误）。
 export function loadProfiles(deps) {
+  // Trusted host-only port: the exact verified configuration snapshot is used for
+  // preflight, upload, paid submit and subsequent reads within this operation.
+  // No CLI flag or environment setting exposes this port.
+  if (deps?.profileSnapshot) return deps.profileSnapshot;
   const domain = discoverDomains({ workdir: deps.workdir }).find(d => d.name === DOMAIN_NAME);
   if (!domain) throw fail("PROVIDER_NOT_FOUND", `domain pack ${DOMAIN_NAME} not discovered`, { domain: DOMAIN_NAME });
   const dir = path.join(domain.dir, "providers");
@@ -514,27 +518,62 @@ export function unzipPick(zipBuf, pickRe, destPath, options = {}) {
 }
 
 // downloadArtifact——产物下载落盘（Task 8）：GET 签名 URL（fetchImpl 可注入，测试零网络），
-// 60s 超时（AbortController）；非 2xx / 网络失败 / 超时一律 DOWNLOAD_FAILED（非 2xx 附
-// status）。落盘恒 destDir/model.glb：binary 直接原子写；zip/auto 先嗅探（Content-Type 含
+// 60s 超时（AbortController）；非 2xx / 网络失败 / 超时 / 3xx 一律 DOWNLOAD_FAILED（非 2xx 附
+// status）。**签名 URL 一律不跟随重定向**（`redirect:'error'`，与 restJson/uploadImages 同款）：
+// 产物地址是 provider 给的带签名链接，跟随 302 就等于把凭据送到未受信主机；这条对 CLI 的
+// `ab generate 3d fetch` 与宿主 API 一并生效（宿主面本就在 hostDeps 强制，此处补齐内核面）。
+// 落盘恒 destDir/model.glb：binary 直接原子写；zip/auto 先嗅探（Content-Type 含
 // zip 或字节头 PK\x03\x04）走 unzipPick 挑 glb 条目。返回 {file, path, sha256, bytes}——
 // spec 红线：签名 URL 永不进入返回值或落盘内容，只存在于调用栈；错误消息同样 redact
 // （T8 遗留收口：URL 不进 message/details，诊断靠 details.status / details.reason）。
+// Keep the host cancellation signal attached until the entire response body is read.
+function requestAbort(deps, timeoutMs) {
+  const ac = new AbortController();
+  const abort = () => ac.abort();
+  if (deps.signal?.aborted) ac.abort();
+  deps.signal?.addEventListener('abort', abort, { once: true });
+  const timer = setTimeout(abort, timeoutMs);
+  return {
+    signal: ac.signal,
+    close() { clearTimeout(timer); deps.signal?.removeEventListener('abort', abort); },
+  };
+}
+
+async function artifactBytes(deps, res) {
+  if (deps.credentialPolicy !== 'env-only') return Buffer.from(await res.arrayBuffer());
+  const limit = deps.maxArtifactBytes;
+  const advertised = Number(res.headers?.get?.('content-length'));
+  if (Number.isFinite(advertised) && advertised > limit) throw fail('DOWNLOAD_FAILED', 'Artifact exceeds host budget');
+  const reader = res.body?.getReader();
+  if (!reader) throw fail('DOWNLOAD_FAILED', 'Hosted artifact response must be bounded');
+  const chunks = []; let size = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.length;
+      if (size > limit) throw fail('DOWNLOAD_FAILED', 'Artifact exceeds host budget');
+      chunks.push(value);
+    }
+  } finally { await reader.cancel().catch(() => {}); reader.releaseLock(); }
+  return Buffer.concat(chunks);
+}
+
 export async function downloadArtifact(deps, profile, url, destDir, localId) {
   const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
-  const ac = new AbortController();
-  const timer = setTimeout(() => ac.abort(), 60000);
+  const request = requestAbort(deps, 60000);
   let res;
   let body;
   try {
-    res = await fetchImpl(url, { method: "GET", signal: ac.signal });
+    res = await fetchImpl(url, { method: "GET", signal: request.signal, redirect: 'error' });
     if (!res.ok) throw fail("DOWNLOAD_FAILED", `下载失败: HTTP ${res.status}`, { status: res.status });
-    body = Buffer.from(await res.arrayBuffer());
+    body = await artifactBytes(deps, res);
     if (deps.maxArtifactBytes !== undefined && body.length > deps.maxArtifactBytes) throw fail('DOWNLOAD_FAILED', 'Artifact exceeds host budget');
   } catch (e) {
     if (e?.code === "DOWNLOAD_FAILED") throw e;   // 非 2xx 已带 status，不二次包裹
     throw fail("DOWNLOAD_FAILED", "下载失败（签名 URL 已隐去）", { reason: String(e?.cause?.message ?? e?.message ?? e).slice(0, 200) });
   } finally {
-    clearTimeout(timer);
+    request.close();
   }
   // mkdir -p 语义自裁（Task 12 离线段 A）：目录不可创建（父路径被文件占据等）也是
   // 下载失败的一部分——收口 DOWNLOAD_FAILED 家族，消息只含本地落点、绝无签名 URL。
@@ -661,11 +700,10 @@ export async function restJson(deps, profile, { method = "GET", url, body, key,
   const headers = { "content-type": "application/json", authorization: `Bearer ${key}` };
   let lastErr;
   for (let attempt = 0; attempt <= retries; attempt++) {
-    const ac = new AbortController();
-    const timer = setTimeout(() => ac.abort(), timeoutMs);
+    const request = requestAbort(deps, timeoutMs);
     try {
       const res = await fetchImpl(url, {
-        method, headers, signal: ac.signal, redirect: 'error',
+        method, headers, signal: request.signal, redirect: 'error',
         ...(body !== undefined ? { body } : {}),   // GET 零 body（undici 拒绝 GET/HEAD body）
       });
       if (!res.ok) {
@@ -683,8 +721,9 @@ export async function restJson(deps, profile, { method = "GET", url, body, key,
       if (e?.code === "HTTP_STATUS") throw e;
       lastErr = e;   // 网络错/超时/响应体非 JSON → 重试
     } finally {
-      clearTimeout(timer);
+      request.close();
     }
+    if (deps.signal?.aborted) break;
   }
   if (lastErr?.code === "HTTP_STATUS") {   // 5xx 耗尽：保 HTTP_FAILED 码，status 仍可诊断
     throw fail("HTTP_FAILED", `rest 请求失败: ${lastErr.message}`, { status: lastErr.details.status });
@@ -718,19 +757,18 @@ async function uploadImages(deps, profile, key, files) {
     }
     const form = new FormData();
     form.append("file", new Blob([raw], { type: mime }), path.basename(file));
-    const ac = new AbortController();
-    const timer = setTimeout(() => ac.abort(), 30000);
+    const request = requestAbort(deps, 30000);
     let res,text;
     try {
       res = await fetchImpl(profile.transport.baseUrl + upath, {
-        method, headers: { authorization: `Bearer ${key}` }, body: form, signal: ac.signal, redirect: 'error',
+        method, headers: { authorization: `Bearer ${key}` }, body: form, signal: request.signal, redirect: 'error',
       });
       text=await providerText(deps,res);
     } catch (e) {
       throw fail("UPLOAD_FAILED", `图片上传失败（网络错）: ${file}`,
         { index: i, reason: String(e?.cause?.message ?? e?.message ?? e).slice(0, 200) });
     } finally {
-      clearTimeout(timer);
+      request.close();
     }
     if (!res.ok) {
       throw fail("UPLOAD_FAILED", `图片上传失败: HTTP ${res.status}`,
@@ -856,6 +894,7 @@ export async function submitFlow(deps, { provider, model: modelId, flags = {} })
   // upload 节（T12 在线段 1c）：双闸通过后、submit 请求前逐图上传换 token——
   // Authorization 同源（上方同一凭证解析的 key）；失败即 UPLOAD_FAILED 中断（零花费）。
   if (profile.upload) tokenByFile = await uploadImages(deps, profile, key, imgCtx.views.map(([, f]) => f));
+  await deps.beforeSubmit?.(); // Trusted host persists the one-send claim before the paid request.
   const raw = await restJson(deps, profile, {
     method: plan.request.method, url: plan.request.url, key,
     body: canonicalJson(buildBody(bodyTemplate, realCtx)),

package/skills/abelien-harness/scripts/receipt.mjs

@@ -16,7 +16,9 @@ const SAFE_RUN_RE = /^[0-9A-Za-z][0-9A-Za-z._-]{0,255}$/;
 const SYMBOL_RE = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/;
 const TERMINAL_WORKFLOW_STATES = new Set(["done", "failed", "cancelled"]);
 const ALLOWED_CHANGES = new Set(["geometry", "transform", "interfaces", "appearance_mapping", "material"]);
-const STEP_KEYS = new Set(["appearance.generate", "cad.initial", "cad.revision", "cad.repair", "cad.final", "visual.review"]);
+const STEP_KEYS = new Set(["appearance.generate", "appearance.revision", "mesh.generate", "structure.adapt",
+  "cad.initial", "cad.revision", "cad.repair", "cad.final", "visual.review"]);
+const APPEARANCE_PARENT_STEPS = new Set(["appearance.revision", "mesh.generate", "structure.adapt"]);
 
 function invalid(message, details) {
   throw fail("RECEIPT_INVALID", message, details);
@@ -237,6 +239,9 @@ export function parseStudioReceiptEnvelope(value) {
   exactKeys(step, ["stepKey", "parentCandidateId", "repairOrdinal", "repairBasis"], "receipt.step");
   if (typeof step.stepKey !== "string" || !STEP_KEYS.has(step.stepKey)) invalid("receipt.step.stepKey is invalid");
   if (step.parentCandidateId !== null) uuid(step.parentCandidateId, "receipt.step.parentCandidateId");
+  if (APPEARANCE_PARENT_STEPS.has(step.stepKey) && step.parentCandidateId === null) {
+    invalid("appearance and engineering receipts require their immutable parent candidate");
+  }
   if (step.stepKey === "cad.final" && (!creationLineage || step.parentCandidateId === null)) {
     invalid("cad.final requires creation lineage and the reviewed preview parent");
   }
@@ -499,7 +504,8 @@ function inspectWorkflow(workdir, envelope) {
     instanceDigest: crypto.createHash("sha256").update(bytes).digest("hex"),
     validatedFields: [...validated].sort(),
     waitIdentityVerified: ["waitId", "workflowInstanceId", operationField, "localRunId", "remoteRunId", "invocationId",
-      ...(envelope.step.stepKey === "cad.final" ? ["definitionDigest", "stepKey", "parentCandidateId"] : [])]
+      ...(envelope.step.stepKey === "cad.final" || APPEARANCE_PARENT_STEPS.has(envelope.step.stepKey)
+        ? ["definitionDigest", "stepKey", "parentCandidateId"] : [])]
       .every(field => validated.has(field)),
     resumeDisposition,
   };

package/skills/abelien-harness/scripts/studio.mjs

@@ -3,7 +3,7 @@
 // model input can never select either value.
 import fs from "node:fs";
 
-export const STUDIO_CONTEXT_FILE = "/tmp/abelien-runtime-delegation/current.json";
+export const STUDIO_CONTEXT_FILE = "/home/agent/workspace/abelien-runtime-delegation/current.json";
 
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const DIGEST = /^[0-9a-f]{64}$/;
@@ -188,6 +188,16 @@ function validateModificationRequest(value) {
   jsonSize(input, "modification input");
   return input;
 }
+// Transport identities only; immutable definitions and full tool schemas remain
+// broker-owned. Do not grant v2 to every tool when adding CAD adaptation.
+function validateToolIdentity(value) {
+  const tool = record(value, "tool input");
+  const v1 = ["model.complete", "hardware.edit", "image.generate", "cad.build", "visual.review", "mesh.generate"];
+  if (!(tool.version === 1 && v1.includes(tool.tool))
+    && !(tool.version === 2 && tool.tool === "cad.build" && tool.purpose === "appearance_adaptation")) {
+    throw fail("STUDIO_INVALID", "tool input identity is invalid");
+  }
+}
 function validateToolOperationRequest(value) {
   const input = exact(value, ["schemaVersion", "commandId", "stepKey", "parentCandidateId",
     "repairBasis", "effectIdentity", "effectRequestDigest", "waits", "input"],
@@ -214,10 +224,7 @@ function validateToolOperationRequest(value) {
     text(repair.reportDigest, "reportDigest", DIGEST, 64);
     sortedUniqueStrings(repair.issueCodes, "issueCodes", 64);
   }
-  const tool = record(input.input, "tool input");
-  if (!["model.complete", "hardware.edit", "image.generate", "cad.build", "visual.review"].includes(tool.tool) || tool.version !== 1) {
-    throw fail("STUDIO_INVALID", "tool input identity is invalid");
-  }
+  validateToolIdentity(input.input);
   noForbiddenKeys(input);
   jsonSize(input, "tool operation input");
   return input;
@@ -244,10 +251,7 @@ function validateInvocationRequest(value) {
   if (input.schemaVersion !== 1) throw fail("STUDIO_INVALID", "invocation schemaVersion must be 1");
   text(input.operationId, "operationId", UUID, 36);
   text(input.callSlot, "callSlot", IDENTIFIER, 128);
-  const tool = record(input.input, "tool input");
-  if (!["model.complete", "hardware.edit", "image.generate", "cad.build", "visual.review"].includes(tool.tool) || tool.version !== 1) {
-    throw fail("STUDIO_INVALID", "tool input identity is invalid");
-  }
+  validateToolIdentity(input.input);
   noForbiddenKeys(input);
   jsonSize(input, "invocation input");
   return input;
@@ -352,10 +356,14 @@ function safeSuccess(kind, value) {
     const row = exact(wrapper.creation, ["creationOperationId", "requestId", "inputRevision", "manifestDigest",
       "requirementsHash", "hardwareRef", "visualSpecRef", "algorithmRef", "frozenInputs", "plannedOccurrenceBindings",
       "executionDefinitionVersion", "executionDefinitionDigest", "executionPath", "repairCount", "status"],
-    ["executionSources", "stage", "latestInvocationId", "latestInvocationStatus", "accountingStatus", "candidateId", "reviewOutcome"], "creation");
+    ["executionSources", "stage", "latestInvocationId", "latestInvocationStatus", "accountingStatus", "candidateId", "reviewOutcome",
+      "latestTool", "cadBuildAttempts", "previewCandidateId"], "creation");
     text(row.creationOperationId, "creationOperationId", UUID, 36);
     text(row.requestId, "requestId", UUID, 36);
     text(row.manifestDigest, "manifestDigest", DIGEST, 64);
+    if (row.latestTool != null) text(row.latestTool, "latestTool", IDENTIFIER, 128);
+    if (row.cadBuildAttempts !== undefined) integer(row.cadBuildAttempts, "cadBuildAttempts");
+    if (row.previewCandidateId != null) text(row.previewCandidateId, "previewCandidateId", UUID, 36);
     noForbiddenKeys(row, "creation response");
     return {creation: row};
   }

package/skills/abelien-structure/SKILL.md

@@ -35,13 +35,15 @@ compatibility:
 
 产品目标是尽快展示可信真实 CAD；根据可用资产组合复用、布局和参数化补建，不强制所有部件从零 Build123d。已有可信模型可先只读预览并标注未审查，实际是否支持由宿主决定；采用／交付仍须适用检查。几何执行分 preview 与 final，预览可迭代，不是只能调用两次。需求、组件、几何、相关证据或工具链变化才失效对应缓存；纯报告措辞变化不要求重新导出 CAD。
 
+局部自由造型修改的独立 structure.adapt（cad.build@2）步骤及 analytic_carrier_faceted_decoration 范围按[外观件交接](../abelien-appearance/references/local-component-edit.md)执行：保持原接口精确几何及未改实例，不要求 Build123d 重建整个装饰网格；缺可信保护区域／接口检查时只预览，不能升级为 CAD 通过。
+
 ## 本包可执行的辅助工具
 
 - `python3 scripts/check_bundle.py --project <候选目录> --manifest bundle.json --baseline <宿主当前基线>`：现代候选包的同版文件、来源／候选 BOM、逐实例数量、原生比例、几何检查覆盖与视觉报告完整性门，格式见[候选包质量](references/bundle-quality.md)。明确只证明契约完整性，不能以 viewed=true 宣称真实审查；不依赖旧 workflow-state。
 - `python3 scripts/run_stage.py --project <工程目录> --plan <任务计划.json>`：显式输入／输出清单、输入与输出哈希复用、互斥执行、可配置超时、POSIX 进程组终止及独立执行回执。计划格式见建模参考。
 - `python3 scripts/check_visual_review.py --project <工程目录> --report <审查.json> --subject <本版模型文件> --require-pass`：为 appearance 保留的兼容完整性校验实现，只检查报告结构、文件及哈希、视图和目标覆盖；不执行图像比较或几何验收。视觉语义见同级 `abelien-appearance/references/visual-review.md`。
 
-进程组清理保持 TERM → wait(2s) → KILL → wait。仅 Darwin 的 PermissionError 且原子进程已退出时，固定 `/bin/ps` 完整校验全表，证明原组无成员或全为同有效 UID 的 zombie 后才按已终止处理；活后代、未知探针与其他错误仍失败。边界见[执行参考](references/build123d-execution.md)。
+进程组清理保持 TERM → wait(2s) → KILL → wait。仅 Darwin 的 PermissionError 且原子进程已退出时，固定 `/bin/ps` 完整校验全表，证明原组无成员或全为同有效 UID 的 zombie 后才按已终止处理（该表接受 Darwin 的 `?` 未定运行态，它不使整表判废；原组自身成员为 `?` 仍不是 zombie，照旧失败）；活后代、未知探针与其他错误仍失败。边界见[执行参考](references/build123d-execution.md)。
 
 本包不注册空 `domain.json`、虚假的 `structure.*` capability 或占位 CAD 生成服务。需要有本地执行／渲染／看图能力的宿主，或另行接通对应后端。执行辅助工具是有界前台进程，不是跨请求的后台 Worker；中断后可核验并复用已完成产物，不能恢复一个已经消失的进程。