diff --git a/README.md b/README.md index fd28aa5..8ac1bdb 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ TypeFerence is an experimental reference implementation of a typed definition and compilation layer for AI agents. It replaces sprawling, duplicated instruction files with Go-like composition: reusable profiles, agent embedding, structurally satisfied interfaces, versioned capabilities, skill implementations, deterministic compilation, provenance, and artifact diffing. -Read the [whitepaper](docs/whitepaper.md), the [rendered PDF](output/pdf/typeference-whitepaper.pdf), or the [draft v3 specification](docs/specification.md). +Read the [whitepaper](docs/whitepaper.md), the [rendered PDF](output/pdf/typeference-whitepaper.pdf), the [draft v3 specification](docs/specification.md), or the [ARD alignment notes](docs/ard-alignment.md). ```text helio/profiles/enterprise-defaults ──embedded by──> helio/profiles/person-defaults ──embedded by──> helio/executive-assistant @@ -13,6 +13,12 @@ helio/profiles/enterprise-defaults ──embedded by──> helio/profiles/perso There is no universal root and no nominal `implements` declaration. Agents embed reusable profiles, promoted behavior is checked for ambiguity, and interfaces are discovered from the resulting slot and capability set. +## Why not just write AGENTS.md? + +You can, and for one small agent you often should. TypeFerence becomes useful when those instructions need reuse, review, specialization, provenance, and repeatable output across several agents or hosts. + +Agent runtime system prompts are like machine code: they are what the model actually consumes at execution time. `AGENTS.md` and similar host-native instruction files are like assembly language: readable and controllable, but still close to one runtime's concrete shape. TypeFerence is the higher-level language above that. It lets teams model profiles, capabilities, skills, context, and trust metadata once, then compile the result into `AGENTS.md`, Copilot instructions, Cursor rules, neutral bundles, and ARD catalog entries. + ## Where it fits ```text @@ -112,6 +118,7 @@ TypeFerence does not hold signing keys. An external signer can produce detached - Target adapters emit platform-native shapes while retaining the portable fields each target supports. - Build output is deterministic and carries provenance. - No deployment state, hosted runtime, or model credentials in v3. +- No ARD registry lifecycle, federation, dependency, install-safety, or deployment metadata in core TypeFerence semantics. - Structural validation does not guarantee identical LLM behavior across models or hosts. - ARD publication wraps selected target outputs; it is not itself a compilation target or execution runtime. diff --git a/docs/ard-alignment.md b/docs/ard-alignment.md new file mode 100644 index 0000000..3e28202 --- /dev/null +++ b/docs/ard-alignment.md @@ -0,0 +1,37 @@ +# ARD Alignment Notes + +Status: reviewed against open `ards-project/ard-spec` issues on July 7, 2026. + +TypeFerence should remain a typed authoring and compilation layer. ARD should remain the discovery, registry, publication, and deployed-resource metadata layer. The current ARD issue backlog reinforces that split. + +That leaves TypeFerence in distinct territory: it models reusable agent source before runtime artifacts exist. ARD can advertise an `AGENTS.md` bundle, an MCP server, an A2A card, an API, or a workflow; it does not define the high-level language that produced a family of host-native agent instruction artifacts. + +## Keep Out of TypeFerence Core + +The following ARD proposals are adjacent to TypeFerence output, but should not become TypeFerence source semantics: + +| ARD issue | Topic | TypeFerence stance | +| --- | --- | --- | +| [#55](https://github.com/ards-project/ard-spec/issues/55), [#45](https://github.com/ards-project/ard-spec/issues/45) | Release policy, lifecycle, deprecation, migration windows | TypeFerence resource IDs include versions and compiled entries carry versions. Discovery-time lifecycle policy belongs to ARD catalog metadata or a future ARD extension. | +| [#44](https://github.com/ards-project/ard-spec/issues/44) | Deployment metadata, instances, regions, environments | TypeFerence emits static target artifacts and an MCP dispatch package. It must not model runtime instances, replicas, regions, or environment availability. | +| [#42](https://github.com/ards-project/ard-spec/issues/42), [#21](https://github.com/ards-project/ard-spec/issues/21), [#20](https://github.com/ards-project/ard-spec/issues/20), [#22](https://github.com/ards-project/ard-spec/issues/22) | Dependencies, auth hints, access, monetization, filter dimensions | TypeFerence can reference local context and preserve skill contracts. It should not define discovery-time credential feasibility, commercial terms, external dependency manifests, or registry filter semantics. | +| [#43](https://github.com/ards-project/ard-spec/issues/43) | Install-time safety envelope | TypeFerence target bundles are installable artifacts, but consent, revocation, smoke checks, kill switches, and scope grants belong to an install manifest or host installer. | +| [#53](https://github.com/ards-project/ard-spec/issues/53) | Registry federation, mutual trust, cross-registry provenance | TypeFerence provenance links compiled bundles back to canonical TypeFerence source. It should not define registry federation handshakes, trust state machines, or canonical registry selection. | +| [#47](https://github.com/ards-project/ard-spec/issues/47), [#24](https://github.com/ards-project/ard-spec/issues/24) | DID methods, domainless publishers, relay-addressed resources | TypeFerence may validate declared identity syntax for emitted catalog entries. DID method resolution, DNS/relay naming semantics, and publisher authority rules belong to ARD and identity ecosystems. | +| [#41](https://github.com/ards-project/ard-spec/issues/41), [#52](https://github.com/ards-project/ard-spec/issues/52) | Attestation types and trust/compliance caveats | TypeFerence may carry publisher-supplied trust manifest metadata. It must not interpret attestations as compliance, safety, SLSA, or runtime-governance verdicts. | +| [#37](https://github.com/ards-project/ard-spec/issues/37), [#27](https://github.com/ards-project/ard-spec/issues/27) | Recognized media types for skills and bundles | TypeFerence package media types are experimental. Standard ARD-recognized media types should be adopted when ARD or the relevant artifact spec settles them. | +| [#40](https://github.com/ards-project/ard-spec/issues/40), [#34](https://github.com/ards-project/ard-spec/issues/34), [#23](https://github.com/ards-project/ard-spec/issues/23), [#19](https://github.com/ards-project/ard-spec/issues/19), [#18](https://github.com/ards-project/ard-spec/issues/18) | Registry implementation, API conformance, AI Catalog relationship, governance | TypeFerence should consume stable ARD/AI Catalog behavior and keep its own compiler spec scoped to source resources, resolution, target artifacts, and optional publication. | + +Reference publisher issues such as [#51](https://github.com/ards-project/ard-spec/issues/51), [#14](https://github.com/ards-project/ard-spec/issues/14), [#13](https://github.com/ards-project/ard-spec/issues/13), [#11](https://github.com/ards-project/ard-spec/issues/11), and [#10](https://github.com/ards-project/ard-spec/issues/10) are useful examples of deployed catalogs. They do not change TypeFerence's core boundary unless they expose a recurring packaging need for compiled static agent bundles. + +## Positive Integration Points + +TypeFerence should integrate with ARD only at clear publication boundaries: + +1. Emit a canonical TypeFerence source-package catalog entry for audit and reproducible compilation. +2. Emit separately versioned target-bundle entries for concrete compiled artifacts. +3. Preserve `derivedFrom` provenance from each target bundle to the canonical source package. +4. Preserve publisher-supplied AI Catalog Trust Manifest fields without dereferencing or judging them. +5. Adopt ARD-standard media types, lifecycle fields, dependency fields, install envelopes, and federation metadata only as catalog-entry metadata when those proposals stabilize. + +This lets TypeFerence avoid duplicating ARD while still producing artifacts that ARD can advertise. diff --git a/docs/ard-typeference-issue-draft.md b/docs/ard-typeference-issue-draft.md new file mode 100644 index 0000000..05038f6 --- /dev/null +++ b/docs/ard-typeference-issue-draft.md @@ -0,0 +1,161 @@ +# GitHub Issue Draft: ARD Authoring Layer Question + +## Title + +Design: pre-publication authoring/compilation layer for agent resources -- in scope for ARD? + +## Body + +### Summary + +I would like to sanity-check whether the ecosystem around ARD needs guidance for a **pre-publication authoring/compilation layer**. + +Before a publisher advertises something through ARD, they need a coherent way to author, compose, and build the actual resources they are publishing: instructions, skills, context references, target formats, provenance, trust metadata, and so on. ARD is focused on discovery and verification of published artifacts, but the "how do I produce something good to publish?" step seems to be left to each project. + +My question is: **does ARD, or the broader ecosystem around ARD, need guidance for this layer, or is it intentionally outside ARD's scope?** + +The thing I am trying to avoid is a world where discovery becomes standardized, but the artifacts being discovered are still hand-authored, host-specific instruction blobs with unclear provenance, inconsistent build process, and no reproducible trust story. + +I am not asking ARD to adopt a particular compiler or source language. I am asking whether the ecosystem needs a common way to talk about pre-compiled or authored agent resources, their target runtime, and the provenance/trust metadata connecting those resources to the source and build process that produced them. + +A concrete example is **TypeFerence**, a small reference experiment I am working on. It treats agent definitions as typed source and compiles them into host-native artifacts such as `AGENTS.md`, Copilot instructions, Cursor rules, neutral bundles, and optional ARD catalog entries. It is not a runtime, registry, identity system, deployment system, or discovery protocol. + +The analogy is: + +- runtime system prompts are like machine code +- `AGENTS.md` and similar host-native instruction files are like assembly language +- TypeFerence is a higher-level language that compiles into those native forms + +This issue is not asking ARD to standardize TypeFerence itself, and it is not asking ARD to become a source-code registry or build system. If the answer is "this is out of scope; use custom media types and provenance fields," that is useful feedback too. + +### Non-goals + +This issue is not proposing that ARD: + +- standardize TypeFerence or any particular authoring language +- store source code +- define deployment, install, consent, runtime, lifecycle, federation, or identity semantics +- require clients to compile source during discovery or invocation + +The question is only whether there should be guidance for pre-publication artifact production, target identity, provenance, digests, and trust-manifest signing inputs. + +### Why this seems adjacent to ARD + +ARD already does the right thing by staying artifact-agnostic: it can advertise MCP servers, A2A cards, APIs, workflows, skill artifacts, catalogs, and other resources without owning each artifact's internal format. + +Pre-compiled or authored agent resources may fit that model: + +1. A publisher may want to advertise a precompiled bundle for a concrete host target. +2. Each compiled bundle should point back to source provenance without requiring ARD to store or standardize that source. +3. Discovery clients should not assume that a static bundle is directly callable. +4. Installation, consent, deployment, identity resolution, lifecycle, and federation should remain separate ARD / host / installer concerns. + +The practical concern is that without some shared guidance, different projects may invent incompatible ways to describe "this agent resource was built from that source, for this target, with this digest, under this publisher identity." + +### Example catalog shape + +If this layer is worth recognizing, a catalog entry for a pre-compiled static agent bundle might look something like this. This is meant as an example, not a proposed normative format: + +```json +{ + "identifier": "urn:air:example.com:typeference:codex:payments-repo-agent", + "displayName": "Payments Repo Agent (codex)", + "type": "application/vnd.typeference.target-bundle+json", + "description": "Precompiled Codex artifact bundle.", + "version": "1.0.0", + "capabilities": [ + "payments-repo-agent.repository-status" + ], + "data": { + "schemaVersion": 1, + "target": "codex", + "agentId": "example/payments-repo-agent@1.0.0", + "files": [] + }, + "metadata": { + "generatedBy": "TypeFerence", + "sourceUri": "https://github.com/example/agents/tree/0123456789abcdef", + "sourceDigest": "sha256:...", + "target": "codex" + }, + "trustManifest": { + "identity": "https://example.com", + "identityType": "https", + "provenance": [ + { + "relation": "derivedFrom", + "sourceId": "https://github.com/example/agents/tree/0123456789abcdef", + "sourceDigest": "sha256:..." + } + ] + } +} +``` + +The media types above are experimental placeholders from the TypeFerence prototype. They are included only to make the shape concrete, not as a request that ARD bless these exact strings. + +### Relationship to existing ARD issues + +The closest existing threads seem to be #27 and #37 on recognized artifact/media types. This also touches the `trustManifest` conversation in #41, #52, and #40, especially around what evidence an attestation or signed manifest does and does not prove. + +I am explicitly trying not to overlap with lifecycle and release policy (#45, #55), install-time safety envelopes (#43), deployment metadata (#44), dependencies/auth/access metadata (#42, #21, #22), federation (#53), or identity/relay naming (#47, #24). + +The pre-publication authoring/compiler layer should not define those things. A build tool can emit or preserve ARD metadata once ARD standardizes it, but those fields should not participate in the tool's own source-language semantics unless that language chooses to model them separately. + +### Trust Manifest implications + +This may also have implications for the AI Catalog / ARD `trustManifest` format. + +A build tool or compiler can be a natural producer of trust-manifest metadata if the target shape is sufficiently stable. The important separation is that the tool produces deterministic signing input, while a publisher-controlled key signs the claim. For example, a tool can deterministically emit: + +- `provenance` entries linking a compiled bundle to the source URI, commit, package reference, or digest it was built from +- an artifact digest for the compiled bundle +- publisher-supplied `identity`, `identityType`, `trustSchema`, and `attestations` +- signing input for an external signer +- a detached signature once an external signing step has completed + +The resulting verification chain can stay language-agnostic: + +1. Source exists at a URI, commit, package reference, and/or digest. +2. A build tool produces a deterministic target resource or bundle. +3. The tool computes the target artifact digest and emits a Trust Manifest payload saying the artifact was derived from that source. +4. A publisher-controlled signing key signs the payload. +5. An ARD registry verifies the signature, signer identity, source provenance fields, and artifact digest without understanding the tool's source language or composition semantics. + +That fits the direction of #41 and #52: attestations and filters should remain carefully scoped evidence, not broad compliance or safety verdicts. It also relates to #40's practical conformance question about what counts as an acceptable `trustManifest` for a publisher. + +The pre-publication build angle adds one design pressure: if ARD / AI Catalog standardizes canonicalization, digest scope, provenance relations, signer identity binding, and detached-signature placement, then build tools can target that format directly and produce reproducible trust metadata for published agent resources. If those pieces remain underspecified, each tool will likely invent slightly different metadata keys for source provenance, artifact integrity, and signing payloads. + +### Questions + +1. Is a pre-publication authoring/compilation layer even a problem worth solving, or will future models and tools make ad hoc prompt/resource management sufficient? +2. Assuming it is worth addressing, should ARD or the broader ecosystem provide any guidance for this layer, or is it intentionally out of scope? +3. If it is in scope, what level of guidance would be useful? + - Recognizing pre-compiled or authored agent resources as catalog resources. + - Documenting `derivedFrom` provenance from published artifacts back to source repositories, commits, packages, or digests. + - Defining enough Trust Manifest canonicalization, digest, provenance, signer identity, and signature semantics for build tools to target it reproducibly. + - Distinguishing static host instruction bundles from directly callable resources such as MCP servers, A2A agents, and OpenAPI endpoints. +4. If it is out of scope, is this a real coordination problem that belongs in a different venue than ARD, or is per-tool fragmentation here an acceptable or expected outcome? + +### Example implementation + +[TypeFerence](https://github.com/buchk/TypeFerence) currently compiles a small typed source model into: + +- neutral `AGENTS.md` bundles +- Codex `AGENTS.md` plus skill folders and MCP config +- GitHub Copilot instructions / custom agent profile files +- Cursor rules +- optional ARD `ai-catalog.json` publication with compiled target-bundle entries and source provenance + +The important boundary I am trying to preserve is: + +- an authoring/compiler tool owns structural composition, deterministic compilation, artifact diffs, and source-to-bundle provenance. +- ARD owns discovery, registry behavior, publication metadata, trust signaling, lifecycle, federation, deployment metadata, and how consumers find resources. + +I am looking for feedback on whether that boundary seems complementary, whether ARD or the surrounding ecosystem needs any standard hooks at this layer, or whether I am thinking about the problem at the wrong level. + +### Personal note + +I am at the edge of my depth here. I built what feels like a useful reference implementation because the problem of maintaining coherent behavior across many agents feels real to me, but I genuinely do not know how this looks from the perspective of standards maintainers, large platform teams, or people with deeper experience in this space. + +That is why I am asking. I want the feedback, even if the answer is "this layer is not needed," "this belongs entirely outside ARD," or "you are thinking about the problem at the wrong level." diff --git a/docs/specification.md b/docs/specification.md index b3672bc..8c6671d 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -8,6 +8,8 @@ TypeFerence defines structural composition and deterministic compilation of agen Agentic Resource Discovery (ARD) can advertise compiled TypeFerence outputs. ARD identifies and locates artifacts; TypeFerence produces target-specific artifacts before publication. Invocation remains the responsibility of MCP, A2A, OpenAPI, or a host-native mechanism. +TypeFerence does not define ARD registry lifecycle, release policy, deprecation, deployment instance metadata, dependency manifests, auth feasibility hints, access or monetization policy, install-time consent envelopes, registry federation, DID resolution rules, relay addressing, search filters, registry APIs, or ARD governance. If ARD standardizes any of those fields, TypeFerence MAY preserve them as publication metadata, but they MUST NOT participate in TypeFerence embedding, composition, skill dispatch, or target compilation semantics. + ## Resource identity A source tree contains YAML documents with `schemaVersion: 3`, a `kind`, and an `id`. IDs use `namespace/name@semantic-version`. Supported kinds are `agent`, `profile`, `interface`, `capability`, and `skill`. @@ -79,6 +81,8 @@ When requested, the reference compiler emits: The v1 package media types are experimental `application/vnd.typeference.source-package+json` and `application/vnd.typeference.target-bundle+json`. A target bundle contains the exact generated files and names its intended runtime. ARD discovery does not install those files or make one target's format executable by another target. Directly callable services SHOULD instead be published using their native MCP, A2A, OpenAPI, or successor artifact card after deployment. +TypeFerence-generated catalog entries intentionally omit ARD-owned lifecycle, deployment, dependency, install-safety, federation, and registry-search metadata unless supplied as external publication metadata. TypeFerence source versions describe authoring resources; they do not imply discovery-time availability, migration windows, deprecation state, supported regions, credential requirements, commercial terms, or registry federation consent. + ### Trust metadata compilation TypeFerence targets the draft AI Catalog Trust Manifest as published at . Draft evolution MAY require corresponding changes in a future TypeFerence schema version. diff --git a/docs/whitepaper.md b/docs/whitepaper.md index 60ada21..c4bc25d 100644 --- a/docs/whitepaper.md +++ b/docs/whitepaper.md @@ -14,6 +14,8 @@ TypeFerence treats agent definitions as typed source code. Organizations define Markdown is an excellent runtime format and a poor organization-wide type system. As agent adoption grows, similar instructions appear in many places. Security language diverges. Status-reporting methods acquire incompatible meanings. A policy correction must be rediscovered and edited in dozens of files. Reviewers can see textual differences but cannot reliably identify which behavior was embedded, replaced, or accidentally omitted. +This is the answer to "why not just write `AGENTS.md` directly?" Direct instruction files are the right level for small, local customization, but they are not the best level for organization-wide reuse. Agent runtime system prompts are like machine code: they are the concrete behavior stream the model consumes. `AGENTS.md`, Copilot instructions, Cursor rules, and similar files are like assembly language: human-readable and powerful, but still tied to one host's instruction shape. TypeFerence is the higher-level language above them, where teams can express shared concepts once and compile them into the host-native forms. + The underlying problem is repeated domain modeling. Each local agent solves identity, capability, context selection, and governance again. Vendor portability is one visible symptom; duplicated organizational reasoning is the larger cost. TypeFerence introduces a canonical typed layer above runtime Markdown. Source definitions are small. Skills conditionally reference context. Compilation is deterministic. The generated artifacts remain ordinary files that existing tools understand.