@mannyc1/ts-release 0.0.6 → 0.2.2

package/src/release/prepared.ts

@@ -0,0 +1,299 @@
+import * as Schema from "effect/Schema"
+import { encodeCanonicalJson, parseStrictJson } from "../model/canonical.js"
+import {
+  ArtifactCollectionContract,
+  ArtifactCollectionMember,
+  cardinalityAccepts,
+  cardinalityIssue,
+  collectionContractIssue,
+  collectionMemberId,
+  collectionMemberPath
+} from "../model/artifact-collection.js"
+import { Sha256Digest } from "../model/digest.js"
+import {
+  CatalogRepositoryPath,
+  GitBranchName,
+  GitHubRepositoryCoordinate,
+  PreparedCatalogRenderer
+} from "../model/catalog.js"
+import { PythonDistribution } from "../model/python-distribution.js"
+import { NonEmptyName, OutputId, SafeRelativePath, Version } from "../model/primitives.js"
+import { ExplicitInputSnapshot, StagingSnapshot } from "./context.js"
+import {
+  CanonicalNpmRegistryEndpoint,
+  NpmAccess,
+  NpmAuthentication,
+  NpmDistTag,
+  NpmProvenancePolicy,
+  PyPiAuthentication,
+  PyPiProjectName,
+  PyPiRepository
+} from "../recipes/config.js"
+import {
+  PublicationAuthorityIntent,
+  catalogPublicationAuthorityIssue,
+  githubPublicationAuthorityIssue,
+  npmPublicationAuthorityIssue,
+  pyPiPublicationAuthorityIssue
+} from "./graph.js"
+
+const optional = Schema.optionalKey
+const artifactKind = Schema.Literals(["file", "executable", "archive", "package", "digest"])
+
+export class PreparedSource extends Schema.Class<PreparedSource>("PreparedSource")({
+  commit: NonEmptyName, tree: NonEmptyName, clean: Schema.Literal(true),
+  packageManifestPath: SafeRelativePath, packageManifestDigest: Sha256Digest,
+  materialized: StagingSnapshot
+}) {}
+
+export class PreparedProject extends Schema.Class<PreparedProject>("PreparedProject")({
+  name: NonEmptyName, packageName: optional(NonEmptyName), version: Version, tag: NonEmptyName,
+  repository: optional(Schema.NonEmptyString)
+}) {}
+
+export class PreparedArtifact extends Schema.Class<PreparedArtifact>("PreparedArtifact")({
+  id: OutputId, path: SafeRelativePath, kind: artifactKind, size: Schema.Number.check(
+    Schema.makeFilter((value: number) => Number.isSafeInteger(value) && value >= 0
+      ? undefined : "Prepared artifact size must be a nonnegative safe integer.")
+  ), digest: Sha256Digest, blob: Sha256Digest, mediaType: optional(Schema.NonEmptyString),
+  producer: NonEmptyName,
+  inputBasis: Sha256Digest
+}) {}
+
+/** Durable collection provenance; the graph itself remains ephemeral. */
+export class PreparedArtifactCollection
+  extends Schema.Class<PreparedArtifactCollection>("PreparedArtifactCollection")({
+    contract: ArtifactCollectionContract,
+    members: Schema.Array(ArtifactCollectionMember)
+  }) {}
+
+export class PreparedExecutionInputs extends Schema.Class<PreparedExecutionInputs>("PreparedExecutionInputs")({
+  environment: Schema.Literal("closed"),
+  network: Schema.Literal("prohibited"),
+  timezone: Schema.Literal("UTC"),
+  locale: Schema.Literal("C"),
+  clock: Schema.Literal("source-date-epoch=0;host-clock-not-isolated"),
+  randomness: Schema.Literal("host-randomness-not-isolated"),
+  platform: Schema.NonEmptyString,
+  runtime: Schema.NonEmptyString,
+  networkIsolation: Schema.NonEmptyString,
+  bunCompileRuntimes: Schema.NonEmptyString,
+  npmPack: Schema.NonEmptyString,
+  releaseGraph: Sha256Digest,
+  preparer: Schema.NonEmptyString
+}) {}
+
+export class PreparedProvenance extends Schema.Class<PreparedProvenance>("PreparedProvenance")({
+  source: StagingSnapshot,
+  externalInputs: Schema.Array(ExplicitInputSnapshot),
+  execution: PreparedExecutionInputs,
+  inputBasis: Sha256Digest,
+  reproducibility: Schema.Literal("not-asserted")
+}) {}
+
+export class PreparedNpmPublication extends Schema.TaggedClass<PreparedNpmPublication>()("PreparedNpmPublication", {
+  id: NonEmptyName,
+  artifactId: OutputId,
+  packageName: NonEmptyName,
+  version: Version,
+  registryUrl: CanonicalNpmRegistryEndpoint,
+  distTag: NpmDistTag,
+  access: NpmAccess,
+  authentication: NpmAuthentication,
+  provenance: NpmProvenancePolicy,
+  authority: PublicationAuthorityIntent
+}) {}
+
+export class PreparedGitHubAsset extends Schema.Class<PreparedGitHubAsset>("PreparedGitHubAsset")({
+  artifactId: OutputId, name: Schema.NonEmptyString, mediaType: Schema.NonEmptyString
+}) {}
+
+export class PreparedGitHubPublication extends Schema.TaggedClass<PreparedGitHubPublication>()("PreparedGitHubPublication", {
+  id: NonEmptyName, repository: Schema.NonEmptyString, tag: NonEmptyName, title: NonEmptyName,
+  draft: Schema.Boolean, prerelease: Schema.Boolean, targetCommit: NonEmptyName, body: optional(Schema.String),
+  assets: Schema.Array(PreparedGitHubAsset), authority: PublicationAuthorityIntent
+}) {}
+
+export class PreparedPyPiFile extends Schema.Class<PreparedPyPiFile>("PreparedPyPiFile")({
+  artifactId: OutputId,
+  filename: NonEmptyName,
+  size: Schema.Number.check(Schema.makeFilter((value: number) =>
+    Number.isSafeInteger(value) && value >= 0 ? undefined : "PyPI file size must be a nonnegative safe integer.")),
+  sha256: Sha256Digest,
+  mediaType: Schema.Literals(["application/zip", "application/gzip"]),
+  distribution: PythonDistribution,
+  authority: PublicationAuthorityIntent
+}) {}
+
+export class PreparedPyPiPublication extends Schema.TaggedClass<PreparedPyPiPublication>()("PreparedPyPiPublication", {
+  id: NonEmptyName,
+  project: PyPiProjectName,
+  version: Version,
+  repository: PyPiRepository,
+  simpleBaseUrl: Schema.NonEmptyString,
+  projectUrl: Schema.NonEmptyString,
+  uploadUrl: Schema.NonEmptyString,
+  authentication: PyPiAuthentication,
+  files: Schema.NonEmptyArray(PreparedPyPiFile)
+}) {}
+
+export class PreparedCatalogPublication
+  extends Schema.TaggedClass<PreparedCatalogPublication>()("PreparedCatalogPublication", {
+    id: NonEmptyName,
+    catalogId: NonEmptyName,
+    targetArtifactId: OutputId,
+    stateArtifactId: OutputId,
+    targetDigest: Sha256Digest,
+    stateDigest: Sha256Digest,
+    repository: GitHubRepositoryCoordinate,
+    branch: GitBranchName,
+    targetPath: CatalogRepositoryPath,
+    statePath: CatalogRepositoryPath,
+    version: Version,
+    sourceRepository: GitHubRepositoryCoordinate,
+    sourceTag: NonEmptyName,
+    renderer: PreparedCatalogRenderer,
+    authority: PublicationAuthorityIntent
+  }) {}
+
+const PreparedPublicationVariants = Schema.Union([
+  PreparedNpmPublication, PreparedPyPiPublication, PreparedGitHubPublication, PreparedCatalogPublication
+])
+export const PreparedPublication = PreparedPublicationVariants.pipe(Schema.check(
+  Schema.makeFilter((publication) => publication._tag === "PreparedNpmPublication"
+    ? npmPublicationAuthorityIssue(publication)
+    : publication._tag === "PreparedPyPiPublication"
+    ? pyPiPublicationAuthorityIssue(publication)
+    : publication._tag === "PreparedGitHubPublication"
+    ? githubPublicationAuthorityIssue(publication)
+    : catalogPublicationAuthorityIssue(publication))
+))
+export type PreparedPublication = typeof PreparedPublication.Type
+
+export class PreparedReleaseV2 extends Schema.Class<PreparedReleaseV2>("PreparedReleaseV2")({
+  kind: Schema.Literal("complete"),
+  schemaVersion: Schema.Literal("prepared-release/v2"), source: PreparedSource, project: PreparedProject,
+  provenance: PreparedProvenance,
+  artifacts: Schema.Array(PreparedArtifact),
+  collections: Schema.Array(PreparedArtifactCollection),
+  publications: Schema.Array(PreparedPublication)
+}) {}
+
+export class PreparedManifestError
+  extends Schema.TaggedErrorClass<PreparedManifestError>()("PreparedManifestError", {
+    reason: Schema.String
+  }) {}
+
+const assertCompletePreparedRelease = (manifest: PreparedReleaseV2): void => {
+  if (manifest.kind !== "complete") throw new Error("prepared manifest kind must be 'complete'")
+  if (manifest.source.materialized.digest.hex !== manifest.provenance.source.digest.hex) {
+    throw new Error("prepared source materialization must match provenance source")
+  }
+  for (const publication of manifest.publications) {
+    if (publication._tag === "PreparedNpmPublication" &&
+      publication.authority.publishStrategy.kind === "trusted-publishing" &&
+      publication.authority.publishStrategy.sourceCommit.toString() !== manifest.source.commit.toString()) {
+      throw new Error(`prepared npm publication ${publication.id} source commit disagrees with the verified source`)
+    }
+    if (publication._tag === "PreparedPyPiPublication" &&
+      publication.authentication.strategy === "trusted-publishing" &&
+      publication.files.some((file) => file.authority.publishStrategy.kind !== "trusted-publishing" ||
+        file.authority.publishStrategy.sourceCommit.toString() !== manifest.source.commit.toString())) {
+      throw new Error(`prepared PyPI publication ${publication.id} source commit disagrees with the verified source`)
+    }
+  }
+  for (const artifact of manifest.artifacts) {
+    if (artifact.inputBasis.hex !== manifest.provenance.inputBasis.hex) {
+      throw new Error(`prepared artifact ${artifact.id} has a foreign input basis`)
+    }
+  }
+  const artifacts = new Map(manifest.artifacts.map((artifact) => [artifact.id.toString(), artifact]))
+  for (const publication of manifest.publications) {
+    if (publication._tag !== "PreparedCatalogPublication") continue
+    const target = artifacts.get(publication.targetArtifactId.toString())
+    const state = artifacts.get(publication.stateArtifactId.toString())
+    if (target === undefined || state === undefined || target.digest.hex !== publication.targetDigest.hex ||
+        state.digest.hex !== publication.stateDigest.hex || target.kind !== "file" || state.kind !== "file") {
+      throw new Error(`prepared catalog publication ${publication.id} does not bind its exact target/state artifacts`)
+    }
+  }
+  const collectionIds = new Set<string>()
+  const collectionRoots = new Map<string, string>()
+  const collectionProducers = new Set<string>()
+  const memberArtifacts = new Set<string>()
+  let previousCollection = ""
+  for (const collection of manifest.collections) {
+    const { contract } = collection
+    const id = contract.id.toString()
+    if (id <= previousCollection) throw new Error("prepared artifact collections must have unique code-point-sorted ids")
+    previousCollection = id
+    const foldedId = id.toLocaleLowerCase("en-US")
+    if (collectionIds.has(foldedId)) throw new Error(`prepared artifact collection ${id} has a case-colliding id`)
+    collectionIds.add(foldedId)
+    const foldedRoot = contract.root.toString().toLocaleLowerCase("en-US")
+    const overlappingRoot = [...collectionRoots.entries()].find(([root]) =>
+      foldedRoot === root || foldedRoot.startsWith(`${root}/`) || root.startsWith(`${foldedRoot}/`))
+    if (overlappingRoot !== undefined) {
+      throw new Error(`prepared artifact collection ${id} root overlaps collection ${overlappingRoot[1]}`)
+    }
+    collectionRoots.set(foldedRoot, id)
+    if (collectionProducers.has(contract.producer.toString())) {
+      throw new Error(`prepared artifact collection ${id} repeats producer ${contract.producer}`)
+    }
+    collectionProducers.add(contract.producer.toString())
+    const issue = cardinalityIssue(contract.cardinality)
+    if (issue !== undefined) throw new Error(`prepared artifact collection ${id}: ${issue}`)
+    const contractIssue = collectionContractIssue(contract)
+    if (contractIssue !== undefined) throw new Error(`prepared artifact collection ${id}: ${contractIssue}`)
+    if (!cardinalityAccepts(contract.cardinality, collection.members.length)) {
+      throw new Error(`prepared artifact collection ${id} has ${collection.members.length} members outside its declared cardinality`)
+    }
+    const keys = new Set<string>()
+    let previousKey = ""
+    for (const member of collection.members) {
+      const key = member.key.toString()
+      if (key <= previousKey) throw new Error(`prepared artifact collection ${id} member keys must be unique and code-point sorted`)
+      previousKey = key
+      const foldedKey = key.toLocaleLowerCase("en-US")
+      if (keys.has(foldedKey)) throw new Error(`prepared artifact collection ${id} has duplicate normalized member key ${key}`)
+      keys.add(foldedKey)
+      const expectedId = collectionMemberId(contract, member.key)
+      if (member.artifactId !== expectedId) throw new Error(`prepared artifact collection ${id} member ${key} has an invalid stable artifact id`)
+      const artifact = artifacts.get(member.artifactId.toString())
+      if (artifact === undefined) throw new Error(`prepared artifact collection ${id} member ${key} references no artifact`)
+      if (artifact.path !== collectionMemberPath(contract, member.key) || artifact.kind !== contract.artifactKind ||
+          artifact.mediaType !== contract.mediaType || artifact.producer.toString() !== contract.producer.toString()) {
+        throw new Error(`prepared artifact collection ${id} member ${key} disagrees with its contract`)
+      }
+      if (memberArtifacts.has(member.artifactId.toString())) {
+        throw new Error(`prepared artifact ${member.artifactId} belongs to more than one collection`)
+      }
+      memberArtifacts.add(member.artifactId.toString())
+    }
+  }
+  for (const artifact of manifest.artifacts) {
+    if (collectionProducers.has(artifact.producer.toString()) && !memberArtifacts.has(artifact.id.toString())) {
+      throw new Error(`prepared collection producer ${artifact.producer} has unclaimed artifact ${artifact.id}`)
+    }
+  }
+}
+
+export const encodePreparedRelease = (manifest: PreparedReleaseV2): Uint8Array => {
+  assertCompletePreparedRelease(manifest)
+  return new TextEncoder().encode(encodeCanonicalJson(Schema.encodeSync(PreparedReleaseV2)(manifest)))
+}
+
+export const decodePreparedRelease = (bytes: Uint8Array): PreparedReleaseV2 => {
+  try {
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes)
+    const value = Schema.decodeUnknownSync(PreparedReleaseV2, { onExcessProperty: "error" })(parseStrictJson(text))
+    assertCompletePreparedRelease(value)
+    const canonical = encodePreparedRelease(value)
+    if (canonical.length !== bytes.length || canonical.some((byte, index) => byte !== bytes[index])) {
+      throw new Error("manifest bytes are not canonical")
+    }
+    return value
+  } catch (cause) {
+    throw PreparedManifestError.make({ reason: cause instanceof Error ? cause.message : String(cause) })
+  }
+}

package/src/release/staging.ts

@@ -0,0 +1,257 @@
+import {
+  constants,
+  copyFileSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readlinkSync,
+  readdirSync,
+  realpathSync,
+  symlinkSync
+} from "node:fs"
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
+import { encodeCanonicalJson } from "../model/canonical.js"
+import { sha256Digest, type Sha256Digest } from "../model/digest.js"
+import { SafeRelativePath } from "../model/primitives.js"
+import {
+  ExplicitInputSnapshot,
+  StagingEntry,
+  StagingSnapshot
+} from "./context.js"
+
+const utf8 = new TextEncoder()
+const byCodepoint = (left: string, right: string): number => left < right ? -1 : left > right ? 1 : 0
+
+const fail = (reason: string): never => { throw new Error(reason) }
+
+/** Paths in staging manifests are portable POSIX-style relative paths. */
+export const canonicalStagingPath = (value: string): SafeRelativePath => {
+  const path = value.split(sep).join("/")
+  if (path === "." || path.includes("\\") || path.includes("\0") ||
+      path.split("/").some((part) => part.length === 0 || part === "." || part === "..")) {
+    return fail(`Staging path ${JSON.stringify(value)} is not canonical and portable.`)
+  }
+  return SafeRelativePath.make(path)
+}
+
+const lexicalContainment = (root: string, candidate: string): boolean => {
+  const path = relative(root, candidate)
+  return path === "" || (path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path))
+}
+
+const relativePath = (root: string, path: string): SafeRelativePath => canonicalStagingPath(relative(root, path))
+
+const entryDigest = (kind: StagingEntry["kind"], path: string): { readonly digest: ReturnType<typeof sha256Digest>, readonly size: number } => {
+  if (kind === "directory") return { digest: sha256Digest(utf8.encode("")), size: 0 }
+  const bytes = kind === "symlink" ? utf8.encode(readlinkSync(path)) : new Uint8Array(readFileSync(path))
+  return { digest: sha256Digest(bytes), size: bytes.length }
+}
+
+const assertSafeSymlink = (root: string, path: string): void => {
+  const target = readlinkSync(path)
+  if (target.length === 0 || isAbsolute(target)) fail(`Staging symlink ${relative(root, path)} has an absolute or empty target.`)
+  const landed = resolve(dirname(path), target)
+  if (!lexicalContainment(root, landed)) fail(`Staging symlink ${relative(root, path)} escapes the private root.`)
+  if (!existsSync(landed)) fail(`Staging symlink ${relative(root, path)} is dangling.`)
+  const real = realpathSync(path)
+  if (!lexicalContainment(root, real)) fail(`Staging symlink ${relative(root, path)} resolves outside the private root.`)
+}
+
+const isExcluded = (path: string, excluded: ReadonlyArray<string>): boolean =>
+  excluded.some((root) => path === root || path.startsWith(`${root}/`))
+
+const isExcludedAncestor = (path: string, excluded: ReadonlyArray<string>): boolean =>
+  excluded.some((root) => root.startsWith(`${path}/`))
+
+export interface SnapshotOptions {
+  /** Canonical roots omitted from a mutation comparison (declared outputs and scratch only). */
+  readonly exclude?: ReadonlyArray<SafeRelativePath | string>
+}
+
+/** Canonical path/type/digest manifest for a private staging tree. */
+export const snapshotStaging = (rootValue: string, options: SnapshotOptions = {}): StagingSnapshot => {
+  const root = realpathSync(rootValue)
+  if (lstatSync(root).isSymbolicLink() || !lstatSync(root).isDirectory()) fail("Staging root must be a real directory.")
+  const excluded = (options.exclude ?? []).map(String).sort(byCodepoint)
+  const entries: StagingEntry[] = []
+  const folded = new Map<string, string>()
+  const walk = (directory: string): void => {
+    for (const child of readdirSync(directory, { withFileTypes: true }).sort((left, right) => byCodepoint(left.name, right.name))) {
+      const path = join(directory, child.name)
+      const name = relativePath(root, path).toString()
+      if (isExcluded(name, excluded)) continue
+      const collision = folded.get(name.toLocaleLowerCase("en-US"))
+      if (collision !== undefined && collision !== name) fail(`Staging paths ${collision} and ${name} collide under case folding.`)
+      folded.set(name.toLocaleLowerCase("en-US"), name)
+      const stat = lstatSync(path)
+      const kind: StagingEntry["kind"] = stat.isSymbolicLink()
+        ? "symlink"
+        : stat.isDirectory()
+        ? "directory"
+        : stat.isFile()
+        ? (stat.mode & 0o111) === 0 ? "file" : "executable"
+        : fail(`Staging path ${name} has an unsupported filesystem kind.`)
+      if (kind === "symlink") assertSafeSymlink(root, path)
+      const value = entryDigest(kind, path)
+      // Ancestor directories of an excluded writable root are traversal-only:
+      // creating `.release` in order to create `.release/assets` must not look
+      // like an undeclared mutation, while siblings under `.release` remain
+      // fully snapshotted and protected.
+      if (!(kind === "directory" && isExcludedAncestor(name, excluded))) {
+        entries.push(StagingEntry.make({
+          path: canonicalStagingPath(name),
+          kind,
+          mode: kind === "executable" ? 0o755 : kind === "directory" ? 0o755 : kind === "symlink" ? 0o777 : 0o644,
+          size: value.size,
+          digest: value.digest
+        }))
+      }
+      if (kind === "directory") walk(path)
+    }
+  }
+  walk(root)
+  const canonical = encodeCanonicalJson(entries.map((entry) => ({
+    path: entry.path.toString(), kind: entry.kind, mode: entry.mode, size: entry.size,
+    digest: entry.digest.hex
+  })))
+  return StagingSnapshot.make({ entries, digest: sha256Digest(utf8.encode(canonical)) })
+}
+
+export const snapshotsEqual = (left: StagingSnapshot, right: StagingSnapshot): boolean =>
+  left.digest.hex === right.digest.hex
+
+const snapshotDigest = (entries: ReadonlyArray<StagingEntry>): Sha256Digest => sha256Digest(utf8.encode(encodeCanonicalJson(
+  entries.map((entry) => ({
+    path: entry.path.toString(), kind: entry.kind, mode: entry.mode, size: entry.size,
+    digest: entry.digest.hex
+  }))
+)))
+
+/** Select canonical roots from a whole-stage snapshot without following links again. */
+export const selectStagingSnapshot = (
+  snapshot: StagingSnapshot,
+  roots: ReadonlyArray<SafeRelativePath | string>
+): StagingSnapshot => {
+  const names = roots.map(String)
+  const selected = snapshot.entries.map((entry) => {
+    const root = names.find((candidate) => entry.path.toString().startsWith(`${candidate}/`))
+    if (root === undefined) return undefined
+    const path = canonicalStagingPath(entry.path.toString().slice(root.length + 1))
+    return StagingEntry.make({ ...entry, path })
+  }).filter((entry): entry is StagingEntry => entry !== undefined)
+  return StagingSnapshot.make({ entries: selected, digest: snapshotDigest(selected) })
+}
+
+export const snapshotDifference = (before: StagingSnapshot, after: StagingSnapshot): string => {
+  const left = new Map(before.entries.map((entry) => [entry.path.toString(), entry]))
+  const right = new Map(after.entries.map((entry) => [entry.path.toString(), entry]))
+  const paths = [...new Set([...left.keys(), ...right.keys()])].sort(byCodepoint)
+  const changed = paths.filter((path) => {
+    const a = left.get(path); const b = right.get(path)
+    return a === undefined || b === undefined || a.kind !== b.kind || a.mode !== b.mode ||
+      a.size !== b.size || a.digest.hex !== b.digest.hex
+  })
+  return changed.slice(0, 8).join(", ") + (changed.length > 8 ? ` (+${changed.length - 8} more)` : "")
+}
+
+export const assertSnapshotPresent = (
+  root: string,
+  expected: StagingSnapshot,
+  label: string,
+  options: SnapshotOptions = {}
+): void => {
+  const current = snapshotStaging(root, options)
+  const available = new Map(current.entries.map((entry) => [entry.path.toString(), entry]))
+  const excluded = (options.exclude ?? []).map(String)
+  for (const entry of expected.entries) {
+    if (isExcluded(entry.path.toString(), excluded)) continue
+    const actual = available.get(entry.path.toString())
+    if (actual === undefined || actual.kind !== entry.kind || actual.mode !== entry.mode ||
+        actual.size !== entry.size || actual.digest.hex !== entry.digest.hex) {
+      fail(`${label} changed at ${entry.path}.`)
+    }
+  }
+}
+
+const copyPrivateTree = (sourceRoot: string, destinationRoot: string): void => {
+  const source = realpathSync(sourceRoot)
+  const walk = (from: string, to: string): void => {
+    const stat = lstatSync(from)
+    if (stat.isSymbolicLink()) {
+      const landed = realpathSync(from)
+      if (!lexicalContainment(source, landed)) fail(`Explicit input symlink ${from} escapes its declared root.`)
+      const target = readlinkSync(from)
+      symlinkSync(target, to, stat.isDirectory() ? "dir" : "file")
+      return
+    }
+    if (stat.isDirectory()) {
+      mkdirSync(to, { recursive: false, mode: 0o700 })
+      for (const child of readdirSync(from).sort(byCodepoint)) walk(join(from, child), join(to, child))
+      return
+    }
+    if (!stat.isFile()) fail(`Explicit input ${from} has an unsupported filesystem kind.`)
+    copyFileSync(from, to, constants.COPYFILE_FICLONE)
+  }
+  walk(sourceRoot, destinationRoot)
+  // Re-snapshot to reject copied links that only appeared safe in the source topology.
+  if (lstatSync(destinationRoot).isDirectory()) snapshotStaging(destinationRoot)
+}
+
+/**
+ * Copy/reflink one declared non-Git input into private staging and return the
+ * digest that becomes part of prepared provenance. The destination must not
+ * already exist; source bytes can therefore never overwrite verified Git
+ * materialization.
+ */
+export const materializeExplicitInput = (input: {
+  readonly id: string
+  readonly sourceWorkspace: string
+  readonly stageRoot: string
+  readonly path: SafeRelativePath
+}): ExplicitInputSnapshot => {
+  const sourceRoot = realpathSync(input.sourceWorkspace)
+  const source = join(sourceRoot, input.path.toString())
+  const destination = join(input.stageRoot, input.path.toString())
+  if (!lexicalContainment(sourceRoot, source) || !lexicalContainment(realpathSync(input.stageRoot), destination)) {
+    return fail(`Explicit input ${input.id} escapes its declared root.`)
+  }
+  if (!existsSync(source)) return fail(`Explicit input ${input.id} does not exist at ${input.path}.`)
+  if (existsSync(destination)) return fail(`Explicit input ${input.id} overlaps verified source at ${input.path}.`)
+  mkdirSync(dirname(destination), { recursive: true, mode: 0o700 })
+  const sourceStat = lstatSync(source)
+  if (sourceStat.isSymbolicLink()) return fail(`Explicit input ${input.id} cannot be a symlink.`)
+  copyPrivateTree(source, destination)
+  const kind = sourceStat.isDirectory() ? "directory" : "file"
+  const snapshot = sourceStat.isDirectory() ? snapshotStaging(destination) : undefined
+  const size = sourceStat.isDirectory()
+    ? snapshot!.entries.filter((entry) => entry.kind !== "directory").reduce((sum, entry) => sum + entry.size, 0)
+    : sourceStat.size
+  const digest = sourceStat.isDirectory()
+    ? snapshot!.digest
+    : sha256Digest(new Uint8Array(readFileSync(destination)))
+  return ExplicitInputSnapshot.make({
+    id: input.id,
+    path: input.path,
+    kind,
+    size,
+    digest,
+    materializer: "private-copy-or-reflink/v1",
+    materializationBasis: [digest]
+  })
+}
+
+/** Digest a set of preparation influences without asserting reproducibility. */
+export const preparationBasisDigest = (
+  source: StagingSnapshot,
+  inputs: ReadonlyArray<ExplicitInputSnapshot>,
+  execution: Readonly<Record<string, string>>
+) => sha256Digest(utf8.encode(encodeCanonicalJson({
+  source: source.digest.hex,
+  inputs: [...inputs].sort((left, right) => byCodepoint(left.id, right.id)).map((input) => ({
+    id: input.id, path: input.path.toString(), kind: input.kind, size: input.size, digest: input.digest.hex,
+    materializer: input.materializer,
+    materializationBasis: input.materializationBasis.map((digest) => digest.hex)
+  })),
+  execution
+})))

package/src/resolve/authored.ts

@@ -0,0 +1,64 @@
+// The shape a HUMAN writes. It is the canonical config with the facts a
+// repository already knows made optional, plus the two directives that say how
+// to fill them. Nothing here is inferred at plan time: resolution happens at
+// the application boundary and produces a canonical value before `plan` runs.
+//
+// The field lists are REUSED from the canonical classes, never restated — a
+// hand-mirrored schema is a drift machine.
+import * as Schema from "effect/Schema"
+import { NonEmptyName, Version } from "../model/primitives.js"
+import {
+  CandidateConfig,
+  CandidatePublish,
+  CandidateProject,
+  NpmAccess,
+  NpmAuthentication,
+  NpmProvenancePolicy,
+  PyPiAuthentication,
+  PyPiRepository
+} from "../recipes/config.js"
+
+const optional = Schema.optionalKey
+
+export class AuthoredProject extends Schema.Class<AuthoredProject>("AuthoredProject")({
+  ...CandidateProject.fields,
+  // Filled from the package manifest's name when omitted; still required if
+  // nothing observes one.
+  name: optional(NonEmptyName),
+  // Observed or derived when omitted: version from a manifest or the tag at
+  // HEAD, and tag from the template. Source commit is always observed; a
+  // human-authored commit expectation would only validate and then disappear.
+  version: optional(Version),
+  tag: optional(NonEmptyName),
+  // `{version}` is the only token, and it is the only one this repo will ever
+  // accept: a template grammar is the rejected direction.
+  tagTemplate: optional(Schema.NonEmptyString)
+}) {}
+
+/** Human-authored npm policy. Resolution fills only documented deterministic defaults. */
+export class AuthoredNpmPublish extends Schema.Class<AuthoredNpmPublish>("AuthoredNpmPublish")({
+  registry: optional(Schema.NonEmptyString),
+  distTag: optional(Schema.NonEmptyString),
+  access: optional(NpmAccess),
+  authentication: NpmAuthentication,
+  provenance: optional(NpmProvenancePolicy)
+}) {}
+
+export class AuthoredPyPiPublish extends Schema.Class<AuthoredPyPiPublish>("AuthoredPyPiPublish")({
+  artifacts: Schema.NonEmptyArray(Schema.NonEmptyString),
+  repository: optional(PyPiRepository),
+  authentication: PyPiAuthentication
+}) {}
+
+export class AuthoredPublish extends Schema.Class<AuthoredPublish>("AuthoredPublish")({
+  ...CandidatePublish.fields,
+  npm: optional(AuthoredNpmPublish),
+  pypi: optional(AuthoredPyPiPublish)
+}) {}
+
+export class AuthoredConfig extends Schema.Class<AuthoredConfig>("AuthoredConfig")({
+  ...CandidateConfig.fields,
+  project: AuthoredProject,
+  publish: optional(AuthoredPublish),
+  versionFrom: optional(Schema.Literals(["manifest", "git-tag"]))
+}) {}

package/src/resolve/encode.ts

@@ -0,0 +1,22 @@
+// The reviewable IR's byte shape: readable JSON with sorted keys, so two
+// resolutions of the same inputs produce the same file and a diff shows only
+// what actually changed.
+//
+// This is deliberately NOT the plan-bytes canonical encoder. Canonical encoding
+// is a durable-document discipline that plan identity depends on; this is a
+// convenience artifact that nothing ever reads back.
+// Also the plain-JSON conversion the resolver needs: decoding produces Schema
+// class INSTANCES, and the canonical decoder refuses non-plain objects.
+export const toPlainJson = (value: unknown): unknown => {
+  if (Array.isArray(value)) return value.map(toPlainJson)
+  if (typeof value !== "object" || value === null) return value
+  return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>)
+      .filter(([, entry]) => entry !== undefined)
+      .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+      .map(([key, entry]) => [key, toPlainJson(entry)])
+  )
+}
+
+export const encodeResolvedConfig = (config: unknown): string =>
+  `${JSON.stringify(toPlainJson(config), null, 2)}\n`

package/src/resolve/errors.ts

@@ -0,0 +1,15 @@
+// `resolveConfig` is a PUBLIC boundary function that apps call directly, so its
+// refusals follow the boundary rule SPEC §13 states: a stable plain error
+// carrying a reason, readable as-is when a CLI prints it. (The internal
+// ConfigValueError family is a decode-time vocabulary; its `message` is empty
+// by construction, which would reach a user as a blank line.)
+export class ResolveError extends Error {
+  readonly _tag = "ResolveError"
+  constructor(
+    readonly field: string,
+    readonly reason: string
+  ) {
+    super(reason)
+    this.name = "ResolveError"
+  }
+}

package/src/resolve/facts.ts

@@ -0,0 +1,18 @@
+// What the world can tell us about a release, observed by an app and passed in
+// as a value. The library never looks: no git, no filesystem, no environment —
+// observation is the imperative shell's job, resolution is pure.
+import * as Schema from "effect/Schema"
+import { NonEmptyName, Version } from "../model/primitives.js"
+
+const optional = Schema.optionalKey
+
+export class ObservedFacts extends Schema.Class<ObservedFacts>("ObservedFacts")({
+  commit: optional(NonEmptyName),
+  manifestName: optional(Schema.NonEmptyString),
+  manifestVersion: optional(Version),
+  repository: optional(Schema.NonEmptyString),
+  // The version carried by the single release-shaped tag at HEAD. Ambiguity is
+  // resolved by the observer: several candidate tags means NO fact, so the
+  // resolver refuses instead of picking one.
+  headTagVersion: optional(Version)
+}) {}