@awebai/oats 0.23.2 → 0.24.1

package/lib/prepared-resources.mjs

@@ -0,0 +1,127 @@
+/** Build retained command/curriculum records from already selected software.
+ * Kernel callbacks own existing skill discovery and manifest command semantics. */
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+import { copyTreeSafe } from "./artifact-tree.mjs";
+import { treeIntegrity, jsonIntegrity } from "./portable-digest.mjs";
+import { retainPortableArtifact, verifyPortableArtifact } from "./portable-artifacts.mjs";
+import { commitCapturedResolution, verifyResolutionInputs } from "./captured-resolutions.mjs";
+import { readPortableBytes } from "./portable-files.mjs";
+import { captureHelperInjectionChoices } from "./helper-injection-policy.mjs";
+import { parseConfigData } from "./config-data.mjs";
+import { oatsError } from "./errors.mjs";
+import { normalizePackagePath } from "./capability-provenance.mjs";
+import { compileCapturedLaunchRequest } from "./captured-launch-request.mjs";
+
+export function completePreparedResources({ seed, plan, manifests, mode, deployment, directory, launch, helperLaunches = {} }, kernel) {
+  const problems = [];
+  for (const [id, manifest] of manifests) {
+    if (!Object.hasOwn(seed.artifacts.capabilities, id)) continue;
+    if (manifest.layer && seed.bindings?.[manifest.layer]?.capability !== id) problems.push({ code: "provider-not-qualified", message: `provider ${id} needs its binding adapter before complete preparation`, origins: [] });
+    const settings = Object.fromEntries(Object.entries(plan.settings[id] ?? {}).map(([name, key]) => [name, plan.choices[key].value]));
+    kernel.settings(manifest, settings);
+  }
+  if (problems.length) return { record: null, problems };
+  const snapshot = join(directory, "kernel-resources"); mkdirSync(snapshot); mkdirSync(join(snapshot, "injects"));
+  const kernelSkills = ["oats-portable", "oats-portable-artifacts"];
+  const workInjection = (workMode) => workMode === "directory" ? "portable-work-directory.md" : `work-${workMode}.md`;
+  const injectionFiles = ["oats-portable.md", "portable-instance-boundary.md", ...kernel.workModes.map(workInjection)];
+  // Only known kernel resources, never a sweep of the checkout/node_modules,
+  // author directories, deployment config or credentials.
+  for (const name of kernelSkills) copyTreeSafe(join(kernel.root, "skills", name), join(snapshot, "skills", name));
+  for (const file of injectionFiles) copyTreeSafe(join(kernel.root, "injects", file), join(snapshot, "injects", file));
+  const bundle = { kind: "resource", integrity: treeIntegrity(snapshot) };
+  retainPortableArtifact(deployment, snapshot, bundle);
+  const portable = (root, path) => relative(root, path).split(sep).join("/") || ".";
+  const effectiveSettings = Object.fromEntries(Object.entries(plan.settings).map(([id, values]) => [id,
+    Object.fromEntries(Object.entries(values).map(([name, key]) => [name, plan.choices[key].value]))]));
+  const definitions = Object.values(seed.artifacts.capabilities).map(row => ({ artifact: row.artifact,
+    bytes: readPortableBytes(join(verifyPortableArtifact(deployment, row.artifact).dir, "oats.json")) }));
+  const build = (subject, workMode, helpers, launchRequest) => {
+    const helperPolicy = subject.kind === "helper" ? captureHelperInjectionChoices(plan, definitions) : null;
+    const resources = Object.create(null), blocks = [], skills = [], names = new Set(), omissions = [];
+    const owner = subject.kind === "persistent" ? subject.soul.sourceArtifact : subject.provider;
+    const sourceRoot = verifyPortableArtifact(deployment, owner).dir;
+    const definition = subject.kind === "persistent" ? subject.soul.definition : subject.definition.path;
+    const soulRoot = join(sourceRoot, dirname(definition));
+    resources.body = { owner, path: portable(sourceRoot, join(soulRoot, "AGENTS.md")), kind: "file" };
+    const inject = (source, owner, path) => {
+      const key = `instruction:${source}`; resources[key] = { owner, path, kind: "file" }; blocks.push({ source, resource: key });
+    };
+    inject("kernel:oats-portable", bundle, "injects/oats-portable.md");
+    inject("kernel:instance-boundary", bundle, "injects/portable-instance-boundary.md");
+    inject(`work-mode:${workMode}`, bundle, `injects/${workInjection(workMode)}`);
+    const skillTree = (owner, root, tree, label, required = true) => {
+      const entries = kernel.skills(tree);
+      if (required && !entries.length) throw oatsError("resource-not-found", "a declared skill tree contains no readable skill");
+      for (const entry of entries) {
+        if (names.has(entry.name)) throw oatsError("needs-configuration", `skill ${entry.name} has multiple sources; an explicit override is required`);
+        names.add(entry.name);
+        const key = `skill:${label}:${entry.name}`; resources[key] = { owner, path: portable(root, entry.src), kind: "skill" };
+        skills.push({ name: entry.name, resource: key });
+      }
+    };
+    const kernelRoot = verifyPortableArtifact(deployment, bundle).dir;
+    for (const name of kernelSkills) skillTree(bundle, kernelRoot, join(kernelRoot, "skills", name), "kernel");
+    if (existsSync(join(soulRoot, "skills"))) skillTree(owner, sourceRoot, join(soulRoot, "skills"), "soul", false);
+    const providerManifests = Object.create(null);
+    for (const [id, row] of Object.entries(seed.artifacts.capabilities)) {
+      const manifest = manifests.get(id), root = verifyPortableArtifact(deployment, row.artifact).dir;
+      const key = `manifest:${id}`; resources[key] = { owner: row.artifact, path: "oats.json", kind: "manifest" }; providerManifests[id] = key;
+      for (const path of manifest.skills ?? []) skillTree(row.artifact, root, join(root, path), id);
+      if (helperPolicy) {
+        const policy = helperPolicy.policies.get(id);
+        if (policy.fact) {
+          if (policy.resource) {
+            resources[policy.resourceKey] = policy.resource;
+            blocks.push({ source: policy.source, resource: policy.resourceKey, choice: policy.fact.key });
+          } else omissions.push({ source: policy.source, reason: "helper-policy", choice: policy.fact.key });
+        }
+      } else if (manifest.inject) inject(`capability:${id}`, row.artifact, portable(root, join(root, manifest.inject)));
+      for (const [kind, declarations] of [["command", manifest.commands ?? {}], ["hook", kernel.hooks(manifest)]]) {
+        for (const [name, value] of Object.entries(declarations)) {
+          if (typeof value !== "string" || !value.trim() || value.includes("\0")) throw oatsError("invalid-resolution", "declared executable is not valid text");
+          resources[`executable:${id}:${kind}:${name}`] = { owner: row.artifact, path: portable(root, join(root, value.trim().split(/\s+/)[0])), kind: "file" };
+        }
+      }
+    }
+    const capturedLaunch = compileCapturedLaunchRequest(launchRequest, { artifacts: seed.artifacts, manifests, settings: effectiveSettings, resources }, kernel);
+    return { ...seed, subject, choices: helperPolicy?.choices ?? seed.choices, bindings: seed.bindings ?? {}, messagingChoice: seed.messagingChoice ?? { schemaVersion: 1, enabled: false }, resources, resourceBundles: [bundle], helpers,
+      dispatch: { schemaVersion: 1, providerManifests, settingsChoices: plan.settings, launch: capturedLaunch, runtimePackages: [], hostRequirements: [], workTargetInputs: {},
+        composition: { schemaVersion: 1, mode: workMode, body: "body", blocks, skills, omissions } } };
+  };
+  // Preflight EVERY helper before publishing any helper record. Until helpers
+  // run their own complete provider/software preparation, inheriting a parent's
+  // binding over helper-authored policy would create a usable contradiction.
+  const helperPlans = [], helperKeys = new Set();
+  for (const [id, row] of Object.entries(seed.artifacts.capabilities)) {
+    const root = verifyPortableArtifact(deployment, row.artifact).dir;
+    for (const path of manifests.get(id).agents ?? []) {
+      const normalized = normalizePackagePath(path);
+      if (normalized === undefined) throw oatsError("invalid-declaration", "invalid helper export path");
+      const definitionPath = `${normalized === "." ? "" : `${normalized}/`}soul.yaml`;
+      const definition = parseConfigData(readFileSync(join(root, definitionPath))).value;
+      const authoredPolicy = ["requires", "defaults"].filter((field) => definition[field] && Object.keys(definition[field]).length);
+      for (const field of ["knowledge", "teams", "resources"]) if (Object.hasOwn(definition, field)) authoredPolicy.push(field);
+      if (authoredPolicy.length) return { record: null, problems: [{ code: "needs-configuration",
+        message: `helper has authored ${authoredPolicy.join(", ")} policy requiring dedicated preparation; parent bindings were not inherited`, origins: [] }] };
+      const helperMode = definition.work ?? "directory";
+      if (!kernel.workModes.includes(helperMode)) throw oatsError("invalid-declaration", "helper work mode is invalid");
+      const subject = { kind: "helper", provider: row.artifact, name: definition.name, definition: { owner: row.artifact, path: definitionPath, kind: "file" } };
+      const key = `${id}:${definition.name}`;
+      if (helperKeys.has(key)) throw oatsError("invalid-declaration", "duplicate helper export name");
+      helperKeys.add(key); helperPlans.push({ key, subject, helperMode });
+    }
+  }
+  for (const key of Object.keys(helperLaunches)) if (!helperKeys.has(key)) throw oatsError("helper-not-selected", "helper launch request must name an exact selected helper-map key");
+  // Compile EVERY launch request before publishing any helper record. No partial
+  // usable helper graph when a later helper's runtime inputs are unsupported.
+  const records = helperPlans.map(({ key, subject, helperMode }) => ({ key, record: build(subject, helperMode, {}, helperLaunches[key]) }));
+  const record = build(seed.subject, mode, {}, launch), helpers = Object.create(null);
+  // Verify every prospective file/owner/witness before publishing ANY member
+  // of this graph, including a primary file omitted only for helpers.
+  for (const candidate of [...records.map(item => item.record), record]) verifyResolutionInputs(deployment,
+    { schemaVersion: 1, id: jsonIntegrity(candidate).value }, { draft: candidate });
+  for (const item of records) helpers[item.key] = commitCapturedResolution(deployment, item.record);
+  return { record: { ...record, helpers }, problems: [] };
+}

package/lib/provider-binding-broker.mjs

@@ -0,0 +1,59 @@
+/** Execute only an approved retained provider command. Preparation does not need
+ * a fabricated complete resolution merely to obtain its binding. */
+import { spawnSync } from 'node:child_process';
+import { canonicalJson } from './portable-values.mjs';
+import { objectAt } from './portable-shape.mjs';
+import { validateArtifactSet } from './resolution-shape.mjs';
+import { verifyPortableArtifact } from './portable-artifacts.mjs';
+import { verifyRetainedCapability, verifyResolutionInputs } from './captured-resolutions.mjs';
+import { buildCapturedInvocationContext } from './captured-invocation-context.mjs';
+import { readApprovalLedger, evaluateCapturedApprovals } from './artifact-approvals.mjs';
+import { validateBindingInterface } from './provider-binding.mjs';
+import { BINDING_LIMITS, validateBindingRequest, decodeBindingResponse } from './provider-binding-wire.mjs';
+import { oatsError } from './errors.mjs';
+
+export function invokeProviderBinding(options,codecs) {
+  canonicalJson(options);
+  objectAt(options,['deployment','artifacts','capability','phase','settings','input','timeoutMs'],['deployment','artifacts','capability','phase','settings','input']);
+  const {deployment,artifacts,capability,phase,settings,input,timeoutMs=30000}=options;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000) throw oatsError('invalid-declaration','binding timeout must be between 1 and 30000 milliseconds');
+  validateArtifactSet(artifacts);
+  if (!Object.hasOwn(artifacts.capabilities,capability)) throw oatsError('capability-not-selected','binding provider is not selected');
+  const row=artifacts.capabilities[capability],root=verifyPortableArtifact(deployment,row.artifact).dir;
+  const manifest=verifyRetainedCapability(root,artifacts,capability,codecs.manifest(root));
+  const binding=validateBindingInterface(manifest);
+  if (!binding) throw oatsError('provider-not-qualified','provider has no binding interface');
+  const request=validateBindingRequest({schemaVersion:1,phase,slot:manifest.layer,capability,settings,input});
+  if (phase === 'check' && input.invocation !== undefined) {
+    // Public check callers cannot turn a merely shape-valid projection into
+    // authority. Re-derive it from the referenced retained record/current target.
+    const verified=verifyResolutionInputs(deployment,input.invocation.executionBinding.resolution),record=verified.record;
+    if (record.capture !== 'prepared') throw oatsError('migration-required','captured check cannot use unverified reconstructed authority');
+    const actual=buildCapturedInvocationContext({loaded:{...verified,deployment,resolution:input.invocation.executionBinding.resolution,capability:{id:capability}},
+      action:input.action,instance:input.invocation.instance === null ? null : Object.fromEntries(['home','work','name','agent'].map(key=>[key,input.invocation.instance[key]])),
+      intent:input.invocation.intent,priorReceipt:input.invocation.priorReceipt});
+    const effective=Object.fromEntries(Object.entries(record.dispatch.settingsChoices[capability] ?? {}).map(([name,key])=>[name,record.choices[key].value]));
+    if (canonicalJson(actual)!==canonicalJson(input.invocation) || canonicalJson(record.artifacts)!==canonicalJson(artifacts)
+      || !record.bindings[manifest.layer] || canonicalJson(record.bindings[manifest.layer])!==canonicalJson(input.binding)
+      || canonicalJson(effective)!==canonicalJson(settings)) throw oatsError('invalid-resolution','provider check invocation differs from retained authority');
+  }
+  codecs.settings(manifest,settings);
+  const selected={record:{artifacts:{...artifacts,capabilities:{[capability]:row}}},manifests:new Map([[capability,manifest]])};
+  const approval=evaluateCapturedApprovals(selected,readApprovalLedger(deployment).ledger)[0];
+  if (approval.status !== 'approved') throw oatsError('approval-required','provider codec requires current exact-artifact approval');
+  if (codecs.host({manifest}).length) throw oatsError('host-requirement-missing','provider codec has unmet host requirements');
+  const spec=manifest.commands[binding[phase]];
+  const [script,...args]=spec.trim().split(/\s+/),file=codecs.executable(manifest,script);
+  if (!file) throw oatsError('resource-not-found','provider codec executable is unavailable');
+  const environment=Object.fromEntries(Object.entries(process.env).filter(([key])=>! /^(OATS_|OAS_|PI_)/.test(key)));
+  Object.assign(environment,{OATS_CAPABILITY:capability,OATS_CAPABILITY_ROOT:root,OATS_SETTINGS:canonicalJson(settings,BINDING_LIMITS)});
+  let result;
+  try {
+    result=spawnSync(process.execPath,[file,...args],{cwd:root,env:environment,input:canonicalJson(request,BINDING_LIMITS),
+      timeout:timeoutMs,killSignal:'SIGKILL',maxBuffer:BINDING_LIMITS.maxBytes,stdio:['pipe','pipe','pipe'],shell:false});
+  } catch { throw oatsError('provider-unavailable','provider codec could not execute'); }
+  if (result.error || result.signal || result.status !== 0) throw oatsError('provider-unavailable','provider codec did not complete successfully');
+  const response=decodeBindingResponse(result.stdout,request);
+  if (!response.ok) throw oatsError(response.error.code,'provider binding phase refused');
+  return response.result;
+}

package/lib/provider-binding-wire.mjs

@@ -0,0 +1,110 @@
+/** Bounded provider wire data. No provider model, precedence or native execution. */
+import { canonicalJson, parseStrictJson } from './portable-values.mjs';
+import { objectAt, stringAt, versionAt } from './portable-shape.mjs';
+import { validateOrigin, validateProviderBinding, validateMessagingChoice, validateCapturedChoices, validateCapturedContext } from './resolution-shape.mjs';
+import { validateCapturedInvocationContext } from './captured-invocation-context.mjs';
+import { FUNDAMENTAL_SLOTS } from './portable-policy.mjs';
+import { isMaterializedCapabilityId } from './capability-provenance.mjs';
+import { BINDING_PHASES } from './provider-binding.mjs';
+import { resolveChoices } from './portable-choices.mjs';
+import { oatsError } from './errors.mjs';
+
+export const BINDING_LIMITS = Object.freeze({maxBytes:1024*1024,maxDepth:32,maxEntries:16384});
+export const BINDING_PROBLEMS = Object.freeze(['needs-configuration','requirement-conflict','invalid-binding','authorization-required','host-requirement-missing','provider-unavailable','provider-not-qualified']);
+const fail = () => { throw oatsError('invalid-binding-output','provider returned invalid binding data'); };
+const same = (a,b) => canonicalJson(a) === canonicalJson(b);
+const roleKinds = {soul:['soul-requirement','soul-default'],workspace:['workspace-default'],adoption:['import-adoption'],operator:['operator']};
+const pointer = key => typeof key === 'string' && /^(?:\/(?:[^~]|~[01])*)+$/.test(key);
+export const bindingField = (key,slot) => pointer(key) && key.startsWith(`/bindings/${slot}/`) && key.length > `/bindings/${slot}/`.length;
+function problem(value) {
+  objectAt(value,['code','message'],['code']);
+  if (!BINDING_PROBLEMS.includes(value.code)) fail();
+  if (value.message !== undefined) stringAt(value.message,'/message',{empty:true});
+  return {code:value.code}; // Free text never leaves the provider boundary.
+}
+export function validateBindingRequest(request) {
+  canonicalJson(request,BINDING_LIMITS);
+  objectAt(request,['schemaVersion','phase','slot','capability','settings','input'],['schemaVersion','phase','slot','capability','settings','input']);
+  versionAt(request.schemaVersion);
+  if (!BINDING_PHASES.includes(request.phase) || !FUNDAMENTAL_SLOTS.includes(request.slot) || !isMaterializedCapabilityId(request.capability)) fail();
+  objectAt(request.settings,null,[]); const input=request.input;
+  if (request.phase === 'normalize') {
+    objectAt(input,['declarations','context'],['declarations','context']);
+    if (!Array.isArray(input.declarations)) fail();
+    for (const declaration of input.declarations) {
+      objectAt(declaration,['kind','value','origin','origins'],['kind','value','origin','origins']);
+      if (!Object.hasOwn(roleKinds,declaration.kind)) fail();
+      validateOrigin(declaration.origin); objectAt(declaration.origins,null,[]);
+      if (!roleKinds[declaration.kind].includes(declaration.origin.kind)) fail();
+      for (const [key,origin] of Object.entries(declaration.origins)) {
+        if (key !== '' && !pointer(key)) fail();
+        validateOrigin(origin);
+        if (!roleKinds[declaration.kind].includes(origin.kind) || !same(origin.document,declaration.origin.document)) fail();
+      }
+    }
+  } else if (request.phase === 'bind') {
+    objectAt(input,['model','choices','context'],['model','choices','context']);
+    validateCapturedChoices(input.choices);
+    for (const key of Object.keys(input.choices)) if (!bindingField(key,request.slot)) fail();
+  } else {
+    objectAt(input,['binding','context','action','invocation'],['binding','context','action']);
+    validateProviderBinding(input.binding); objectAt(input.action,null,['kind']);
+    if (input.binding.capability !== request.capability) fail();
+    if (Object.hasOwn(input,'invocation')) {
+      const invocation=validateCapturedInvocationContext(input.invocation);
+      if (invocation.capability !== request.capability || !same(invocation.context,input.context) || !same(invocation.action,input.action)) fail();
+      if (request.slot === 'messaging' && (!invocation.messagingChoice.enabled || invocation.messagingChoice.privateKey.provider !== request.capability)) fail();
+    }
+  }
+  validateCapturedContext(input.context);
+  return request;
+}
+function witnessed(origin,declarations) {
+  validateOrigin(origin);
+  return declarations.some(declaration => roleKinds[declaration.kind].includes(origin.kind)
+    && [declaration.origin,...Object.values(declaration.origins)].some(candidate => {
+      const {kind:_,...a}=origin, {kind:__,...b}=candidate;
+      return same(a,b);
+    }));
+}
+export function decodeBindingResponse(bytes,request) {
+  let response;
+  try {
+    validateBindingRequest(request);
+    response=parseStrictJson(bytes,BINDING_LIMITS);
+    objectAt(response,response?.ok === true ? ['schemaVersion','phase','slot','capability','ok','result'] : ['schemaVersion','phase','slot','capability','ok','error'],
+      response?.ok === true ? ['schemaVersion','phase','slot','capability','ok','result'] : ['schemaVersion','phase','slot','capability','ok','error']);
+    for (const key of ['schemaVersion','phase','slot','capability']) if (response[key] !== request[key]) fail();
+    if (response.ok === false) return {ok:false,error:problem(response.error)};
+    if (response.ok !== true) fail();
+    const result=response.result;
+    if (request.phase === 'normalize') {
+      objectAt(result,['requirements','candidates','model'],['requirements','candidates','model']);
+      if (!Array.isArray(result.requirements) || !Array.isArray(result.candidates)) fail();
+      for (const entry of [...result.requirements,...result.candidates]) {
+        if (!bindingField(entry.key,request.slot) || !witnessed(entry.origin,request.input.declarations)) fail();
+      }
+      for (const requirement of result.requirements) if (requirement.origin.kind !== 'soul-requirement') fail();
+      for (const candidate of result.candidates) if (candidate.kind !== candidate.origin.kind) fail();
+      // Reuse the sole entry codec/solver; conflicts are data for the combined plan.
+      resolveChoices(result);
+      return {ok:true,result};
+    }
+    if (request.phase === 'bind') {
+      const keys=['payloadContract','payloadVersion','payload','credentialRefs','provenance'];
+      objectAt(result,request.slot === 'messaging' ? [...keys,'messagingChoice'] : keys,request.slot === 'messaging' ? [...keys,'messagingChoice'] : keys);
+      const {messagingChoice,...fields}=result;
+      const binding=validateProviderBinding({schemaVersion:1,capability:request.capability,...fields});
+      // Source read/ownership provenance may live in the opaque normalized model;
+      // preparation validates that additional provenance against its original input.
+      if (request.slot === 'messaging') validateMessagingChoice(messagingChoice,{bindings:{messaging:binding},context:request.input.context});
+      return {ok:true,result:{binding,...(request.slot === 'messaging' ? {messagingChoice} : {})}};
+    }
+    objectAt(result,['status','problems'],['status','problems']);
+    if (!['ready','needs-configuration','authorization-required','unavailable'].includes(result.status) || !Array.isArray(result.problems)) fail();
+    const problems=result.problems.map(problem);
+    if (result.status === 'ready' && problems.length) fail();
+    return {ok:true,result:{status:result.status,problems}};
+  } catch { fail(); }
+}
+export function bindingOriginWitnessed(origin,declarations) { return witnessed(origin,declarations); }

package/lib/provider-binding.mjs

@@ -0,0 +1,22 @@
+/** Provider-owned binding protocol. This codec declares no provider model and
+ * grants no execution authority; commands remain in the sole manifest table. */
+import { objectAt, stringAt, versionAt } from './portable-shape.mjs';
+import { FUNDAMENTAL_SLOTS } from './portable-policy.mjs';
+import { oatsError } from './errors.mjs';
+
+export const BINDING_PHASES = Object.freeze(['normalize', 'bind', 'check']);
+export function validateBindingInterface(manifest) {
+  if (manifest.binding === undefined) return null;
+  if (!FUNDAMENTAL_SLOTS.includes(manifest.layer)) throw oatsError('invalid-binding-interface', 'binding codecs belong to a fundamental provider slot');
+  const binding = manifest.binding;
+  objectAt(binding, ['version', ...BINDING_PHASES], ['version', ...BINDING_PHASES], '/binding');
+  versionAt(binding.version);
+  for (const phase of BINDING_PHASES) {
+    const name = binding[phase];
+    stringAt(name, `/binding/${phase}`, { pattern: /^[a-z0-9][a-z0-9-]*$/ });
+    if (!manifest.commands || !Object.hasOwn(manifest.commands, name) || typeof manifest.commands[name] !== 'string' || !manifest.commands[name].trim()) {
+      throw oatsError('invalid-binding-interface', 'binding phase must reference a command owned by this manifest');
+    }
+  }
+  return binding;
+}

package/lib/repository-observation.mjs

@@ -0,0 +1,226 @@
+/** Exact, transaction-scoped repository observations. Bare Git reads never check
+ * out or execute source content. Cache lifetime/auth context is one transaction. */
+import { execFileSync } from "node:child_process";
+import { lstatSync, mkdirSync, mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { canonicalJson, decodeUtf8, freezeJson, parseStrictJson } from "./portable-values.mjs";
+import { bytesIntegrity } from "./portable-digest.mjs";
+import { parseRepositorySource, portablePath, revisionSelector } from "./source-spec.mjs";
+import { sameIdentity, validateRepositoryIdentity } from "./portable-identity.mjs";
+import { validateOrigin } from "./resolution-shape.mjs";
+import { createSourceProjection, validateProjectionPath } from "./source-projection.mjs";
+export { validateProjectionPath } from "./source-projection.mjs";
+import { oatsError } from "./errors.mjs";
+
+function githubCoordinates(url) {
+  let host, path;
+  if (url.includes("://")) { const parsed = new URL(url); host = parsed.hostname; path = parsed.pathname.slice(1); }
+  else { const match = /^[^@]+@([^:]+):(.+)$/.exec(url); if (!match) return null; [, host, path] = match; }
+  if (host.toLowerCase() !== "github.com") return null;
+  const parts = path.replace(/\.git$/, "").split("/");
+  if (parts.length !== 2 || parts.some((part) => !/^[A-Za-z0-9_.-]+$/.test(part))) throw oatsError("source-identity-unresolved", "GitHub repository locator cannot be qualified");
+  return { host: "github.com", owner: parts[0], name: parts[1] };
+}
+
+/** Native host credentials only; no token extraction, copying or fallback after
+ * a GitHub identity lookup fails. Unsupported hosts use explicit remote identity. */
+export function readHostingIdentity(repository, { environment = process.env, expectedIdentity } = {}) {
+  if (expectedIdentity?.kind === "canonical-remote") return { identity: { kind: "canonical-remote", remote: repository.normalized } };
+  const coordinates = githubCoordinates(repository.url);
+  if (!coordinates) return { identity: { kind: "canonical-remote", remote: repository.normalized } };
+  let metadata;
+  try {
+    const output = execFileSync("gh", ["api", "--hostname", coordinates.host, `repos/${coordinates.owner}/${coordinates.name}`,
+      "--jq", "{id, full_name, default_branch}"], { env: environment, timeout: 30_000, maxBuffer: 64 * 1024, stdio: ["ignore", "pipe", "pipe"] });
+    metadata = parseStrictJson(output);
+  } catch { throw oatsError("source-identity-unresolved", "repository hosting identity is unavailable in the selected access context"); }
+  if (!Number.isSafeInteger(metadata.id) || metadata.id < 1 || typeof metadata.full_name !== "string") throw oatsError("source-identity-unresolved", "hosting response lacks a stable repository identity");
+  if (metadata.full_name.toLowerCase() !== `${coordinates.owner}/${coordinates.name}`.toLowerCase()) throw oatsError("source-identity-change", "repository redirect or rename requires an explicit identity mapping");
+  revisionSelector(metadata.default_branch);
+  return { identity: { kind: "provider-repository", provider: "github", host: coordinates.host, id: String(metadata.id) }, defaultBranch: metadata.default_branch };
+}
+
+function gitEnvironment(environment) {
+  const out = { ...environment };
+  // Keep native credential/SSH facilities, but never an invoking repository's
+  // object/index/config injection. Host HOME/config credentials remain host-owned.
+  const retained = new Set(["GIT_ASKPASS", "GIT_SSH", "GIT_SSH_COMMAND", "GIT_SSH_VARIANT", "GIT_CONFIG_GLOBAL", "GIT_CONFIG_SYSTEM", "GIT_CONFIG_NOSYSTEM"]);
+  for (const key of Object.keys(out)) if (key.startsWith("GIT_") && !retained.has(key)) delete out[key];
+  out.GIT_TERMINAL_PROMPT = "0"; out.GIT_LITERAL_PATHSPECS = "1"; out.GIT_NO_REPLACE_OBJECTS = "1";
+  return out;
+}
+
+export function createRepositoryTransaction({ directory, accessContextKey, environment = process.env, identityReader = readHostingIdentity, allowLocalGit = false,
+  maxRepositories = 32, maxEntries = 10_000, maxBytes = 256 * 1024 * 1024 } = {}) {
+  if (typeof directory !== "string" || !isAbsolute(directory) || typeof accessContextKey !== "string" || !accessContextKey) throw oatsError("invalid-source", "repository observation requires an explicit scratch directory and access context");
+  canonicalJson(accessContextKey, { maxBytes: 8192 });
+  for (const value of [maxRepositories, maxEntries, maxBytes]) if (!Number.isSafeInteger(value) || value < 1) throw oatsError("resource-limit", "invalid repository observation budget");
+  const parent = realpathSync(directory);
+  if (!lstatSync(parent).isDirectory()) throw oatsError("invalid-source", "repository observation scratch root is not a directory");
+  const root = mkdtempSync(join(parent, ".repository-transaction-")), owned = lstatSync(root), hooks = join(root, "empty-hooks");
+  mkdirSync(hooks, { mode: 0o700 });
+  const env = gitEnvironment(environment), memo = new Map(), snapshots = new Map(), hosts = new Map(), defaults = new Map(), handles = new WeakMap(), blobs = new Map();
+  let closed = false, readBytes = 0, entriesRead = 0;
+  const active = () => { if (closed) throw oatsError("source-unavailable", "repository transaction is closed"); };
+  const git = (args, limit = 1024 * 1024) => {
+    active();
+    try { return execFileSync("git", ["-c", `core.hooksPath=${hooks}`, "-c", "protocol.ext.allow=never", "-c", `protocol.file.allow=${allowLocalGit ? "always" : "never"}`,
+      "-c", "http.followRedirects=false", ...args], { cwd: root, env, timeout: 60_000, maxBuffer: limit, stdio: ["ignore", "pipe", "pipe"] }); }
+    catch (error) { throw oatsError(error.code === "ENOBUFS" ? "resource-limit" : "source-unavailable", "repository read failed in the selected access context"); }
+  };
+  const hostFor = (repository, expectedIdentity) => {
+    if (!hosts.has(repository.normalized)) {
+      if (hosts.size >= maxRepositories * 4) throw oatsError("resource-limit", "repository identity count exceeded");
+      try {
+        const response = identityReader(repository, { environment: env, expectedIdentity });
+        validateRepositoryIdentity(response.identity);
+        if (response.defaultBranch !== undefined) revisionSelector(response.defaultBranch);
+        hosts.set(repository.normalized, { value: freezeJson({ identity: structuredClone(response.identity),
+          ...(response.defaultBranch === undefined ? {} : { defaultBranch: response.defaultBranch }) }) });
+      } catch (error) { hosts.set(repository.normalized, { error }); }
+    }
+    const hosted = hosts.get(repository.normalized);
+    if (hosted.error) throw hosted.error;
+    const host = hosted.value;
+    if (host.identity.kind === "canonical-remote" && host.identity.remote !== repository.normalized) throw oatsError("source-identity-change", "canonical repository identity differs from its source");
+    if (expectedIdentity && !sameIdentity(host.identity, expectedIdentity)) throw oatsError("source-identity-change", "repository hosting identity changed");
+    const identityKey = canonicalJson(host.identity);
+    if (host.defaultBranch !== undefined && !defaults.has(identityKey)) defaults.set(identityKey, { selector: host.defaultBranch });
+    return host;
+  };
+  const dataFor = (observation) => {
+    active(); const data = handles.get(observation);
+    if (!data) throw oatsError("invalid-source", "repository observation was not issued by this transaction");
+    return data;
+  };
+  const list = (data, paths, recursive) => {
+    const args = ["-C", data.directory, "ls-tree", "-z", "--full-tree", ...(recursive ? ["-r"] : []), data.commit];
+    if (!paths.includes(".")) args.push("--", ...paths);
+    const rows = decodeUtf8(git(args, 16 * 1024 * 1024)).split("\0").filter(Boolean);
+    if ((entriesRead += rows.length) > maxEntries) throw oatsError("resource-limit", "repository entry budget exceeded");
+    return rows.map((row) => {
+      const at = row.indexOf("\t"), header = /^([0-7]{6}) (blob|tree|commit) ([a-f0-9]{40})$/.exec(row.slice(0, at)), path = row.slice(at + 1);
+      if (!header || at < 0) throw oatsError("invalid-source", "repository returned a malformed tree entry");
+      portablePath(path);
+      if (path.split("/").some((part) => part.toLowerCase() === ".git")) throw oatsError("resource-not-contained", "source projection cannot include Git administrative files");
+      if (!paths.some((root) => root === "." || path === root || path.startsWith(`${root}/`))) throw oatsError("resource-not-contained", "repository returned an unselected source path");
+      return { mode: header[1], type: header[2], object: header[3], path };
+    });
+  };
+  const blob = (data, entry, limit) => {
+    if (entry.type !== "blob") throw oatsError("source-incomplete", "selected source contains an unsupported submodule or object kind");
+    const key = `${data.directory}:${entry.object}`;
+    if (!blobs.has(key)) {
+      const sizeText = decodeUtf8(git(["-C", data.directory, "cat-file", "-s", entry.object], 1024)).trim();
+      const size = Number(sizeText);
+      if (!/^[0-9]+$/.test(sizeText) || !Number.isSafeInteger(size) || size > limit || readBytes + size > maxBytes) throw oatsError("resource-limit", "repository content byte budget exceeded");
+      const bytes = git(["-C", data.directory, "cat-file", "blob", entry.object], size + 1024);
+      if (bytes.length !== size) throw oatsError("integrity-drift", "repository blob changed during reading");
+      readBytes += size; blobs.set(key, bytes);
+    }
+    const bytes = blobs.get(key);
+    if (bytes.length > limit) throw oatsError("resource-limit", "repository descriptor byte limit exceeded");
+    return Buffer.from(bytes);
+  };
+
+  return {
+    identify(source, { expectedIdentity } = {}) {
+      active();
+      if (expectedIdentity !== undefined) validateRepositoryIdentity(expectedIdentity);
+      const repository = parseRepositorySource(source), host = hostFor(repository, expectedIdentity);
+      return Object.freeze({ identity: host.identity, source: repository.normalized, accessContextKey });
+    },
+    observe(source, { revision, origin, expectedIdentity } = {}) {
+      active(); validateOrigin(origin);
+      if (expectedIdentity !== undefined) validateRepositoryIdentity(expectedIdentity);
+      // Local working snapshots use path: custody, not portable file: identities.
+      // allowLocalGit only enables an explicit host/test transport mapping.
+      const repository = parseRepositorySource(source);
+      if (revision !== undefined) revisionSelector(revision);
+      const key = canonicalJson({ source: repository.normalized, selector: revision ?? null });
+      if (!memo.has(key)) {
+        if (memo.size >= maxRepositories * 4) throw oatsError("resource-limit", "repository request count exceeded");
+        // Cache failures too: a single transaction never re-observes a moving
+        // request because its first attempt was inconvenient or inaccessible.
+        const slot = {}; memo.set(key, slot);
+        try {
+          const host = hostFor(repository, expectedIdentity), identityKey = canonicalJson(host.identity);
+          let selector = revision ?? defaults.get(identityKey)?.selector, exactHead = revision === undefined ? defaults.get(identityKey)?.exactHead : undefined;
+          if (selector === undefined) {
+            const head = decodeUtf8(git(["ls-remote", "--symref", "--", repository.url, "HEAD"], 64 * 1024));
+            const symbolic = /^ref: refs\/heads\/(.+)\tHEAD$/m.exec(head), resolved = /^([a-f0-9]{40})\tHEAD$/m.exec(head);
+            if (!symbolic || !resolved) throw oatsError("source-identity-unresolved", "repository default branch is unavailable");
+            selector = symbolic[1]; exactHead = resolved[1];
+            defaults.set(identityKey, { selector, exactHead });
+          }
+          revisionSelector(selector);
+          const snapshotKey = canonicalJson({ identity: host.identity, selector });
+          if (snapshots.has(snapshotKey)) {
+            const existing = snapshots.get(snapshotKey);
+            if (existing.error) throw existing.error;
+            slot.data = existing.data;
+          } else {
+            if (snapshots.size >= maxRepositories) throw oatsError("resource-limit", "repository snapshot count exceeded");
+            const directory = join(root, `repository-${snapshots.size}.git`);
+            snapshots.set(snapshotKey, slot);
+            // One selected shallow snapshot, not all repository branches/history.
+            // Servers may decline filtering; budgets below bound selected reads,
+            // not the transport's pack size. Git/host resource limits still apply.
+            git(["init", "--quiet", "--bare", directory]);
+            git(["-C", directory, "remote", "add", "origin", repository.url]);
+            git(["-C", directory, "fetch", "--quiet", "--depth=1", "--filter=blob:none", "--no-tags", "--", "origin", exactHead ?? selector], 4 * 1024 * 1024);
+            const commit = decodeUtf8(git(["-C", directory, "rev-parse", "--verify", "--quiet", "--end-of-options", "FETCH_HEAD^{commit}"], 1024)).trim();
+            if (exactHead && commit !== exactHead) throw oatsError("integrity-drift", "fetched default branch differs from its exact observation");
+            if (!/^[a-f0-9]{40}$/.test(commit)) throw oatsError("source-identity-unresolved", "repository selector did not resolve to an exact commit");
+            slot.data = { directory, identity: Object.freeze({ ...host.identity }), selector, commit };
+          }
+        } catch (error) { slot.error = error; throw error; }
+      }
+      const slot = memo.get(key);
+      if (slot.error) throw slot.error;
+      const data = { ...slot.data, remote: repository.normalized };
+      if (expectedIdentity && !sameIdentity(data.identity, expectedIdentity)) throw oatsError("source-identity-change", "cached repository identity differs from the request");
+      const observation = Object.freeze({ schemaVersion: 1, source: Object.freeze({ identity: data.identity, remote: data.remote,
+        selector: data.selector, commit: data.commit, provenance: freezeJson([structuredClone(origin)]) }), accessContextKey });
+      handles.set(observation, data);
+      return observation;
+    },
+    readFile(observation, path, { optional = false } = {}) {
+      portablePath(path); const data = dataFor(observation), rows = list(data, [path], false);
+      if (!rows.length && optional) return null;
+      if (rows.length !== 1 || rows[0].path !== path || !["100644", "100755"].includes(rows[0].mode)) throw oatsError("export-not-found", "repository descriptor is absent or is not a regular file");
+      const bytes = blob(data, rows[0], 1024 * 1024);
+      return { bytes, origin: { kind: "source", source: data.remote, revision: data.commit, path, integrity: bytesIntegrity(bytes) } };
+    },
+    materialize(observation, roots, destination) {
+      const data = dataFor(observation);
+      canonicalJson(roots);
+      if (!Array.isArray(roots) || !roots.length || roots.length > 1024 || new Set(roots).size !== roots.length) throw oatsError("invalid-source", "source projection needs a bounded unique root set");
+      roots.forEach((path) => portablePath(path, { allowRoot: true }));
+      if (typeof destination !== "string" || !isAbsolute(destination)) throw oatsError("invalid-source", "source projection destination must be explicit");
+      const rows = list(data, roots, true);
+      for (const path of roots) if (!rows.some((row) => path === "." || row.path === path || row.path.startsWith(`${path}/`))) throw oatsError("export-not-found", "required source projection root is absent");
+      for (const entry of rows) validateProjectionPath(entry.path);
+      const expected = new Map(rows.map((entry) => [entry.path, entry]));
+      if (expected.size !== rows.length) throw oatsError("invalid-source", "source tree has duplicate paths");
+      const projection = createSourceProjection(destination);
+      try {
+        for (const entry of rows) {
+          const bytes = blob(data, entry, maxBytes);
+          if (entry.mode === "120000") projection.link(entry.path, decodeUtf8(bytes, "source link target"));
+          else if (["100644", "100755"].includes(entry.mode)) projection.file(entry.path, bytes, entry.mode === "100755" ? 0o755 : 0o644);
+          else throw oatsError("source-incomplete", "source object mode cannot be retained");
+        }
+        projection.finish();
+        return { directory: destination, roots: [...roots], observation };
+      } catch (error) { error.stagingPath = destination; throw error; }
+    },
+    close() {
+      if (closed) return;
+      const current = lstatSync(root);
+      if (!current.isDirectory() || current.dev !== owned.dev || current.ino !== owned.ino) throw oatsError("source-unavailable", "repository transaction cleanup lost ownership");
+      closed = true;
+      rmSync(root, { recursive: true });
+    },
+  };
+}