Skip to content

Document ARD alignment and clarify TypeFerence scope #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
buchk merged 1 commit into from
Jul 7, 2026
Merged

Document ARD alignment and clarify TypeFerence scope #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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.

Expand Down
37 changes: 37 additions & 0 deletions docs/ard-alignment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
161 changes: 161 additions & 0 deletions docs/ard-typeference-issue-draft.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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."
Loading
Loading