@awebai/oats 0.24.12 → 0.25.0

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 });
-  }
-}