@mannyc1/ts-release 0.0.7 → 0.2.2

package/src/correction/coordinator.ts

@@ -0,0 +1,336 @@
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { encodeCanonicalJson } from "../model/canonical.js"
+import { digestEquals, parseSha256Hex, sha256Digest, sha512Digest } from "../model/digest.js"
+import {
+  CatalogManagedState,
+  PreparedCatalogDownload,
+  compareCatalogVersions,
+  decodeCatalogManagedState,
+  encodeCatalogManagedState,
+  renderCatalog
+} from "../model/catalog.js"
+import { SubjectId } from "../model/authority.js"
+import type { CredentialProviderShape } from "../publication/authority.js"
+import { CredentialProvider } from "../publication/authority.js"
+import { publishReleaseSubjects } from "../publication/coordinator.js"
+import type { AuthorizedMutationHttpShape, HttpAuthorizerShape } from "../publication/http.js"
+import { makeCatalogSubject } from "../publication/catalog-git.js"
+import type { ReleaseReport } from "../publication/report.js"
+import {
+  PreparedPublication,
+  encodePreparedRelease,
+  type PreparedPublication as PreparedPublicationType
+} from "../release/prepared.js"
+import type { PreparedBundle } from "../release/prepared-store.js"
+import {
+  type AuthoredCorrection,
+  CorrectionIntentV2,
+  encodeCorrectionIntent,
+  makeCorrectionIntent,
+  type CorrectionIntent,
+  type CatalogForwardCorrection,
+  type GithubReleaseCorrection,
+  type NpmDeprecationCorrection
+} from "./intent.js"
+
+export class CorrectionValidationError
+  extends Schema.TaggedErrorClass<CorrectionValidationError>()("CorrectionValidationError", {
+    reason: Schema.String
+  }) {}
+
+export class CorrectionUnsupported extends Schema.TaggedClass<CorrectionUnsupported>()("CorrectionUnsupported", {
+  provider: Schema.Literals(["npm", "github", "catalog-git"]), reason: Schema.String, evidence: Schema.NonEmptyString,
+  proposal: Schema.optionalKey(Schema.String)
+}) {}
+
+export interface CorrectionExecuted {
+  readonly _tag: "CorrectionExecuted"
+  readonly provider: "catalog-git"
+  readonly report: ReleaseReport
+  readonly reason: string
+  readonly evidence: string
+  readonly proposal: string
+}
+
+export type CorrectionOutcome = typeof CorrectionUnsupported.Type | CorrectionExecuted
+
+const preparedDigest = (bundle: PreparedBundle) => sha256Digest(encodePreparedRelease(bundle.manifest))
+const publicationBaselineDigest = (publication: PreparedPublicationType) => sha256Digest(
+  new TextEncoder().encode(encodeCanonicalJson(Schema.encodeSync(PreparedPublication)(publication)))
+)
+const findPublication = (bundle: PreparedBundle, id: string) => bundle.manifest.publications.find((publication) => publication.id.toString() === id)
+
+const choosePublication = <Tag extends "PreparedNpmPublication" | "PreparedGitHubPublication" | "PreparedCatalogPublication">(
+  bundle: PreparedBundle,
+  tag: Tag,
+  publicationId?: { readonly toString: () => string }
+): Extract<PreparedBundle["manifest"]["publications"][number], { readonly _tag: Tag }> => {
+  const candidates = bundle.manifest.publications.filter((publication): publication is Extract<
+    PreparedBundle["manifest"]["publications"][number],
+    { readonly _tag: Tag }
+  > => publication._tag === tag && (
+    publicationId === undefined || publication.id.toString() === publicationId.toString()
+  ))
+  if (candidates.length !== 1) {
+    throw new Error(publicationId === undefined
+      ? `Authored correction requires exactly one ${tag === "PreparedNpmPublication" ? "npm" : tag === "PreparedGitHubPublication" ? "GitHub" : "catalog Git"} publication; specify publicationId when more than one exists.`
+      : `Authored correction publicationId ${publicationId} does not identify exactly one prepared ${tag === "PreparedNpmPublication" ? "npm" : tag === "PreparedGitHubPublication" ? "GitHub" : "catalog Git"} publication.`)
+  }
+  return candidates[0]!
+}
+
+/** Resolve human intent only after the exact prepared bundle has been loaded. */
+export const bindAuthoredCorrection = (
+  bundle: PreparedBundle,
+  authored: AuthoredCorrection
+): CorrectionIntent => {
+  const digest = preparedDigest(bundle)
+  if (authored.provider === "npm") {
+    const publication = choosePublication(bundle, "PreparedNpmPublication", authored.publicationId)
+    const artifact = bundle.manifest.artifacts.find((candidate) => candidate.id === publication.artifactId)
+    const bytes = artifact === undefined ? undefined : bundle.blobs.get(artifact.id.toString())
+    if (bytes === undefined) throw new Error("Prepared npm correction subject has no verified tarball bytes.")
+    return makeCorrectionIntent({
+      schemaVersion: "correction-intent/v2",
+      preparedDigest: digest,
+      correction: {
+        _tag: "NpmDeprecationCorrection",
+        provider: "npm",
+        publicationId: publication.id,
+        registryUrl: publication.registryUrl,
+        packageName: publication.packageName,
+        version: publication.version,
+        baselineDigest: publicationBaselineDigest(publication),
+        tarballIntegrity: sha512Digest(bytes),
+        message: authored.message,
+        ...(authored.replacement === undefined ? {} : { replacement: authored.replacement })
+      }
+    })
+  }
+  if (authored.provider === "catalog-git") {
+    const publication = choosePublication(bundle, "PreparedCatalogPublication", authored.publicationId)
+    if (compareCatalogVersions(publication.version.toString(), authored.replacementVersion.toString()) >= 0) {
+      throw new Error("Catalog correction replacementVersion must be SemVer-greater than the prepared generation.")
+    }
+    const expectedArchitectures = publication.renderer.downloads.map((download) => download.architecture).sort()
+    const observedArchitectures = authored.downloads.map((download) => download.architecture).sort()
+    if (new Set(observedArchitectures).size !== observedArchitectures.length ||
+        expectedArchitectures.join("\n") !== observedArchitectures.join("\n")) {
+      throw new Error("Catalog correction downloads must replace the exact prepared architecture set.")
+    }
+    const downloads = authored.downloads.map((download) => {
+      const expectedUrl = `https://github.com/${publication.sourceRepository}/releases/download/${encodeURIComponent(authored.replacementTag)}/${encodeURIComponent(download.filename)}`
+      if (download.url !== expectedUrl) {
+        throw new Error("Catalog correction download URL must be the exact replacement GitHub release asset coordinate.")
+      }
+      return PreparedCatalogDownload.make({
+        architecture: download.architecture,
+        url: download.url,
+        filename: download.filename,
+        sha256: parseSha256Hex(download.sha256)
+      })
+    }) as [PreparedCatalogDownload, ...Array<PreparedCatalogDownload>]
+    const target = bundle.blobs.get(publication.targetArtifactId.toString())
+    const state = bundle.blobs.get(publication.stateArtifactId.toString())
+    if (target === undefined || state === undefined ||
+        !digestEquals(sha256Digest(target), publication.targetDigest) ||
+        !digestEquals(sha256Digest(state), publication.stateDigest)) {
+      throw new Error("Prepared catalog correction subject has no exact target/state baseline bytes.")
+    }
+    const managed = decodeCatalogManagedState(state)
+    if (managed === undefined || managed.status !== "active" || managed.generation !== publication.version ||
+        !digestEquals(managed.targetDigest, publication.targetDigest)) {
+      throw new Error("Prepared catalog correction baseline is not one canonical active managed pair.")
+    }
+    return makeCorrectionIntent({
+      schemaVersion: "correction-intent/v2",
+      preparedDigest: digest,
+      correction: {
+        _tag: "CatalogForwardCorrection",
+        provider: "catalog-git",
+        publicationId: publication.id,
+        baselineDigest: publicationBaselineDigest(publication),
+        baselineTargetDigest: publication.targetDigest,
+        baselineStateDigest: publication.stateDigest,
+        replacementVersion: authored.replacementVersion,
+        replacementTag: authored.replacementTag,
+        downloads,
+        reason: authored.reason
+      }
+    })
+  }
+  const publication = choosePublication(bundle, "PreparedGitHubPublication", authored.publicationId)
+  return makeCorrectionIntent({
+    schemaVersion: "correction-intent/v2",
+    preparedDigest: digest,
+    correction: {
+      _tag: "GithubReleaseCorrection",
+      provider: "github",
+      publicationId: publication.id,
+      repository: publication.repository,
+      tag: publication.tag,
+      baselineDigest: publicationBaselineDigest(publication),
+      marker: authored.message,
+      ...(authored.replacement === undefined ? {} : { replacement: authored.replacement })
+    }
+  })
+}
+
+const verifyNpm = (bundle: PreparedBundle, correction: NpmDeprecationCorrection): void => {
+  const publication = findPublication(bundle, correction.publicationId.toString())
+  if (publication?._tag !== "PreparedNpmPublication" || publication.registryUrl !== correction.registryUrl ||
+    publication.packageName !== correction.packageName || publication.version !== correction.version) {
+    throw new Error("npm correction subject is not the exact npm publication in the prepared manifest.")
+  }
+  if (!digestEquals(publicationBaselineDigest(publication), correction.baselineDigest)) {
+    throw new Error("npm correction baseline digest is not the exact prepared publication digest.")
+  }
+  const artifact = bundle.manifest.artifacts.find((candidate) => candidate.id === publication.artifactId)
+  const bytes = artifact === undefined ? undefined : bundle.blobs.get(artifact.id.toString())
+  if (bytes === undefined) throw new Error("npm correction subject has no verified prepared tarball.")
+  const integrity = sha512Digest(bytes)
+  if (!digestEquals(integrity, correction.tarballIntegrity)) {
+    throw new Error("npm correction tarball integrity is not the prepared artifact integrity.")
+  }
+}
+
+const verifyGithub = (bundle: PreparedBundle, correction: GithubReleaseCorrection): void => {
+  const publication = findPublication(bundle, correction.publicationId.toString())
+  if (publication?._tag !== "PreparedGitHubPublication" || publication.repository !== correction.repository || publication.tag !== correction.tag) {
+    throw new Error("GitHub correction subject is not the exact GitHub publication in the prepared manifest.")
+  }
+  if (!digestEquals(publicationBaselineDigest(publication), correction.baselineDigest)) {
+    throw new Error("GitHub correction baseline digest is not the exact prepared publication digest.")
+  }
+}
+
+const verifyCatalog = (bundle: PreparedBundle, correction: CatalogForwardCorrection): void => {
+  const publication = findPublication(bundle, correction.publicationId.toString())
+  if (publication?._tag !== "PreparedCatalogPublication") {
+    throw new Error("Catalog correction subject is not the exact catalog publication in the prepared manifest.")
+  }
+  if (!digestEquals(publicationBaselineDigest(publication), correction.baselineDigest) ||
+      !digestEquals(publication.targetDigest, correction.baselineTargetDigest) ||
+      !digestEquals(publication.stateDigest, correction.baselineStateDigest)) {
+    throw new Error("Catalog correction baseline digest is not the exact prepared target/state publication.")
+  }
+  if (compareCatalogVersions(publication.version.toString(), correction.replacementVersion.toString()) >= 0) {
+    throw new Error("Catalog correction is not a SemVer-forward replacement.")
+  }
+  const expectedArchitectures = publication.renderer.downloads.map((download) => download.architecture).sort().join("\n")
+  const replacementArchitectures = correction.downloads.map((download) => download.architecture).sort().join("\n")
+  if (expectedArchitectures !== replacementArchitectures) {
+    throw new Error("Catalog correction replacement architecture set differs from the prepared renderer.")
+  }
+  for (const download of correction.downloads) {
+    const expected = `https://github.com/${publication.sourceRepository}/releases/download/${encodeURIComponent(correction.replacementTag)}/${encodeURIComponent(download.filename)}`
+    if (download.url !== expected) throw new Error("Catalog correction carries a foreign replacement download coordinate.")
+  }
+}
+
+export const verifyCorrectionIntent = (bundle: PreparedBundle, intent: CorrectionIntent): void => {
+  encodeCorrectionIntent(intent)
+  if (!digestEquals(preparedDigest(bundle), intent.preparedDigest)) {
+    throw new Error("Correction intent is bound to a different prepared release.")
+  }
+  switch (intent.correction._tag) {
+    case "NpmDeprecationCorrection": return verifyNpm(bundle, intent.correction)
+    case "GithubReleaseCorrection": return verifyGithub(bundle, intent.correction)
+    case "CatalogForwardCorrection": return verifyCatalog(bundle, intent.correction)
+  }
+}
+
+const providerOf = (intent: CorrectionIntent): "npm" | "github" | "catalog-git" => intent.correction.provider
+
+/**
+ * The only correction entry point. Provider adapters are built at the host
+ * boundary. Neither admitted provider currently exposes a conditional write
+ * that protects the exact observed generation, so a validated intent becomes
+ * an external proposal and never a read-then-unconditional mutation.
+ */
+export const correctPreparedRelease = Effect.fn("correctPreparedRelease")(function*(input: {
+  readonly bundle: PreparedBundle
+  readonly intent: CorrectionIntent
+  readonly services?: {
+    readonly credentials: CredentialProviderShape
+    readonly http: HttpAuthorizerShape
+    readonly mutationHttp: AuthorizedMutationHttpShape
+  }
+}) {
+  try {
+    verifyCorrectionIntent(input.bundle, input.intent)
+  } catch (cause) {
+    return yield* Effect.fail(new CorrectionValidationError({ reason: cause instanceof Error ? cause.message : String(cause) }))
+  }
+  const provider = providerOf(input.intent)
+  if (input.intent.correction._tag === "CatalogForwardCorrection") {
+    if (input.services === undefined) return CorrectionUnsupported.make({
+      provider,
+      reason: "Catalog correction requires the host-owned credential and GitHub HTTP authority boundary.",
+      evidence: "docs/release-program/remediation/231-catalog-delivery.md",
+      proposal: new TextDecoder().decode(encodeCorrectionIntent(input.intent))
+    })
+    const correction = input.intent.correction
+    const publication = findPublication(input.bundle, correction.publicationId.toString())
+    if (publication?._tag !== "PreparedCatalogPublication") {
+      return yield* new CorrectionValidationError({ reason: "Verified catalog correction publication disappeared." })
+    }
+    const baselineTarget = input.bundle.blobs.get(publication.targetArtifactId.toString())
+    const baselineState = input.bundle.blobs.get(publication.stateArtifactId.toString())
+    if (baselineTarget === undefined || baselineState === undefined) {
+      return yield* new CorrectionValidationError({ reason: "Verified catalog correction baseline bytes disappeared." })
+    }
+    const target = renderCatalog(correction.replacementVersion, publication.renderer.renderer, correction.downloads)
+    const state = encodeCatalogManagedState(CatalogManagedState.make({
+      schemaVersion: "ts-release/catalog-state/v2",
+      catalogId: publication.catalogId,
+      renderer: publication.renderer.renderer._tag,
+      generation: correction.replacementVersion,
+      status: "corrected",
+      targetDigest: sha256Digest(target),
+      sourceRepository: publication.sourceRepository,
+      sourceTag: correction.replacementTag,
+      correctionId: input.intent.correctionId,
+      reason: correction.reason,
+      replacementVersion: correction.replacementVersion
+    }))
+    const subject = makeCatalogSubject(publication, input.services.http, input.services.mutationHttp, {
+      id: SubjectId.make(`${publication.authority.subject}#correction-${input.intent.correctionId.hex}`),
+      purpose: "correct",
+      target,
+      state,
+      baselineTarget,
+      baselineState
+    })
+    const report = yield* publishReleaseSubjects({
+      prepared: SubjectId.make(`correction:sha256-${input.intent.correctionId.hex}`),
+      subjects: [subject]
+    }).pipe(Effect.provideService(CredentialProvider, input.services.credentials))
+    return {
+      _tag: "CorrectionExecuted",
+      provider: "catalog-git",
+      report,
+      reason: "Catalog correction ran through the exact conditional Git-data subject.",
+      evidence: "docs/release-program/remediation/231-catalog-delivery.md",
+      proposal: ""
+    } as const
+  }
+  return CorrectionUnsupported.make({
+    provider,
+    reason: provider === "npm"
+      ? "npm exposes no proved conditional deprecation write for the observed package generation; use the exact external proposal instead."
+      : "GitHub exposes no proved conditional release-metadata write for the observed release generation.",
+    evidence: "docs/release-program/remediation/229-provider-recovery.md",
+    proposal: new TextDecoder().decode(encodeCorrectionIntent(input.intent))
+  })
+})
+
+export const correctionEvidenceProjection = (intent: CorrectionIntent): string => {
+  const encoded = Schema.encodeSync(CorrectionIntentV2)(intent)
+  return encodeCanonicalJson({
+    correctionId: encoded.correctionId,
+    preparedDigest: encoded.preparedDigest,
+    provider: providerOf(intent)
+  })
+}

package/src/correction/index.ts

@@ -0,0 +1,2 @@
+export * from "./intent.js"
+export * from "./coordinator.js"

package/src/correction/intent.ts

@@ -0,0 +1,172 @@
+import * as Schema from "effect/Schema"
+import { encodeCanonicalJson, parseStrictJson } from "../model/canonical.js"
+import {
+  Sha256Digest,
+  Sha256Hex,
+  Sha512Digest,
+  digestEquals,
+  sha256Digest
+} from "../model/digest.js"
+import { NonEmptyName, Version } from "../model/primitives.js"
+import { CatalogArchitecture, PreparedCatalogDownload } from "../model/catalog.js"
+
+const optional = Schema.optionalKey
+const boundedText = Schema.String.check(Schema.makeFilter((value: string) =>
+  [...value].length <= 2048 && [...value].every((character) => {
+    const codePoint = character.codePointAt(0) ?? 0
+    return codePoint === 9 || codePoint === 10 || codePoint === 13 || codePoint >= 0x20
+  }) ? undefined : "Correction text must be bounded and contain no control characters."))
+const publicMessage = boundedText.pipe(Schema.check(Schema.makeFilter((value: string) =>
+  value.length > 0 ? undefined : "Correction message must be nonempty.")))
+
+export class ReplacementCoordinate extends Schema.Class<ReplacementCoordinate>("ReplacementCoordinate")({
+  provider: Schema.Literals(["npm", "github"]), coordinate: publicMessage
+}) {}
+
+export class NpmDeprecationCorrection extends Schema.TaggedClass<NpmDeprecationCorrection>()("NpmDeprecationCorrection", {
+  provider: Schema.Literal("npm"), publicationId: NonEmptyName, registryUrl: Schema.NonEmptyString,
+  packageName: NonEmptyName, version: Version, baselineDigest: Sha256Digest, tarballIntegrity: Sha512Digest,
+  message: publicMessage, replacement: optional(ReplacementCoordinate)
+}) {}
+
+export class GithubReleaseCorrection extends Schema.TaggedClass<GithubReleaseCorrection>()("GithubReleaseCorrection", {
+  provider: Schema.Literal("github"), publicationId: NonEmptyName, repository: Schema.NonEmptyString,
+  tag: NonEmptyName, baselineDigest: Sha256Digest, marker: publicMessage,
+  replacement: optional(ReplacementCoordinate)
+}) {}
+
+export class CatalogForwardCorrection extends Schema.TaggedClass<CatalogForwardCorrection>()("CatalogForwardCorrection", {
+  provider: Schema.Literal("catalog-git"),
+  publicationId: NonEmptyName,
+  baselineDigest: Sha256Digest,
+  baselineTargetDigest: Sha256Digest,
+  baselineStateDigest: Sha256Digest,
+  replacementVersion: Version,
+  replacementTag: NonEmptyName,
+  downloads: Schema.NonEmptyArray(PreparedCatalogDownload),
+  reason: publicMessage
+}) {}
+
+/** Human-authored correction request. Destination and immutable subject facts
+ * are deliberately absent: they are derived from the loaded prepared bundle. */
+export class AuthoredNpmDeprecation
+  extends Schema.Class<AuthoredNpmDeprecation>("AuthoredNpmDeprecation")({
+    provider: Schema.Literal("npm"),
+    kind: Schema.Literal("deprecate"),
+    publicationId: optional(NonEmptyName),
+    message: publicMessage,
+    replacement: optional(ReplacementCoordinate)
+  }) {}
+
+export class AuthoredGithubReleaseAmendment
+  extends Schema.Class<AuthoredGithubReleaseAmendment>("AuthoredGithubReleaseAmendment")({
+    provider: Schema.Literal("github"),
+    kind: Schema.Literal("amend-release-metadata"),
+    publicationId: optional(NonEmptyName),
+    message: publicMessage,
+    replacement: optional(ReplacementCoordinate)
+  }) {}
+
+export class AuthoredCatalogDownload extends Schema.Class<AuthoredCatalogDownload>("AuthoredCatalogDownload")({
+  architecture: CatalogArchitecture,
+  url: Schema.NonEmptyString,
+  filename: NonEmptyName,
+  sha256: Sha256Hex
+}) {}
+
+export class AuthoredCatalogForwardCorrection
+  extends Schema.Class<AuthoredCatalogForwardCorrection>("AuthoredCatalogForwardCorrection")({
+    provider: Schema.Literal("catalog-git"),
+    kind: Schema.Literal("forward-catalog-state"),
+    publicationId: optional(NonEmptyName),
+    replacementVersion: Version,
+    replacementTag: NonEmptyName,
+    downloads: Schema.NonEmptyArray(AuthoredCatalogDownload),
+    reason: publicMessage
+  }) {}
+
+export const AuthoredCorrection = Schema.Union([
+  AuthoredNpmDeprecation,
+  AuthoredGithubReleaseAmendment,
+  AuthoredCatalogForwardCorrection
+])
+export type AuthoredCorrection = typeof AuthoredCorrection.Type
+
+export const decodeAuthoredCorrection = Schema.decodeUnknownSync(AuthoredCorrection, {
+  onExcessProperty: "error"
+})
+
+export const CorrectionVariant = Schema.Union([
+  NpmDeprecationCorrection, GithubReleaseCorrection, CatalogForwardCorrection
+])
+export type CorrectionVariant = typeof CorrectionVariant.Type
+
+const CorrectionIntentUnsignedV2 = Schema.Struct({
+  schemaVersion: Schema.Literal("correction-intent/v2"),
+  preparedDigest: Sha256Digest,
+  correction: CorrectionVariant
+})
+
+export class CorrectionIntentV2 extends Schema.Class<CorrectionIntentV2>("CorrectionIntentV2")({
+  schemaVersion: Schema.Literal("correction-intent/v2"), preparedDigest: Sha256Digest,
+  correction: CorrectionVariant, correctionId: Sha256Digest
+}) {}
+export type CorrectionIntent = typeof CorrectionIntentV2.Type
+export type CorrectionIntentInput = Omit<CorrectionIntent, "correctionId">
+
+export class CorrectionIntentError
+  extends Schema.TaggedErrorClass<CorrectionIntentError>()("CorrectionIntentError", {
+    reason: Schema.String
+  }) {}
+
+const normalizeCorrection = (value: unknown): CorrectionVariant => Schema.decodeUnknownSync(CorrectionVariant)(value)
+const normalizeUnsigned = (value: CorrectionIntentInput): CorrectionIntentInput =>
+  Schema.decodeUnknownSync(CorrectionIntentUnsignedV2, { onExcessProperty: "error" })({
+    schemaVersion: value.schemaVersion,
+    preparedDigest: value.preparedDigest,
+    correction: normalizeCorrection(value.correction)
+  })
+
+const unsignedBytes = (value: CorrectionIntentInput): Uint8Array => {
+  const normalized = normalizeUnsigned(value)
+  const encoded = Schema.encodeSync(CorrectionIntentUnsignedV2)(normalized)
+  return new TextEncoder().encode(encodeCanonicalJson(encoded))
+}
+
+export const correctionIdFor = (value: CorrectionIntentInput): Sha256Digest =>
+  sha256Digest(unsignedBytes(value))
+
+export const makeCorrectionIntent = (value: CorrectionIntentInput): CorrectionIntent => {
+  const normalized = normalizeUnsigned(value)
+  const correctionId = correctionIdFor(normalized)
+  return CorrectionIntentV2.make({ ...normalized, correctionId })
+}
+
+const equal = (left: Uint8Array, right: Uint8Array): boolean =>
+  left.length === right.length && left.every((byte, index) => byte === right[index])
+
+export const encodeCorrectionIntent = (value: CorrectionIntent): Uint8Array => {
+  try {
+    const normalized = Schema.decodeUnknownSync(CorrectionIntentV2, { onExcessProperty: "error" })(value)
+    const expected = correctionIdFor(normalized)
+    if (!digestEquals(expected, normalized.correctionId)) {
+      throw new Error("Correction id does not match canonical unsigned V2 intent bytes.")
+    }
+    return new TextEncoder().encode(encodeCanonicalJson(Schema.encodeSync(CorrectionIntentV2)(normalized)))
+  } catch (cause) {
+    throw CorrectionIntentError.make({ reason: cause instanceof Error ? cause.message : String(cause) })
+  }
+}
+
+export const decodeCorrectionIntent = (bytes: Uint8Array): CorrectionIntent => {
+  try {
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes)
+    const value = Schema.decodeUnknownSync(CorrectionIntentV2, { onExcessProperty: "error" })(parseStrictJson(text))
+    const canonical = encodeCorrectionIntent(value)
+    if (!equal(canonical, bytes)) throw new Error("Correction intent bytes are not canonical.")
+    return value
+  } catch (cause) {
+    if (cause instanceof CorrectionIntentError) throw cause
+    throw CorrectionIntentError.make({ reason: cause instanceof Error ? cause.message : String(cause) })
+  }
+}

package/src/drivers/archive.ts

@@ -0,0 +1,102 @@
+import { gzipSync } from "node:zlib"
+
+export interface ArchiveEntry {
+  readonly path: string
+  readonly data: Uint8Array
+  readonly mode: number
+}
+const text = (value: string) => new TextEncoder().encode(value)
+const concat = (parts: ReadonlyArray<Uint8Array>): Uint8Array => {
+  const output = new Uint8Array(parts.reduce((total, part) => total + part.length, 0))
+  let offset = 0
+  for (const part of parts) {
+    output.set(part, offset)
+    offset += part.length
+  }
+  return output
+}
+const integer = (bytes: number, value: number): Uint8Array => {
+  const output = new Uint8Array(bytes)
+  const view = new DataView(output.buffer)
+  if (bytes === 2) view.setUint16(0, value, true)
+  else view.setUint32(0, value, true)
+  return output
+}
+const crcTable = Array.from({ length: 256 }, (_, value) => {
+  let crc = value
+  for (const bit of Array.from({ length: 8 }, (_, index) => index)) {
+    crc = (crc & 1) === 1 ? 0xedb88320 ^ (crc >>> 1) : crc >>> 1
+  }
+  return crc >>> 0
+})
+const crc32 = (data: Uint8Array): number => {
+  let crc = 0xffffffff
+  for (const byte of data) crc = (crc >>> 8) ^ crcTable[(crc ^ byte) & 0xff]!
+  return (crc ^ 0xffffffff) >>> 0
+}
+export const zip = (entries: ReadonlyArray<ArchiveEntry>): Uint8Array => {
+  const bodies: Array<Uint8Array> = []
+  const central: Array<Uint8Array> = []
+  let offset = 0
+  for (const entry of entries) {
+    const name = text(entry.path)
+    const crc = crc32(entry.data)
+    const local = concat([
+      integer(4, 0x04034b50), integer(2, 20), integer(2, 0x0800), integer(2, 0),
+      integer(2, 0), integer(2, 0), integer(4, crc), integer(4, entry.data.length),
+      integer(4, entry.data.length), integer(2, name.length), integer(2, 0), name
+    ])
+    bodies.push(local, entry.data)
+    central.push(concat([
+      integer(4, 0x02014b50), integer(2, 0x0314), integer(2, 20), integer(2, 0x0800),
+      integer(2, 0), integer(2, 0), integer(2, 0), integer(4, crc),
+      integer(4, entry.data.length), integer(4, entry.data.length), integer(2, name.length),
+      integer(2, 0), integer(2, 0), integer(2, 0), integer(2, 0),
+      integer(4, entry.mode << 16), integer(4, offset), name
+    ]))
+    offset += local.length + entry.data.length
+  }
+  const directory = concat(central)
+  return concat([
+    ...bodies, directory, integer(4, 0x06054b50), integer(2, 0), integer(2, 0),
+    integer(2, entries.length), integer(2, entries.length), integer(4, directory.length),
+    integer(4, offset), integer(2, 0)
+  ])
+}
+const ascii = (output: Uint8Array, offset: number, length: number, value: string): void => {
+  const bytes = text(value)
+  if (bytes.length > length) throw new Error(`Archive path is too long: ${value}`)
+  output.set(bytes, offset)
+}
+const octal = (output: Uint8Array, offset: number, length: number, value: number): void => {
+  ascii(output, offset, length - 2, value.toString(8).padStart(length - 2, "0"))
+  output[offset + length - 2] = 0
+  output[offset + length - 1] = 0x20
+}
+const tarHeader = (entry: ArchiveEntry): Uint8Array => {
+  const header = new Uint8Array(512)
+  ascii(header, 0, 100, entry.path)
+  octal(header, 100, 8, entry.mode & 0o777)
+  octal(header, 108, 8, 0)
+  octal(header, 116, 8, 0)
+  octal(header, 124, 12, entry.data.length)
+  octal(header, 136, 12, 0)
+  header.fill(0x20, 148, 156)
+  header[156] = 0x30
+  ascii(header, 257, 6, "ustar")
+  ascii(header, 263, 2, "00")
+  octal(header, 148, 8, header.reduce((sum, byte) => sum + byte, 0))
+  return header
+}
+// Level 9 is explicit because it is the level at which every zlib we ship on
+// emits identical deflate bytes; the 10-byte header is then overwritten so no
+// clock (MTIME) or platform (OS) leaks into an artifact.
+export const tarGz = (entries: ReadonlyArray<ArchiveEntry>): Uint8Array => {
+  const packed = new Uint8Array(gzipSync(concat(entries.flatMap((entry) => [
+    tarHeader(entry), entry.data,
+    new Uint8Array(entry.data.length % 512 === 0 ? 0 : 512 - entry.data.length % 512)
+  ]).concat([new Uint8Array(1024)])), { level: 9 }))
+  packed.fill(0, 4, 8)
+  packed[9] = 0xff
+  return packed
+}

package/src/drivers/contain.ts

@@ -0,0 +1,20 @@
+import { realpathSync } from "node:fs"
+import { isAbsolute, relative, sep } from "node:path"
+
+// Lexical: is `path` at or beneath `root`? Both must already be in the same
+// canonical form (use assertContained with realpath when symlinks may be
+// present).
+export const contained = (root: string, path: string): boolean => {
+  const value = relative(root, path)
+  return value === "" || (value !== ".." && !value.startsWith(`..${sep}`) && !isAbsolute(value))
+}
+export const assertContained = (
+  root: string, path: string,
+  options: { readonly realpath: boolean, readonly what: string }
+): string => {
+  const candidate = options.realpath ? realpathSync(path) : path
+  if (!contained(options.realpath ? realpathSync(root) : root, candidate)) {
+    throw new Error(`${options.what} escapes the workspace root.`)
+  }
+  return candidate
+}

package/src/drivers/environment.ts

@@ -0,0 +1,28 @@
+import * as Config from "effect/Config"
+import * as Effect from "effect/Effect"
+import * as Option from "effect/Option"
+
+// Environment is a host capability, so it is read through effect/Config rather
+// than process.env. The default ConfigProvider reads the host environment; a
+// test or an embedding host substitutes one with ConfigProvider.layer.
+export const readOptionalEnv = (name: string): Effect.Effect<string | undefined> =>
+  Config.option(Config.string(name)).pipe(
+    Effect.map(Option.getOrUndefined),
+    Effect.orElseSucceed(() => undefined)
+  )
+
+// Exec and command publish run with a closed environment: PATH plus the
+// operation's named variables and nothing else. The parent environment is
+// never inherited, so a plan states every variable a command can observe.
+export const readEnvironment = (
+  names: ReadonlyArray<string>
+): Effect.Effect<Record<string, string>> =>
+  Effect.forEach(["PATH", ...names], (name) =>
+    readOptionalEnv(name).pipe(Effect.map((value) => [name, value] as const))).pipe(
+    Effect.map((entries) => ({
+      ...Object.fromEntries(entries.flatMap(([name, value]) => value === undefined ? [] : [[name, value]])),
+      TZ: "UTC",
+      LC_ALL: "C",
+      LANG: "C",
+      SOURCE_DATE_EPOCH: "0"
+    })))

package/src/drivers/errors.ts

@@ -0,0 +1,6 @@
+import * as Schema from "effect/Schema"
+
+export class DriverError
+  extends Schema.TaggedErrorClass<DriverError>()("DriverError", {
+    reason: Schema.String, commitment: Schema.Literals(["before-commit", "unknown"])
+  }) {}