@awebai/oats 0.24.13 → 0.25.1

package/lib/portable-migration-store.mjs

@@ -1,199 +0,0 @@
-/** Immutable, unselectable historical evidence records.
- *
- * Partial/unknown evidence lives outside `.agents/resolutions` and can never be
- * consumed as dispatch authority. Publication re-verifies all inventoried input
- * witnesses first and changes no lock, home, schedule, session or approval. */
-import { linkSync, lstatSync, mkdirSync, mkdtempSync, opendirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { ensureStoreIgnore } from "./capability-artifacts.mjs";
-import { readPortableBytes } from "./portable-files.mjs";
-import { JSON_FORMAT, jsonIntegrity, validateIntegrity } from "./portable-digest.mjs";
-import { canonicalJson, compareUtf8, parseStrictJson } from "./portable-values.mjs";
-import { portableScope } from "./portable-state.mjs";
-import { objectAt, stringAt, versionAt } from "./portable-shape.mjs";
-import { validateOrigin, validateResolutionRef } from "./resolution-shape.mjs";
-import { validatePortableMigrationInventory, verifyPortableMigrationInventory } from "./portable-migration-evidence.mjs";
-import { planPortableMigration } from "./portable-migration.mjs";
-import { verifyHistoricalHomeCapabilityCandidate } from "./portable-migration-artifacts.mjs";
-import { oatsError } from "./errors.mjs";
-
-export const RESOLUTION_EVIDENCE_VERSION = 1;
-const TARGET_KINDS = new Set(["selection-lock", "instance-home", "scheduled-job"]);
-const ACTIONS = new Set(["preserve", "verify", "hold"]);
-const exists = (path) => { try { return lstatSync(path); } catch (error) { if (error.code === "ENOENT") return null; throw error; } };
-
-export function validateResolutionEvidence(value) {
-  canonicalJson(value);
-  objectAt(value, ["schemaVersion", "target", "status", "evidence", "knownInputs", "unresolved", "resolution"],
-    ["schemaVersion", "target", "status", "evidence", "knownInputs", "unresolved", "resolution"]);
-  versionAt(value.schemaVersion);
-  objectAt(value.target, ["kind", "id"], ["kind", "id"]);
-  if (!TARGET_KINDS.has(value.target.kind)) throw oatsError("invalid-evidence", "unsupported migration evidence target kind");
-  stringAt(value.target.id, "/target/id");
-  if (!Array.isArray(value.evidence)) throw oatsError("invalid-evidence", "migration evidence origins must be an array");
-  value.evidence.forEach(validateOrigin);
-  objectAt(value.knownInputs, ["inventory", "action", "preserve"], ["inventory", "action", "preserve"]);
-  validateIntegrity(value.knownInputs.inventory, [JSON_FORMAT]);
-  if (!ACTIONS.has(value.knownInputs.action)) throw oatsError("invalid-evidence", "invalid planned migration action");
-  canonicalJson(value.knownInputs.preserve);
-  if (!Array.isArray(value.unresolved)) throw oatsError("invalid-evidence", "migration unresolved inputs must be an array");
-  for (const item of value.unresolved) {
-    objectAt(item, ["pointer", "code", "origins", "reason"], ["pointer", "code", "origins", "reason"]);
-    stringAt(item.pointer, "/unresolved/pointer", { empty: true, pattern: /^(?:\/(?:[^~]|~[01])*)*$/ });
-    stringAt(item.code, "/unresolved/code"); stringAt(item.reason, "/unresolved/reason");
-    if (!Array.isArray(item.origins)) throw oatsError("invalid-evidence", "unresolved origins must be an array");
-    item.origins.forEach(validateOrigin);
-  }
-  if (!['reconstructed', 'partial', 'unknown'].includes(value.status)) throw oatsError("invalid-evidence", "invalid migration evidence status");
-  if (value.status === "reconstructed") {
-    validateResolutionRef(value.resolution);
-    if (!value.evidence.length) throw oatsError("resolution-incomplete", "reconstructed evidence requires historical witnesses");
-    if (value.unresolved.length) throw oatsError("resolution-incomplete", "reconstructed evidence cannot retain unresolved managed inputs");
-  } else if (value.resolution !== null) {
-    throw oatsError("resolution-incomplete", "partial or unknown evidence cannot reference a captured resolution");
-  }
-  return value;
-}
-
-export function validateResolutionEvidenceRef(value) {
-  canonicalJson(value, { maxBytes: 1024, maxDepth: 4, maxEntries: 8 });
-  objectAt(value, ["schemaVersion", "id"], ["schemaVersion", "id"]);
-  versionAt(value.schemaVersion);
-  stringAt(value.id, "/id", { pattern: /^sha256-[a-f0-9]{64}$/ });
-  return value;
-}
-
-function store(scope, create) {
-  let root = portableScope(scope);
-  for (const name of [".agents", "resolution-evidence"]) {
-    root = join(root, name);
-    if (create) { try { mkdirSync(root, { mode: 0o700 }); } catch (error) { if (error.code !== "EEXIST") throw error; } }
-    const stat = exists(root);
-    if (!stat) throw oatsError("evidence-not-found", "resolution evidence store is absent");
-    if (!stat.isDirectory() || realpathSync(root) !== root) throw oatsError("invalid-evidence", "resolution evidence store component is not a real directory");
-  }
-  if (create) ensureStoreIgnore(root);
-  return root;
-}
-
-function decode(path, reference) {
-  const bytes = readPortableBytes(path, { missingCode: "evidence-not-found", invalidCode: "invalid-evidence" });
-  const value = parseStrictJson(bytes);
-  if (jsonIntegrity(value).value !== reference.id || !bytes.equals(Buffer.from(canonicalJson(value)))) {
-    throw oatsError("integrity-drift", "resolution evidence bytes differ from their canonical address");
-  }
-  validateResolutionEvidence(value);
-  return value;
-}
-
-export function readResolutionEvidence(scope, reference) {
-  validateResolutionEvidenceRef(reference);
-  return decode(join(store(scope, false), `${reference.id}.json`), reference);
-}
-
-/** Bounded diagnostic enumeration of immutable evidence. Staging and managed
- * ignore metadata are not records; every other entry must be one valid file. */
-export function listResolutionEvidence(scope, { maxEntries = 512, maxRecords = 256, maxBytes = 32 * 1024 * 1024, includeDocuments = false } = {}) {
-  if (!Number.isSafeInteger(maxEntries) || maxEntries < 1 || maxEntries > 10_000
-      || !Number.isSafeInteger(maxRecords) || maxRecords < 1 || maxRecords > 10_000
-      || !Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > 256 * 1024 * 1024
-      || typeof includeDocuments !== "boolean") {
-    throw oatsError("invalid-evidence", "invalid resolution evidence listing options");
-  }
-  let root;
-  try { root = store(scope, false); }
-  catch (error) { if (error.code === "evidence-not-found") return []; throw error; }
-  const entries = [];
-  let visited = 0;
-  const directory = opendirSync(root);
-  try {
-    for (;;) {
-      const entry = directory.readSync();
-      if (entry === null) break;
-      if (++visited > maxEntries) throw oatsError("resource-limit", "resolution evidence visited-entry limit exceeded");
-      if (entry.name === ".gitignore" || entry.name.startsWith(".evidence-")) continue;
-      if (entries.length >= maxRecords) throw oatsError("resource-limit", "resolution evidence record limit exceeded");
-      entries.push(entry);
-    }
-  } finally { directory.closeSync(); }
-  const results = [];
-  let totalBytes = 0;
-  for (const entry of entries.sort((a, b) => compareUtf8(a.name, b.name))) {
-    const match = /^(sha256-[a-f0-9]{64})\.json$/.exec(entry.name);
-    if (!entry.isFile() || !match) throw oatsError("invalid-evidence", "resolution evidence store contains an unsupported entry");
-    const reference = { schemaVersion: 1, id: match[1] }, document = decode(join(root, entry.name), reference);
-    totalBytes += Buffer.byteLength(canonicalJson(document));
-    if (totalBytes > maxBytes) throw oatsError("resource-limit", "aggregate resolution evidence byte limit exceeded");
-    results.push({ reference, target: document.target, status: document.status, unresolved: document.unresolved.length,
-      ...(includeDocuments ? { document } : {}) });
-  }
-  return results;
-}
-
-function targetKey(target) { return canonicalJson(target); }
-function entryFor(plan, target) {
-  const wanted = targetKey(target), entry = plan.targets.find((candidate) => targetKey(candidate.target) === wanted);
-  if (!entry) throw oatsError("invalid-evidence", "migration target is not in the verified inventory plan");
-  if (entry.status === "reconstructed") throw oatsError("migration-required", "reconstructed publication requires the dedicated historical evidence verifier");
-  return entry;
-}
-function publishEvidence(deployment, document) {
-  validateResolutionEvidence(document);
-  const reference = { schemaVersion: 1, id: jsonIntegrity(document).value };
-  const root = store(deployment, true), destination = join(root, `${reference.id}.json`);
-  if (exists(destination)) { decode(destination, reference); return reference; }
-  const staging = mkdtempSync(join(root, ".evidence-"));
-  let failed = false, primary;
-  try {
-    const candidate = join(staging, "record.json");
-    writeFileSync(candidate, canonicalJson(document), { flag: "wx", mode: 0o600 });
-    decode(candidate, reference);
-    try { linkSync(candidate, destination); } catch (error) { if (error.code !== "EEXIST") throw error; }
-    decode(destination, reference);
-    return reference;
-  } catch (error) { failed = true; primary = error; throw error; }
-  finally {
-    try { rmSync(staging, { recursive: true, force: true }); }
-    catch (cleanup) {
-      const error = failed ? new AggregateError([primary, cleanup], "evidence publication and cleanup failed", { cause: primary })
-        : new Error("evidence staging cleanup failed", { cause: cleanup });
-      error.code = failed ? primary.code : cleanup.code; error.stagingPath = staging; throw error;
-    }
-  }
-}
-
-/** Publish exactly one target from the deterministic plan after re-reading all
- * inventory witnesses. Reconstructed records require a later dedicated verifier
- * and are deliberately outside this function. */
-export function commitPlannedResolutionEvidence(scope, inventory, target, adapters = {}) {
-  validatePortableMigrationInventory(inventory);
-  const current = verifyPortableMigrationInventory(scope, inventory, adapters);
-  const plan = planPortableMigration(current), entry = entryFor(plan, target);
-  const document = { schemaVersion: RESOLUTION_EVIDENCE_VERSION,
-    target: entry.target, status: entry.status, evidence: entry.evidence,
-    knownInputs: { inventory: plan.inventory, action: entry.action, preserve: entry.preserve ?? null },
-    unresolved: entry.unresolved, resolution: null };
-  return publishEvidence(current.deployment, document);
-}
-
-/** Persist a narrow verified home→historical capability association as
- * partial evidence. Raw legacy source/settings/commands are intentionally not
- * copied; their literal document remains addressed by the evidence origins. */
-export function commitHistoricalHomeCapabilityEvidence(scope, inventory, request, adapters = {}) {
-  validatePortableMigrationInventory(inventory);
-  const candidate = verifyHistoricalHomeCapabilityCandidate(scope, inventory, request, adapters);
-  const current = verifyPortableMigrationInventory(scope, inventory, adapters), plan = planPortableMigration(current);
-  const entry = entryFor(plan, { kind: "instance-home", id: candidate.home.path });
-  const origins = [...entry.evidence, ...candidate.artifact.evidence];
-  const seen = new Set(), evidence = origins.filter((origin) => { const key = canonicalJson(origin); if (seen.has(key)) return false; seen.add(key); return true; })
-    .sort((a, b) => compareUtf8(canonicalJson(a), canonicalJson(b)));
-  const proof = { kind: candidate.artifact.package ? "home-capability-v2" : "home-capability-v1", home: candidate.home.path,
-    capability: { id: candidate.artifact.capability.id, version: candidate.artifact.capability.row.version,
-      package: candidate.artifact.package?.id ?? null, path: candidate.artifact.package ? candidate.artifact.capability.row.path : null },
-    artifact: candidate.artifact.artifact, association: candidate.association,
-    legacyTrustedClaim: candidate.legacyTrustedClaim, selectionAuthority: candidate.artifact.selectionAuthority,
-    approvalAuthority: candidate.approvalAuthority, retentionStatus: candidate.artifact.retentionStatus };
-  const document = { schemaVersion: RESOLUTION_EVIDENCE_VERSION, target: entry.target, status: "partial", evidence,
-    knownInputs: { inventory: plan.inventory, action: "hold", preserve: proof }, unresolved: entry.unresolved, resolution: null };
-  return publishEvidence(current.deployment, document);
-}

package/lib/portable-migration.mjs

@@ -1,104 +0,0 @@
-/** Pure planning over literal historical evidence. No filesystem access, writes,
- * provider execution, source resolution, approval transfer or publication. */
-import { canonicalJson, compareUtf8 } from "./portable-values.mjs";
-import { jsonIntegrity } from "./portable-digest.mjs";
-import { validatePortableMigrationInventory } from "./portable-migration-evidence.mjs";
-import { oatsError } from "./errors.mjs";
-
-export const MIGRATION_PLAN_VERSION = 1;
-const originFor = (receipt, pointer = "") => receipt.state === "absent" ? [] : [{ kind: "migration-evidence",
-  document: { kind: "deployment", path: receipt.path, integrity: receipt.integrity }, pointer }];
-const unresolved = (code, reason, receipt, pointer = "") => ({ pointer, code, origins: originFor(receipt, pointer), reason });
-
-function lockPlan(lock) {
-  const target = { kind: "selection-lock", id: lock.path };
-  if (lock.state === "absent") return { target, status: "unknown", action: "hold", evidence: [],
-    unresolved: [unresolved("migration-held", "the historical lock file is absent", lock)] };
-  const evidence = originFor(lock);
-  if (lock.state === "invalid" || lock.format === "unknown") return { target, status: "unknown", action: "hold", evidence,
-    unresolved: [unresolved("invalid-lock", "the literal historical lock is malformed or unsupported", lock)] };
-  if (lock.format === "portable-v3") return { target, status: "partial", action: "verify", evidence,
-    unresolved: [unresolved("migration-required", "the current lock still needs its authoritative lock-v3 reader; a lock is not historical dispatch authority", lock)] };
-  const empty = lock.rowCounts.packages === 0 && lock.rowCounts.capabilities === 0;
-  return { target, status: empty ? "unknown" : "partial", action: "hold", evidence,
-    unresolved: [
-      ...(lock.semanticVerification === "verified" ? [] : [unresolved("migration-required", "the strict legacy lock reader must verify every row without reinterpretation", lock)]),
-      unresolved("migration-held", "a deployment lock does not prove which revision a particular home or job used", lock),
-      unresolved("approval-required", "legacy trust is evidence only and cannot grant new-format exact-artifact approval", lock),
-    ] };
-}
-
-function homePlan(home) {
-  const target = { kind: "instance-home", id: home.path };
-  const receipts = [home.document, home.cleanup.document].filter((entry) => entry.state !== "absent");
-  const evidence = receipts.flatMap((entry) => originFor(entry));
-  if (!receipts.length) return { target, status: "unknown", action: "hold", evidence: [],
-    unresolved: [unresolved("migration-held", "the named home has no instance or quarantine metadata", home.document)] };
-  if (home.executionBinding.state === "valid-shape") return { target, status: "partial", action: "verify", evidence,
-    preserve: { executionBinding: home.executionBinding.value },
-    unresolved: [
-      unresolved("migration-required", "the referenced captured resolution and all retained inputs must be verified before adoption", home.document, "/executionBinding"),
-      unresolved("approval-required", "current exact-artifact approval and action-specific readiness remain separate", home.document, "/executionBinding"),
-    ] };
-  const hasRuntime = home.capabilities.length || home.cleanup.capabilities.length;
-  const invalid = home.document.state === "invalid" || home.cleanup.document.state === "invalid" || home.executionBinding.state === "invalid";
-  return { target, status: hasRuntime && !invalid ? "partial" : "unknown", action: "hold", evidence,
-    unresolved: [
-      ...(invalid ? [unresolved("invalid-evidence", "historical home metadata is malformed or has an invalid captured binding", home.document)] : []),
-      unresolved("migration-held", "the home does not carry a verified complete captured resolution", home.document),
-      unresolved("migration-held", "historical source revision, full managed resources and helper closure are not established by home metadata", home.document),
-      unresolved("approval-required", "recorded legacy trust cannot authorize a reconstructed owner-exec artifact", home.document),
-      ...(home.cleanup.document.state !== "absent" ? [unresolved("migration-held", "cleanup obligations must remain retryable and cannot be discarded during migration", home.cleanup.document)] : []),
-    ] };
-}
-
-function executionCandidates(job) {
-  return [
-    ["definition", job.execution],
-    ["attempt", job.attempt],
-    ["lastRun", job.lastRun],
-  ].filter(([, value]) => value.state !== "absent");
-}
-
-function schedulePlan(schedule, job) {
-  const target = { kind: "scheduled-job", id: `${schedule.path}:${job.id}` };
-  const evidence = [schedule.definitions, schedule.state].filter((entry) => entry.state !== "absent").flatMap((entry) => originFor(entry));
-  const executions = executionCandidates(job), valid = executions.filter(([, value]) => value.state === "valid-shape");
-  const invalid = executions.some(([, value]) => value.state === "invalid") || !!job.problems?.length
-    || schedule.definitions.state === "invalid" || schedule.state.state === "invalid";
-  const unresolvedCustody = [job.attempt.state, job.lastRun.state].some((state) => state === "legacy" || state === "invalid");
-  if (unresolvedCustody) return { target, status: "unknown", action: "hold", evidence,
-    unresolved: [
-      ...(invalid ? [unresolved("invalid-evidence", "the admitted or unknown attempt evidence is malformed", schedule.state)] : []),
-      unresolved("migration-held", "an existing admitted or unknown historical attempt has no valid captured execution; preserve it exactly and require owner reconciliation", schedule.state),
-    ] };
-  if (valid.length) {
-    const preserve = { executions: valid.map(([source, value]) => ({ source, ...value })) };
-    return { target, status: "partial", action: "preserve", evidence, preserve,
-      unresolved: [
-        ...(invalid ? [unresolved("invalid-evidence", "one or more schedule records disagree with the valid captured authority and must remain held", schedule.state)] : []),
-        unresolved("migration-required", "each referenced resolution and admitted execution must be verified without rebinding", schedule.state),
-      ] };
-  }
-  const hasAttempt = job.attempt.state !== "absent" || job.lastRun.state !== "absent";
-  return { target, status: "unknown", action: "hold", evidence,
-    unresolved: [unresolved("migration-held", hasAttempt
-      ? "the admitted or unknown historical attempt has no valid captured execution; preserve it exactly and require owner reconciliation"
-      : "the legacy schedule has no captured software authority", schedule.state)] };
-}
-
-/** Produce a deterministic no-write plan. No target can become reconstructed at
- * this stage: reconstruction requires the dedicated historical verifier. */
-export function planPortableMigration(inventory) {
-  validatePortableMigrationInventory(inventory);
-  const targets = [
-    ...inventory.locks.map(lockPlan),
-    ...inventory.homes.map(homePlan),
-    ...inventory.schedules.flatMap((schedule) => schedule.jobs.map((job) => schedulePlan(schedule, job))),
-  ].sort((a, b) => compareUtf8(`${a.target.kind}:${a.target.id}`, `${b.target.kind}:${b.target.id}`));
-  if (targets.some((entry) => entry.status === "reconstructed")) throw oatsError("invalid-evidence", "unverified planner output cannot claim reconstruction");
-  const plan = { schemaVersion: MIGRATION_PLAN_VERSION, inventory: jsonIntegrity(inventory), readyToApply: false,
-    effects: { writes: false, providerExecution: false, sessionChanges: false, scheduleChanges: false, trustTransfer: false }, targets };
-  canonicalJson(plan);
-  return plan;
-}

package/lib/portable-onboarding-acceptance.mjs

@@ -1,66 +0,0 @@
-/** Fresh setup acceptance boundary. Read-only comparison and explicit mutation
- * handoff only; all source discovery and request construction remain owned by
- * portable-onboarding. */
-import { canonicalJson, freezeJson } from "./portable-values.mjs";
-import { sameIdentity } from "./portable-identity.mjs";
-import { buildFreshPreparationRequest, recheckFreshOnboarding } from "./portable-onboarding.mjs";
-import { oatsError } from "./errors.mjs";
-
-export const PORTABLE_ONBOARDING_ACCEPTANCE_VERSION = 1;
-
-/** Prove two issued/ready inspections name one unchanged source while retaining
- * distinct organization and standalone work/context facts. */
-export function compareFreshSourceAcceptance({ organization, standalone }) {
-  const organizationRequest = buildFreshPreparationRequest(organization), standaloneRequest = buildFreshPreparationRequest(standalone);
-  if (!organization.workspace || organization.context.kind !== "workspace") throw oatsError("invalid-declaration", "organization acceptance requires an explicit workspace context");
-  if (standalone.workspace !== null || standalone.context.kind !== "standalone") throw oatsError("invalid-declaration", "standalone acceptance requires an explicit standalone context");
-  if (standalone.workTarget.git.present) throw oatsError("invalid-declaration", "standalone acceptance work target must be explicitly non-Git");
-  if (!sameIdentity(organization.source.identity, standalone.source.identity)) throw oatsError("source-identity-change", "acceptance inspections name different source identities");
-  if (organization.source.revision.commit !== standalone.source.revision.commit
-      || organization.source.exportPath !== standalone.source.exportPath
-      || organization.source.definition !== standalone.source.definition) {
-    throw oatsError("integrity-drift", "acceptance inspections do not name the same unchanged source export");
-  }
-  return freezeJson({ schemaVersion: PORTABLE_ONBOARDING_ACCEPTANCE_VERSION, status: "ready",
-    source: { identity: organization.source.identity, commit: organization.source.revision.commit,
-      exportPath: organization.source.exportPath, definition: organization.source.definition },
-    organization: { context: organization.context, workTarget: organization.workTarget,
-      preparation: organizationRequest.preparation },
-    standalone: { context: standalone.context, workTarget: standalone.workTarget,
-      preparation: standaloneRequest.preparation },
-    effects: { writes: false, preparation: false, approval: false, enrollment: false } });
-}
-
-function approvalRequests(result) {
-  const requests = [];
-  for (const selection of Array.isArray(result?.selections) ? result.selections : []) {
-    for (const capability of Array.isArray(selection.approvalRequired) ? selection.approvalRequired : []) {
-      requests.push({ capability, artifactSet: selection.artifactSet, request: selection.request });
-    }
-  }
-  return requests;
-}
-
-/** Recheck fresh deployment state immediately before an explicitly supplied
- * public preparation function. Missing integration/provisioning remains pending;
- * no stale inspection is permission to overwrite managed state. */
-export function prepareFreshOnboarding(inspection, options = {}, { prepareCapturedComposition } = {}) {
-  canonicalJson(options);
-  const built = buildFreshPreparationRequest(inspection, options);
-  const preflight = recheckFreshOnboarding(inspection);
-  const requestedBindings = built.preparation.operator?.bindings ?? null;
-  if (preflight.deployment.state === "absent") return freezeJson({ schemaVersion: PORTABLE_ONBOARDING_ACCEPTANCE_VERSION,
-    status: "pending", code: "fresh-deployment-provisioning-required", mutationAttempted: false,
-    preparation: built.preparation, workTarget: built.workTarget, requestedBindings,
-    resolution: null, approvalRequests: [], problems: [{ code: "fresh-deployment-provisioning-required", message: "provision the explicit fresh deployment path before preparation" }] });
-  if (typeof prepareCapturedComposition !== "function") return freezeJson({ schemaVersion: PORTABLE_ONBOARDING_ACCEPTANCE_VERSION,
-    status: "pending", code: "onboarding-integration-required", mutationAttempted: false,
-    preparation: built.preparation, workTarget: built.workTarget, requestedBindings,
-    resolution: null, approvalRequests: [], problems: [{ code: "onboarding-integration-required", message: "the public captured preparation adapter is not available" }] });
-  const result = prepareCapturedComposition(built.preparation);
-  if (!result || typeof result !== "object" || Array.isArray(result)) throw oatsError("invalid-resolution", "public preparation returned no structured result");
-  return freezeJson({ schemaVersion: PORTABLE_ONBOARDING_ACCEPTANCE_VERSION,
-    status: typeof result.status === "string" ? result.status : "pending", mutationAttempted: true,
-    preparation: built.preparation, workTarget: built.workTarget, requestedBindings,
-    resolution: result.resolution ?? null, approvalRequests: approvalRequests(result), problems: Array.isArray(result.problems) ? result.problems : [] });
-}

package/lib/setup-expert-source.mjs

@@ -1,100 +0,0 @@
-/** Read the setup edition as data for a CLASSIC local bootstrap copy.
- * No provider code, workspace activation, enrollment or captured identity. */
-import { lstatSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { tmpdir } from 'node:os';
-import { fileURLToPath } from 'node:url';
-import { parsePortableSoul } from './portable-soul.mjs';
-import { parseRepositorySource, parsePortableSource } from './source-spec.mjs';
-import { createRepositoryTransaction } from './repository-observation.mjs';
-import { createWorkspaceDiscovery } from './workspace-discovery.mjs';
-import { packageIntegrity } from './core.mjs';
-import { oatsError } from './errors.mjs';
-
-export const SETUP_EXPERT = 'oats-setup-expert';
-export const SETUP_CAPABILITIES = Object.freeze(['oats.core', 'oats.setup']);
-const EXPORT = `souls/${SETUP_EXPERT}`;
-function validateEdition(bytes) {
-  const { declaration: soul } = parsePortableSoul(bytes);
-  const required = soul.requires || {}, caps = required.capabilities || {};
-  if (soul.name !== SETUP_EXPERT || soul.work !== 'directory'
-      || Object.keys(required).some(key => key !== 'capabilities')
-      || Object.keys(caps).length !== 2 || SETUP_CAPABILITIES.some(id => caps[id]?.source !== 'repo:oats-package' || Object.keys(caps[id]).some(key => key !== 'source'))
-      || ['knowledge', 'messaging', 'tasks'].some(slot => soul.defaults?.[slot] !== 'none')
-      || Object.keys(soul.defaults || {}).some(key => !['knowledge', 'messaging', 'tasks'].includes(key))
-      || soul.knowledge || soul.teams?.length || soul.resources?.length || soul.yolo === true || soul.backend || soul['launch-config']) {
-    throw oatsError('needs-configuration', 'classic setup bootstrap needs the provider-independent directory edition with only oats.core/oats.setup; use explicit portable preparation for other requirements');
-  }
-  return soul;
-}
-function repositoryRequest(source) {
-  if (typeof source !== 'string' || source.includes('#')) throw oatsError('invalid-source', '--workspace needs a Git repository source, optionally @revision, without a package fragment');
-  try { return { source: parseRepositorySource(source).normalized }; }
-  catch {
-    const parsed = parsePortableSource(source);
-    if (parsed.kind !== 'git') throw oatsError('invalid-source', '--workspace needs an explicit Git repository source');
-    return { source: `git:${parsed.url}`, revision: parsed.selector };
-  }
-}
-
-/** `packages["oats.framework"]` from the repository's own `package-catalog.json` at the observed
- *  revision, or null when the file or entry is absent. Data only; the acquisition still verifies
- *  bytes, and the edition/package integrity comparison still applies. */
-function frameworkCatalogEntry(transaction, observation) {
-  const file = transaction.readFile(observation, 'package-catalog.json', { optional: true });
-  if (!file) return null;
-  let doc;
-  try { doc = JSON.parse(file.bytes.toString('utf8')); } catch { throw oatsError('invalid-source', 'workspace package-catalog.json is not valid JSON'); }
-  const entry = doc && typeof doc === 'object' && !Array.isArray(doc) && doc.packages && typeof doc.packages === 'object' && !Array.isArray(doc.packages)
-    ? doc.packages['oats.framework'] : undefined;
-  if (entry === undefined) return null;
-  if (!entry || typeof entry !== 'object' || Array.isArray(entry) || typeof entry.url !== 'string' || typeof entry.ref !== 'string' || (entry.path !== undefined && typeof entry.path !== 'string')) {
-    throw oatsError('invalid-source', 'workspace package-catalog.json has an invalid oats.framework entry');
-  }
-  return { url: entry.url, ref: entry.ref, ...(entry.path === undefined ? {} : { path: entry.path }), revision: observation.source.commit };
-}
-
-export function loadSetupExpertEdition(workspace, repositoryOptions = {}) {
-  if (workspace === undefined) {
-    const root = fileURLToPath(new URL(`../${EXPORT}/`, import.meta.url));
-    return { declaration: validateEdition(readFileSync(join(root, 'soul.yaml'))), instructions: readFileSync(join(root, 'AGENTS.md'), 'utf8'),
-      source: { kind: 'packaged-definition', captured: false }, packageIntegrity: null, catalogEntry: null };
-  }
-  const request = repositoryRequest(workspace), scratch = realpathSync(mkdtempSync(join(tmpdir(), 'oats-setup-source-'))), owned = lstatSync(scratch);
-  let transaction;
-  try {
-    transaction = createRepositoryTransaction({ ...repositoryOptions, directory: scratch, accessContextKey: 'explicit-setup-source' });
-    const discovery = createWorkspaceDiscovery(transaction), origin = { kind: 'operator', document: { kind: 'operator', id: 'oats-onboard' }, pointer: '/workspace' };
-    const observed = transaction.observe(request.source, { ...request, origin });
-    const workspaceDoc = transaction.readFile(observed, 'oats-workspace.yaml', { optional: true });
-    const view = workspaceDoc ? discovery.readWorkspace({ ...request, origin }) : null;
-    const reference = view?.parsed.imports.find(item => item.alias === SETUP_EXPERT)
-      ?? { source: request.source, revision: observed.source.commit, soul: EXPORT, alias: SETUP_EXPERT };
-    // A selected workspace import never falls back if its exact source fails.
-    const imported = discovery.importSoul(reference, { origin });
-    if (reference.adoption) throw oatsError('needs-configuration', 'classic setup copies an edition only; provider adoption values require the portable preparation path');
-    const declaration = validateEdition(transaction.readFile(imported.observation, imported.definition).bytes);
-    const projection = join(scratch, 'edition');
-    transaction.materialize(imported.observation, imported.roots, projection);
-    const soulRoot = join(projection, dirname(imported.definition)), body = join(soulRoot, 'AGENTS.md'), alias = join(soulRoot, 'CLAUDE.md');
-    if (!lstatSync(body).isFile() || !lstatSync(alias).isSymbolicLink() || readlinkSync(alias) !== 'AGENTS.md'
-        || readdirSync(soulRoot).some(name => !['soul.yaml', 'AGENTS.md', 'CLAUDE.md'].includes(name))) {
-      throw oatsError('source-incomplete', 'classic setup edition must have canonical AGENTS.md/CLAUDE.md and no omitted private skill or knowledge trees');
-    }
-    // The workspace publishes the reviewed catalog: read the oats.framework entry at the WORKSPACE's
-    // observed revision (falling back to the edition's own revision when the source has no workspace
-    // document), so onboarding acquires the framework the workspace currently names instead of
-    // whatever the kernel tarball snapshotted at its own tag. The edition/package integrity check
-    // below still decides whether that acquisition matches the copied edition.
-    const catalogEntry = frameworkCatalogEntry(transaction, observed) ?? frameworkCatalogEntry(transaction, imported.observation);
-    return { declaration, instructions: readFileSync(body, 'utf8'), packageIntegrity: packageIntegrity(join(projection, 'oats-package')),
-      catalogEntry,
-      source: { kind: 'exported-edition-copy', source: imported.reference.source, revision: imported.observation.source.commit,
-        path: imported.reference.soul, workspaceRevision: view?.source.commit ?? null, captured: false } };
-  } finally {
-    transaction?.close();
-    const current = lstatSync(scratch);
-    if (!current.isDirectory() || current.dev !== owned.dev || current.ino !== owned.ino) throw oatsError('source-unavailable', 'setup source scratch ownership changed');
-    rmSync(scratch, { recursive: true });
-  }
-}