Python
//! Portable data contract for artifact-first coding handoff. Valid metadata is
//! NOT authorization, proof of artifact publication, Git integrity or successful
//! verification. Trusted adapters must check those facts before any I/O/admission.
use anyhow::{ensure, Result};
use serde::{Deserialize, Serialize};
pub mod config;
pub mod git;
pub mod integrate;
pub mod transfer;
pub mod workflow;
pub const VERSION: u8 = 1;
pub const MAX_BUNDLE_BYTES: u64 = 64 * 1024 * 1024;
fn component(value: &str, max: usize) -> Result<()> {
ensure!(
!value.is_empty()
&& value.len() <= max
&& value
.bytes()
.all(|c| c.is_ascii_alphanumeric() || b"_-".contains(&c)),
"Invalid handoff identity"
);
Ok(())
}
fn hex(value: &str, length: usize) -> Result<()> {
ensure!(
value.len() == length
&& value
.bytes()
.all(|c| c.is_ascii_digit() || (b'a'..=b'f').contains(&c)),
"Expected a pinned lowercase object/checksum identity"
);
Ok(())
}
fn repository(value: &str) -> Result<()> {
ensure!(
!value.is_empty()
&& value.len() <= 200
&& !value.starts_with(['/', '-'])
&& !value.contains("..")
&& value
.bytes()
.all(|c| c.is_ascii_alphanumeric() || b"_-./:@".contains(&c)),
"Invalid application repository identity"
);
// Treat this as an application reference, never a model-provided endpoint.
ensure!(
!value.contains("://"),
"Repository identity cannot be a download URL"
);
Ok(())
}
fn oid(value: &str, format: ObjectFormat) -> Result<()> {
hex(value, format.oid_length())?;
ensure!(
value.bytes().any(|c| c != b'0'),
"Null Git object ID is not a revision"
);
Ok(())
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ObjectFormat {
Sha1,
Sha256,
}
impl ObjectFormat {
pub fn oid_length(self) -> usize {
match self {
Self::Sha1 => 40,
Self::Sha256 => 64,
}
}
pub fn git_name(self) -> &'static str {
match self {
Self::Sha1 => "sha1",
Self::Sha256 => "sha256",
}
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Kind {
Source,
Submission,
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Producer {
pub team_id: String,
pub agent_id: String,
pub session_id: String,
}
impl Producer {
fn validate(&self) -> Result<()> {
component(&self.team_id, 80)?;
component(&self.session_id, 80)?;
component(&self.agent_id, 64)?;
ensure!(
self.agent_id.as_bytes()[0].is_ascii_alphabetic() && self.agent_id != "all",
"Invalid producer instance"
);
Ok(())
}
}
/// Reference to the existing artifact catalog, never a storage key or URL.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ArtifactRef {
pub session_id: String,
pub artifact_id: String,
pub size: u64,
pub sha256: String,
}
impl ArtifactRef {
pub fn validate(&self) -> Result<()> {
component(&self.session_id, 80)?;
component(&self.artifact_id, 40)?;
hex(&self.sha256, 64)?;
ensure!(
self.size > 0 && self.size <= MAX_BUNDLE_BYTES,
"Git bundle size outside artifact limit"
);
Ok(())
}
}
/// Collaborator-supplied report. Neither an approval nor a verified/integrated flag.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Report {
pub submitted_commit: String,
pub text: String,
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Manifest {
pub version: u8,
pub kind: Kind,
/// Application-owned repository identity; never interpreted as a remote URL.
pub repository: String,
pub producer: Producer,
pub object_format: ObjectFormat,
pub base_commit: String,
pub submitted_commit: String,
pub artifact: ArtifactRef,
#[serde(default)]
pub reports: Vec<Report>,
}
impl Manifest {
pub fn validate(&self) -> Result<()> {
ensure!(
self.version == VERSION,
"Unsupported handoff manifest version"
);
repository(&self.repository)?;
self.producer.validate()?;
self.artifact.validate()?;
ensure!(
self.artifact.session_id == self.producer.session_id,
"Artifact producer differs from handoff producer"
);
oid(&self.base_commit, self.object_format)?;
oid(&self.submitted_commit, self.object_format)?;
if self.kind == Kind::Source {
ensure!(
self.base_commit == self.submitted_commit,
"A source snapshot pins one exact revision"
);
}
ensure!(self.reports.len() <= 16, "Too many handoff reports");
for report in &self.reports {
ensure!(
report.submitted_commit == self.submitted_commit
&& !report.text.is_empty()
&& report.text.len() <= 8000,
"Report is not bounded to the submitted revision"
);
}
ensure!(
serde_json::to_vec(self)?.len() <= 32768,
"Handoff manifest too large"
);
Ok(())
}
pub fn digest(&self) -> Result<String> {
self.validate()?;
Ok(crate::bundle::digest(&serde_json::to_vec(&(
"coding-handoff-v1",
self,
))?))
}
/// Data binding only. The caller must still authorize the original producer,
/// read the published artifact and inspect the exact Git objects.
pub fn require_source(&self, repository: &str, base: &str) -> Result<()> {
self.validate()?;
ensure!(
self.repository == repository && self.base_commit == base,
"Handoff repository/base differs from the expected source"
);
Ok(())
}
}
/// Original import intent. A lost connection permits inspection of this exact
/// operation/destination only, never blindly repeating checkout or applying a
/// patch again. A digest alone is not permission to read someone else's artifact.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Import {
pub operation_id: String,
pub scope_digest: String,
pub manifest_digest: String,
pub directory: String,
}
impl Import {
pub fn validate(&self) -> Result<()> {
component(&self.operation_id, 80)?;
hex(&self.scope_digest, 64)?;
hex(&self.manifest_digest, 64)?;
ensure!(
!self.directory.contains(['\\', ':']),
"Checkout directory must be a portable relative path"
);
crate::runner::relative_path(&self.directory)?;
ensure!(
self.directory.split('/').next() != Some(".openworker"),
"Checkout cannot replace reserved harness bookkeeping"
);
Ok(())
}
pub fn require_manifest(&self, manifest: &Manifest) -> Result<()> {
self.validate()?;
ensure!(
self.manifest_digest == manifest.digest()?,
"Import intent belongs to another immutable handoff"
);
Ok(())
}
}
pub mod publication;