@mannyc1/ts-release 0.0.7 → 0.3.0

package/src/model/artifact-collection.ts

@@ -0,0 +1,237 @@
+import * as Schema from "effect/Schema"
+import { encodeCanonicalJson } from "./canonical.js"
+import { sha256Digest } from "./digest.js"
+import { OperationId, OutputId, SafeRelativePath } from "./primitives.js"
+
+export const ArtifactCollectionId = Schema.NonEmptyString.check(Schema.makeFilter((value: string) =>
+  /^[A-Za-z0-9._-]+$/u.test(value)
+    ? undefined
+    : "Artifact collection id must be a portable ASCII identifier."
+)).pipe(Schema.brand("ArtifactCollectionId"))
+export type ArtifactCollectionId = typeof ArtifactCollectionId.Type
+
+export const CollectionArtifactKind = Schema.Literals([
+  "file",
+  "executable",
+  "archive",
+  "digest"
+])
+export type CollectionArtifactKind = typeof CollectionArtifactKind.Type
+
+export const ArtifactPathSuffix = Schema.NonEmptyString.check(Schema.makeFilter((value: string) =>
+  /^\.[A-Za-z0-9._-]+$/u.test(value)
+    ? undefined
+    : "Artifact collection pathSuffix must be a canonical dot suffix without path separators."
+)).pipe(Schema.brand("ArtifactPathSuffix"))
+export type ArtifactPathSuffix = typeof ArtifactPathSuffix.Type
+
+export const ArtifactCollectionRoot = SafeRelativePath.check(Schema.makeFilter((value: string) =>
+  value !== "." && value.split("/").every((part) => /^[A-Za-z0-9._-]+$/u.test(part) && part !== "." && part !== "..")
+    ? undefined
+    : "Artifact collection root must be a canonical NFC POSIX subdirectory."
+)).pipe(Schema.brand("ArtifactCollectionRoot"))
+export type ArtifactCollectionRoot = typeof ArtifactCollectionRoot.Type
+
+const nonNegativeInteger = Schema.Number.check(Schema.makeFilter((value: number) =>
+  Number.isSafeInteger(value) && value >= 0
+    ? undefined
+    : "Collection cardinality bounds must be nonnegative safe integers."
+))
+
+export class OneArtifactCardinality
+  extends Schema.Class<OneArtifactCardinality>("OneArtifactCardinality")({
+    kind: Schema.Literal("one")
+  }) {}
+
+export class OneOrMoreArtifactCardinality
+  extends Schema.Class<OneOrMoreArtifactCardinality>("OneOrMoreArtifactCardinality")({
+    kind: Schema.Literal("one-or-more")
+  }) {}
+
+export class BoundedArtifactCardinality
+  extends Schema.Class<BoundedArtifactCardinality>("BoundedArtifactCardinality")({
+    kind: Schema.Literal("bounded"),
+    minimum: nonNegativeInteger,
+    maximum: nonNegativeInteger
+  }) {}
+
+const ArtifactCardinalityVariants = Schema.Union([
+  OneArtifactCardinality,
+  OneOrMoreArtifactCardinality,
+  BoundedArtifactCardinality
+])
+
+export const ArtifactCardinality = ArtifactCardinalityVariants.pipe(Schema.check(
+  Schema.makeFilter((value) => value.kind !== "bounded" || value.minimum <= value.maximum
+    ? undefined
+    : "Bounded collection cardinality minimum must not exceed maximum.")
+))
+export type ArtifactCardinality = typeof ArtifactCardinality.Type
+
+/**
+ * One command-owned dynamic output set. A collection intentionally permits one
+ * artifact kind and one filename suffix: heterogeneous output sets must be
+ * split into independently selectable contracts.
+ */
+export class ArtifactCollectionContract
+  extends Schema.Class<ArtifactCollectionContract>("ArtifactCollectionContract")({
+    id: ArtifactCollectionId,
+    producer: OperationId,
+    root: ArtifactCollectionRoot,
+    artifactKind: CollectionArtifactKind,
+    pathSuffix: ArtifactPathSuffix,
+    mediaType: Schema.NonEmptyString,
+    cardinality: ArtifactCardinality
+  }) {}
+
+/** A downstream requirement over a stable collection identity. */
+export class ArtifactCollectionSelector
+  extends Schema.Class<ArtifactCollectionSelector>("ArtifactCollectionSelector")({
+    collection: ArtifactCollectionId,
+    artifactKind: CollectionArtifactKind,
+    pathSuffix: ArtifactPathSuffix,
+    mediaType: Schema.NonEmptyString,
+    cardinality: ArtifactCardinality
+  }) {}
+
+/** Exact runtime member identity persisted beside the prepared artifacts. */
+export class ArtifactCollectionMember
+  extends Schema.Class<ArtifactCollectionMember>("ArtifactCollectionMember")({
+    key: SafeRelativePath,
+    artifactId: OutputId
+  }) {}
+
+export interface CardinalityRange {
+  readonly minimum: number
+  readonly maximum?: number
+}
+
+export const cardinalityRange = (value: ArtifactCardinality): CardinalityRange => {
+  switch (value.kind) {
+    case "one": return { minimum: 1, maximum: 1 }
+    case "one-or-more": return { minimum: 1 }
+    case "bounded": return { minimum: value.minimum, maximum: value.maximum }
+  }
+}
+
+export const cardinalityIssue = (value: ArtifactCardinality): string | undefined => {
+  const range = cardinalityRange(value)
+  return !Number.isSafeInteger(range.minimum) || range.minimum < 0 ||
+      (range.maximum !== undefined && (!Number.isSafeInteger(range.maximum) || range.maximum < range.minimum))
+    ? "Collection cardinality must define a valid nonnegative integer range."
+    : undefined
+}
+
+/** Reject kind/media/suffix combinations whose observable claims conflict. */
+export const collectionContractIssue = (
+  value: Pick<ArtifactCollectionContract, "artifactKind" | "pathSuffix" | "mediaType">
+): string | undefined => {
+  const suffix = value.pathSuffix.toString()
+  switch (value.artifactKind) {
+    case "archive":
+      if (value.mediaType === "application/zip" && suffix === ".zip") return undefined
+      if (value.mediaType === "application/gzip" && [".gz", ".tgz", ".tar.gz"].includes(suffix)) return undefined
+      return "Archive collections support application/zip with .zip or application/gzip with .gz, .tgz, or .tar.gz."
+    case "digest":
+      return value.mediaType === "text/plain" && [".sha256", ".sha512"].includes(suffix)
+        ? undefined
+        : "Digest collections require text/plain with .sha256 or .sha512."
+    case "executable":
+      return value.mediaType === "application/octet-stream"
+        ? undefined
+        : "Executable collections require application/octet-stream; executable mode is observed at capture."
+    case "file":
+      return value.mediaType === "application/zip" || value.mediaType === "application/gzip"
+        ? "Archive media types require the archive artifact kind."
+        : undefined
+  }
+}
+
+/** Byte-level checks for the formats whose kind is portable and observable. */
+export const collectionMemberBytesIssue = (
+  contract: ArtifactCollectionContract,
+  bytes: Uint8Array
+): string | undefined => {
+  if (contract.artifactKind === "archive") {
+    if (contract.mediaType === "application/zip") {
+      return bytes.length >= 4 && bytes[0] === 0x50 && bytes[1] === 0x4b &&
+          ((bytes[2] === 0x03 && bytes[3] === 0x04) ||
+            (bytes[2] === 0x05 && bytes[3] === 0x06) ||
+            (bytes[2] === 0x07 && bytes[3] === 0x08))
+        ? undefined
+        : "declared ZIP member does not have a ZIP file signature"
+    }
+    if (contract.mediaType === "application/gzip") {
+      return bytes.length >= 3 && bytes[0] === 0x1f && bytes[1] === 0x8b && bytes[2] === 0x08
+        ? undefined
+        : "declared gzip member does not have a gzip file signature"
+    }
+  }
+  if (contract.artifactKind === "digest") {
+    let text: string
+    try { text = new TextDecoder("utf-8", { fatal: true }).decode(bytes) } catch {
+      return "declared digest member is not UTF-8 text"
+    }
+    const digits = contract.pathSuffix === ".sha256" ? 64 : 128
+    const rows = text.endsWith("\n") ? text.slice(0, -1).split("\n") : text.split("\n")
+    return rows.length > 0 && rows.every((row) => new RegExp(`^[a-f0-9]{${digits}}  [^\\s/](?:.*[^\\s/])?$`, "u").test(row))
+      ? undefined
+      : `declared digest member does not contain canonical ${digits}-hex checksum rows`
+  }
+  return undefined
+}
+
+export const cardinalityAccepts = (value: ArtifactCardinality, count: number): boolean => {
+  const range = cardinalityRange(value)
+  return Number.isSafeInteger(count) && count >= range.minimum &&
+    (range.maximum === undefined || count <= range.maximum)
+}
+
+export const cardinalitiesOverlap = (
+  left: ArtifactCardinality,
+  right: ArtifactCardinality
+): boolean => {
+  const a = cardinalityRange(left)
+  const b = cardinalityRange(right)
+  const maximum = a.maximum === undefined
+    ? b.maximum
+    : b.maximum === undefined
+    ? a.maximum
+    : Math.min(a.maximum, b.maximum)
+  return maximum === undefined || Math.max(a.minimum, b.minimum) <= maximum
+}
+
+/** Paths discovered from directory entries must already be portable canon. */
+export const normalizeCollectionMemberKey = (value: string): SafeRelativePath => {
+  if (value.split("/").some((part) => !/^[A-Za-z0-9._-]+$/u.test(part) || part === "." || part === "..")) {
+    throw new Error(`Collection member path ${JSON.stringify(value)} is not portable ASCII POSIX form.`)
+  }
+  return SafeRelativePath.make(value)
+}
+
+/**
+ * Stable output identity is a digest of the declared producer/contract and the
+ * normalized member key. No guessed runtime filename becomes graph authority.
+ */
+export const collectionMemberId = (
+  contract: ArtifactCollectionContract,
+  key: SafeRelativePath
+): OutputId => OutputId.make(`collection-sha256-${sha256Digest(new TextEncoder().encode(
+  encodeCanonicalJson({
+    producer: contract.producer.toString(),
+    collection: contract.id.toString(),
+    root: contract.root.toString(),
+    artifactKind: contract.artifactKind,
+    pathSuffix: contract.pathSuffix.toString(),
+    mediaType: contract.mediaType,
+    cardinality: contract.cardinality.kind === "bounded"
+      ? { kind: contract.cardinality.kind, minimum: contract.cardinality.minimum, maximum: contract.cardinality.maximum }
+      : { kind: contract.cardinality.kind },
+    key: key.toString()
+  })
+)).hex}`)
+
+export const collectionMemberPath = (
+  contract: ArtifactCollectionContract,
+  key: SafeRelativePath
+): SafeRelativePath => SafeRelativePath.make(`${contract.root}/${key}`)

package/src/model/authority.ts

@@ -0,0 +1,116 @@
+import * as Schema from "effect/Schema"
+
+const identifier = <const Name extends string>(name: Name) =>
+  Schema.NonEmptyString.pipe(Schema.brand(name))
+
+/** Stable identity of one remotely observable publication/correction subject. */
+export const SubjectId = identifier("SubjectId")
+export type SubjectId = typeof SubjectId.Type
+
+export const ProviderId = identifier("ProviderId")
+export type ProviderId = typeof ProviderId.Type
+
+/** Canonical provider audience, including any authority-relevant base path. */
+export const CanonicalAudience = identifier("CanonicalAudience")
+export type CanonicalAudience = typeof CanonicalAudience.Type
+
+/** A host-owned secret reference. It is a name/handle, never secret material. */
+export const CredentialRef = identifier("CredentialRef")
+export type CredentialRef = typeof CredentialRef.Type
+
+export const EnvironmentName = Schema.String.check(
+  Schema.makeFilter((value: string) => /^[A-Za-z_][A-Za-z0-9_]*$/u.test(value)
+    ? undefined
+    : "EnvironmentName must be a portable environment variable name.")
+).pipe(Schema.brand("EnvironmentName"))
+export type EnvironmentName = typeof EnvironmentName.Type
+
+export const CredentialPurpose = Schema.Literals(["observe", "publish", "correct"])
+export type CredentialPurpose = typeof CredentialPurpose.Type
+
+/** Exact verified source revision projected into npm's GitHub provenance statement. */
+export const TrustedPublishingSourceCommit = Schema.String.check(
+  Schema.makeFilter((value: string) => /^[a-f0-9]{40}(?:[a-f0-9]{24})?$/u.test(value)
+    ? undefined
+    : "TrustedPublishingSourceCommit must be a lowercase full Git SHA (40 or 64 hex characters).")
+).pipe(Schema.brand("TrustedPublishingSourceCommit"))
+export type TrustedPublishingSourceCommit = typeof TrustedPublishingSourceCommit.Type
+
+export class AnonymousAuthStrategy
+  extends Schema.Class<AnonymousAuthStrategy>("AnonymousAuthStrategy")({
+    kind: Schema.Literal("anonymous")
+  }) {}
+
+export class TokenAuthStrategy
+  extends Schema.Class<TokenAuthStrategy>("TokenAuthStrategy")({
+    kind: Schema.Literal("token"),
+    credential: CredentialRef
+  }) {}
+
+export class TrustedPublishingAuthStrategy
+  extends Schema.Class<TrustedPublishingAuthStrategy>("TrustedPublishingAuthStrategy")({
+    kind: Schema.Literal("trusted-publishing"),
+    identityProvider: Schema.Literal("github-actions"),
+    runnerClass: Schema.Literal("github-hosted"),
+    repository: Schema.NonEmptyString,
+    workflow: Schema.NonEmptyString,
+    workflowRef: Schema.NonEmptyString,
+    sourceCommit: TrustedPublishingSourceCommit,
+    provenanceEnvironmentContract: Schema.Literal("github-actions-npm-provenance-v1"),
+    allowedAction: Schema.Literal("npm-publish-direct"),
+    publisherSink: Schema.Literal("certified-npm-cli")
+  }) {}
+
+/**
+ * A supported external workflow owner. The stock coordinator persists and
+ * reports this identity but deliberately cannot mint or consume its token.
+ */
+export class ExternalTrustedPublishingAuthStrategy
+  extends Schema.Class<ExternalTrustedPublishingAuthStrategy>("ExternalTrustedPublishingAuthStrategy")({
+    kind: Schema.Literal("trusted-publishing"),
+    identityProvider: Schema.Literal("github-actions"),
+    runnerClass: Schema.Literal("github-hosted"),
+    repository: Schema.NonEmptyString,
+    workflow: Schema.NonEmptyString,
+    workflowRef: Schema.NonEmptyString,
+    sourceCommit: TrustedPublishingSourceCommit,
+    provenanceEnvironmentContract: Schema.Literal("external-pypa-action-v1"),
+    allowedAction: Schema.Literal("external-pypa-action"),
+    publisherSink: Schema.Literal("external-host-owned"),
+    environment: Schema.NonEmptyString,
+    projects: Schema.NonEmptyArray(Schema.NonEmptyString)
+  }) {}
+
+export const ResolvedTrustedPublishingAuthStrategy = Schema.Union([
+  TrustedPublishingAuthStrategy,
+  ExternalTrustedPublishingAuthStrategy
+])
+export type ResolvedTrustedPublishingAuthStrategy = typeof ResolvedTrustedPublishingAuthStrategy.Type
+
+export const ResolvedAuthStrategy = Schema.Union([
+  AnonymousAuthStrategy,
+  TokenAuthStrategy,
+  ResolvedTrustedPublishingAuthStrategy
+])
+export type ResolvedAuthStrategy = typeof ResolvedAuthStrategy.Type
+
+/**
+ * Exact authority requested for a verified prepared subject. This value is
+ * safe to report and persist: it contains only host references and intent.
+ */
+export class CredentialRequest
+  extends Schema.Class<CredentialRequest>("CredentialRequest")({
+    subject: SubjectId,
+    provider: ProviderId,
+    audience: CanonicalAudience,
+    purpose: CredentialPurpose,
+    strategy: ResolvedAuthStrategy
+  }) {}
+
+export type ObservationCredentialRequest = CredentialRequest & {
+  readonly purpose: "observe"
+}
+
+export type MutationCredentialRequest = CredentialRequest & {
+  readonly purpose: "publish" | "correct"
+}

package/src/model/bun-targets.ts

@@ -0,0 +1,34 @@
+/**
+ * The one advertised Bun artifact-target vocabulary. Config decoding, graph
+ * compilation, capability documentation, and cross-compile certification all
+ * project from these values.
+ */
+export const bunArtifactTargets = Object.freeze([
+  { id: "linux-x64", bunTarget: "bun-linux-x64", format: "elf", architecture: "x86_64" },
+  { id: "linux-arm64", bunTarget: "bun-linux-arm64", format: "elf", architecture: "aarch64" },
+  { id: "darwin-x64", bunTarget: "bun-darwin-x64", format: "mach-o", architecture: "x86_64" },
+  { id: "darwin-arm64", bunTarget: "bun-darwin-arm64", format: "mach-o", architecture: "aarch64" }
+] as const)
+
+// Windows targets are deliberately not advertised or shipped by this
+// candidate. Header-valid cross-compilation alone cannot certify execution.
+// Reopen one only after its public CLI binary executes on that Windows host in
+// the same clean-candidate gate.
+export type BunArtifactTarget = typeof bunArtifactTargets[number]
+export type BunArtifactTargetId = BunArtifactTarget["id"]
+export type BunBinaryFormat = BunArtifactTarget["format"]
+export type BunBinaryArchitecture = BunArtifactTarget["architecture"]
+
+const idsOf = <const Entries extends ReadonlyArray<{ readonly id: string }>>(
+  entries: Entries
+): { readonly [Index in keyof Entries]: Entries[Index] extends { readonly id: infer Id } ? Id : never } =>
+  Object.freeze(entries.map(({ id }) => id)) as never
+
+export const bunArtifactTargetIds = idsOf(bunArtifactTargets)
+
+const byId = new Map<BunArtifactTargetId, BunArtifactTarget>(
+  bunArtifactTargets.map((target) => [target.id, target])
+)
+
+/** Total after strict config decoding against `bunArtifactTargetIds`. */
+export const bunArtifactTarget = (id: BunArtifactTargetId): BunArtifactTarget => byId.get(id)!

package/src/model/canonical.ts

@@ -0,0 +1,205 @@
+import { createHash } from "node:crypto"
+
+export type Json =
+  | boolean
+  | null
+  | number
+  | string
+  | ReadonlyArray<Json>
+  | { readonly [key: string]: Json }
+
+class StrictJsonParser {
+  private index = 0
+  constructor(private readonly text: string) {}
+
+  parse(): Json {
+    this.space()
+    const value = this.value()
+    this.space()
+    if (this.index !== this.text.length) this.fail("trailing input")
+    return value
+  }
+
+  private fail(reason: string): never {
+    throw new Error(`Invalid strict JSON at ${this.index}: ${reason}`)
+  }
+
+  private space(): void {
+    while (/[\t\n\r ]/u.test(this.text[this.index] ?? "")) this.index += 1
+  }
+
+  private take(expected: string): void {
+    if (!this.text.startsWith(expected, this.index)) this.fail(`expected ${expected}`)
+    this.index += expected.length
+  }
+
+  private value(): Json {
+    const token = this.text[this.index]
+    if (token === "{") return this.object()
+    if (token === "[") return this.array()
+    if (token === '"') return this.string()
+    if (token === "t") {
+      this.take("true")
+      return true
+    }
+    if (token === "f") {
+      this.take("false")
+      return false
+    }
+    if (token === "n") {
+      this.take("null")
+      return null
+    }
+    if (token === "-" || token !== undefined && /[0-9]/u.test(token)) return this.number()
+    return this.fail("expected value")
+  }
+
+  private string(): string {
+    const start = this.index
+    this.index += 1
+    let escaped = false
+    while (this.index < this.text.length) {
+      const character = this.text[this.index]!
+      if (!escaped && character === '"') {
+        this.index += 1
+        const value = JSON.parse(this.text.slice(start, this.index)) as string
+        if (value !== value.normalize("NFC")) this.fail("non-NFC string")
+        return value
+      }
+      if (!escaped && character.codePointAt(0)! < 0x20) this.fail("control character")
+      escaped = !escaped && character === "\\"
+      this.index += 1
+    }
+    return this.fail("unterminated string")
+  }
+
+  private number(): number {
+    const match = /^-?(?:0|[1-9][0-9]*)/u.exec(this.text.slice(this.index))
+    if (match === null) return this.fail("invalid number")
+    const token = match[0]
+    const next = this.text[this.index + token.length]
+    if (next === "." || next === "e" || next === "E") this.fail("float")
+    this.index += token.length
+    const value = Number(token)
+    if (!Number.isSafeInteger(value) || Object.is(value, -0)) this.fail("unsafe integer")
+    return value
+  }
+
+  private array(): ReadonlyArray<Json> {
+    this.index += 1
+    this.space()
+    const result: Array<Json> = []
+    if (this.text[this.index] === "]") {
+      this.index += 1
+      return result
+    }
+    while (true) {
+      result.push(this.value())
+      this.space()
+      if (this.text[this.index] === "]") {
+        this.index += 1
+        return result
+      }
+      this.take(",")
+      this.space()
+    }
+  }
+
+  private object(): { readonly [key: string]: Json } {
+    this.index += 1
+    this.space()
+    const result: Record<string, Json> = {}
+    if (this.text[this.index] === "}") {
+      this.index += 1
+      return result
+    }
+    while (true) {
+      if (this.text[this.index] !== '"') this.fail("expected object key")
+      const key = this.string()
+      if (Object.hasOwn(result, key)) this.fail(`duplicate key ${key}`)
+      this.space()
+      this.take(":")
+      this.space()
+      result[key] = this.value()
+      this.space()
+      if (this.text[this.index] === "}") {
+        this.index += 1
+        return result
+      }
+      this.take(",")
+      this.space()
+    }
+  }
+}
+
+const codePointOrder = (left: string, right: string): number => {
+  const a = [...left]
+  const b = [...right]
+  let index = 0
+  while (index < Math.min(a.length, b.length)) {
+    const difference = a[index]!.codePointAt(0)! - b[index]!.codePointAt(0)!
+    if (difference !== 0) return difference
+    index += 1
+  }
+  return a.length - b.length
+}
+
+const canonicalArray = (value: ReadonlyArray<unknown>, parents: Set<object>): string => {
+  let index = 0
+  while (index < value.length) {
+    if (!Object.hasOwn(value, index)) throw new Error("sparse array")
+    index += 1
+  }
+  return `[${value.map((item) => canonical(item, parents)).join(",")}]`
+}
+
+const canonicalObject = (value: object, parents: Set<object>): string => {
+  if (Object.getPrototypeOf(value) !== Object.prototype) throw new Error("non-plain object")
+  const entries = Object.entries(value).map(([key, item]) => [key.normalize("NFC"), item] as const)
+  if (new Set(entries.map(([key]) => key)).size !== entries.length) {
+    throw new Error("normalized key collision")
+  }
+  entries.sort(([left], [right]) => codePointOrder(left, right))
+  return `{${entries.map(([key, item]) =>
+    `${JSON.stringify(key)}:${canonical(item, parents)}`).join(",")}}`
+}
+
+const canonical = (value: unknown, parents: Set<object>): string => {
+  if (value === null || typeof value === "boolean") return JSON.stringify(value)
+  if (typeof value === "string") return JSON.stringify(value.normalize("NFC"))
+  if (typeof value === "number") {
+    if (!Number.isSafeInteger(value) || Object.is(value, -0)) throw new Error("unsafe number")
+    return String(value)
+  }
+  if (typeof value !== "object") throw new Error("non-JSON value")
+  if (parents.has(value)) throw new Error("cyclic value")
+  parents.add(value)
+  try {
+    return Array.isArray(value)
+      ? canonicalArray(value, parents)
+      : canonicalObject(value, parents)
+  } finally {
+    parents.delete(value)
+  }
+}
+
+const frame = (value: Uint8Array): Uint8Array => {
+  const result = new Uint8Array(value.length + 4)
+  new DataView(result.buffer).setUint32(0, value.length, false)
+  result.set(value, 4)
+  return result
+}
+
+export const parseStrictJson = (text: string): Json => new StrictJsonParser(text).parse()
+export const encodeCanonicalJson = (value: unknown): string =>
+  `${canonical(value, new Set())}\n`
+export const hashFramed = (domain: string, parts: ReadonlyArray<Uint8Array>): string => {
+  const hash = createHash("sha256")
+  hash.update(frame(new TextEncoder().encode(domain.normalize("NFC"))))
+  parts.forEach((part) => {
+    hash.update(frame(part))
+  })
+  return hash.digest("hex")
+}
+export const hashCanonical = (domain: string, value: unknown): string =>
+  hashFramed(domain, [new TextEncoder().encode(encodeCanonicalJson(value))])