Skip to content

Better inheritance model #1

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 2 commits into from
Jul 7, 2026
Merged

Better inheritance model #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b7014cc
golang style inheritance
andrewbuchkovichLP Jul 6, 2026
d298e66
Refactor type inference pipeline and related UI
andrewbuchkovichLP Jul 7, 2026
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
40 changes: 26 additions & 14 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,20 +2,16 @@

**Define organizational agents once. Validate their composition. Compile them into the native shapes your teams already use.**

TypeFerence is an experimental reference implementation of a typed definition and compilation layer for AI agents. It replaces sprawling, duplicated instruction files with a small object model: single inheritance, contract-only interfaces, versioned skills, deterministic compilation, provenance, and artifact diffing.
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 v1 specification](docs/specification.md).
Read the [whitepaper](docs/whitepaper.md), the [rendered PDF](output/pdf/typeference-whitepaper.pdf), or the [draft v3 specification](docs/specification.md).

```text
system/object
└── helio/enterprise-agent
├── helio/person-agent
│ └── helio/executive-assistant
└── helio/repo-agent
└── helio/payments-repo-agent
helio/profiles/enterprise-defaults ──embedded by──> helio/profiles/person-defaults ──embedded by──> helio/executive-assistant
└─embedded by──> helio/profiles/repository-defaults ──embedded by──> helio/payments-repo-agent
```

`system/object` owns mechanics and emits no instructions. Organizations own their enterprise base, policies, voice, and domain knowledge.
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.

## Where it fits

Expand All @@ -29,7 +25,22 @@ TypeFerence source

[Agentic Resource Discovery](https://agenticresourcediscovery.org/) helps clients find and verify deployed capabilities. TypeFerence addresses the earlier authoring problem: producing compatible native artifacts from one governed definition. Discovery portability does not itself provide definition portability.

The long-term objective is behavioral equivalence: preserving declared organizational intent across supported hosts closely enough to be measured and governed. V1 provides the common typed source, deterministic adapters, and provenance needed to test that objective; it does not claim that different models or runtimes already behave identically.
The long-term objective is behavioral equivalence: preserving declared organizational intent across supported hosts closely enough to be measured and governed. V3 provides the common typed source, deterministic adapters, and provenance needed to test that objective; it does not claim that different models or runtimes already behave identically.

The v3 source shape is deliberately small:

```yaml
schemaVersion: 3
kind: agent
id: helio/payments-repo-agent@1.0.0
embeds:
- helio/profiles/repository-defaults@1.0.0
skills:
- ref: helio/skills/payments-repository-status@1.0.0
capability: helio/capabilities/repository-status@1.0.0
```

Use profiles for reusable organizational, domain, or team defaults that should participate in composition without producing their own target bundle.

## Quick start

Expand Down Expand Up @@ -88,18 +99,19 @@ TypeFerence does not hold signing keys. An external signer can produce detached

- `src/` - compiler, target adapters, CLI, and MCP runtime.
- `examples/helio/` - fictional cross-domain organization.
- `docs/specification.md` - normative v1 behavior.
- `docs/specification.md` - normative v3 behavior.
- `docs/whitepaper.md` and `output/pdf/typeference-whitepaper.pdf` - design paper.
- `tests/` - type-system, target, determinism, and MCP integration tests.

## Design boundaries

- One implementation parent; multiple contract-only interfaces.
- Interface and skill contracts are explicit and versioned.
- Agents may embed multiple profiles or agents; profiles may embed other profiles; local slots and capability bindings resolve promoted-name ambiguity.
- Interfaces may embed interfaces and are satisfied structurally, without declarations on agents.
- Capabilities are explicit, versioned method slots; skills are concrete implementations that bind those capabilities.
- Context is referenced and loaded only with the skill that needs it.
- 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 v1.
- No deployment state, hosted runtime, or model credentials in v3.
- 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
106 changes: 58 additions & 48 deletions dist/ard/ai-catalog.json
View file
Open in desktop

Large diffs are not rendered by default.

73 changes: 27 additions & 46 deletions dist/codex/executive-assistant/.typeference/bundle.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,11 @@
"id": "helio/executive-assistant@1.0.0",
"displayName": "Helio Executive Assistant",
"description": "Coordinates an executive\u0027s correspondence, briefings, and cross-agent requests.",
"abstract": false,
"lineage": [
"system/object@1.0.0",
"helio/enterprise-agent@1.0.0",
"helio/person-agent@1.0.0",
"helio/executive-assistant@1.0.0"
"emit": true,
"embeds": [
"helio/profiles/person-defaults@1.0.0"
],
"interfaces": [
"satisfies": [
"helio/interfaces/correspondent@1.0.0"
],
"slots": {
Expand All @@ -31,7 +28,7 @@
"skills": [
{
"dispatchName": "executive-assistant.prepare-brief",
"contractId": "helio/skills/prepare-brief@1.0.0",
"capabilityId": "helio/capabilities/prepare-brief@1.0.0",
"implementationId": "helio/skills/prepare-brief@1.0.0",
"description": "Assemble an executive brief, requesting repository evidence when needed.",
"instructions": "Build a decision-oriented brief from the supplied topic and evidence.\nWhen repository status is material, request \u0060payments-repo-agent.repository-status\u0060 and incorporate its returned evidence with attribution.\n",
Expand All @@ -45,8 +42,8 @@
],
"provenance": [
{
"field": "skill.contract",
"source": "helio/skills/prepare-brief@1.0.0"
"field": "skill.capability",
"source": "helio/capabilities/prepare-brief@1.0.0"
},
{
"field": "skill.implementation",
Expand All @@ -56,7 +53,7 @@
},
{
"dispatchName": "executive-assistant.triage-message",
"contractId": "helio/skills/triage-message@1.0.0",
"capabilityId": "helio/capabilities/triage-message@1.0.0",
"implementationId": "helio/skills/triage-message@1.0.0",
"description": "Classify an inbound message and recommend an accountable next action.",
"instructions": "Read the message and identify its sender, intent, urgency, decision owner, and requested deadline.\nSeparate facts from assumptions. Return a concise recommendation; do not send a reply.\n",
Expand All @@ -69,8 +66,8 @@
],
"provenance": [
{
"field": "skill.contract",
"source": "helio/skills/triage-message@1.0.0"
"field": "skill.capability",
"source": "helio/capabilities/triage-message@1.0.0"
},
{
"field": "skill.implementation",
Expand All @@ -80,69 +77,49 @@
}
],
"provenance": [
{
"field": "displayName",
"source": "system/object@1.0.0"
},
{
"field": "description",
"source": "system/object@1.0.0"
},
{
"field": "displayName",
"source": "helio/enterprise-agent@1.0.0"
},
{
"field": "description",
"source": "helio/enterprise-agent@1.0.0"
},
{
"field": "slots.organization",
"source": "helio/enterprise-agent@1.0.0"
"source": "helio/profiles/enterprise-defaults@1.0.0"
},
{
"field": "slots.safetyPolicy",
"source": "helio/enterprise-agent@1.0.0"
"source": "helio/profiles/enterprise-defaults@1.0.0"
},
{
"field": "workingNorms",
"source": "helio/enterprise-agent@1.0.0"
"source": "helio/profiles/enterprise-defaults@1.0.0"
},
{
"field": "workingNorms",
"source": "helio/enterprise-agent@1.0.0"
"source": "helio/profiles/enterprise-defaults@1.0.0"
},
{
"field": "contextFiles",
"source": "helio/enterprise-agent@1.0.0"
"source": "helio/profiles/enterprise-defaults@1.0.0"
},
{
"field": "contextFiles",
"source": "helio/enterprise-agent@1.0.0"
"source": "helio/profiles/enterprise-defaults@1.0.0"
},
{
"field": "displayName",
"source": "helio/person-agent@1.0.0"
},
{
"field": "description",
"source": "helio/person-agent@1.0.0"
"field": "embeds.helio/profiles/enterprise-defaults@1.0.0",
"source": "helio/profiles/person-defaults@1.0.0"
},
{
"field": "slots.principal",
"source": "helio/person-agent@1.0.0"
"source": "helio/profiles/person-defaults@1.0.0"
},
{
"field": "workingNorms",
"source": "helio/person-agent@1.0.0"
"source": "helio/profiles/person-defaults@1.0.0"
},
{
"field": "contextFiles",
"source": "helio/person-agent@1.0.0"
"source": "helio/profiles/person-defaults@1.0.0"
},
{
"field": "interfaces.helio/interfaces/correspondent@1.0.0",
"source": "helio/person-agent@1.0.0"
"field": "embeds.helio/profiles/person-defaults@1.0.0",
"source": "helio/executive-assistant@1.0.0"
},
{
"field": "displayName",
Expand All @@ -155,6 +132,10 @@
{
"field": "contextFiles",
"source": "helio/executive-assistant@1.0.0"
},
{
"field": "satisfies.helio/interfaces/correspondent@1.0.0",
"source": "helio/executive-assistant@1.0.0"
}
]
}
2 changes: 1 addition & 1 deletion dist/codex/payments-repo-agent/.agents/skills/repository-status/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ name: repository-status
description: "Report payments-service health with contract and reconciliation evidence."
---

Apply the repository-status contract, then include payment-contract compatibility, reconciliation checks, and rollback readiness.
Apply the repository-status capability, then include payment-contract compatibility, reconciliation checks, and rollback readiness.
Do not report the service healthy when any required financial-control signal is unavailable.

## Context loaded on invocation
Expand Down
69 changes: 25 additions & 44 deletions dist/codex/payments-repo-agent/.typeference/bundle.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,11 @@
"id": "helio/payments-repo-agent@1.0.0",
"displayName": "Helio Payments Repository Agent",
"description": "Specializes repository assistance for the fictional payments service.",
"abstract": false,
"lineage": [
"system/object@1.0.0",
"helio/enterprise-agent@1.0.0",
"helio/repo-agent@1.0.0",
"helio/payments-repo-agent@1.0.0"
"emit": true,
"embeds": [
"helio/profiles/repository-defaults@1.0.0"
],
"interfaces": [
"satisfies": [
"helio/interfaces/repository-observer@1.0.0"
],
"slots": {
Expand All @@ -31,10 +28,10 @@
"skills": [
{
"dispatchName": "payments-repo-agent.repository-status",
"contractId": "helio/skills/repository-status@1.0.0",
"capabilityId": "helio/capabilities/repository-status@1.0.0",
"implementationId": "helio/skills/payments-repository-status@1.0.0",
"description": "Report payments-service health with contract and reconciliation evidence.",
"instructions": "Apply the repository-status contract, then include payment-contract compatibility, reconciliation checks, and rollback readiness.\nDo not report the service healthy when any required financial-control signal is unavailable.\n",
"instructions": "Apply the repository-status capability, then include payment-contract compatibility, reconciliation checks, and rollback readiness.\nDo not report the service healthy when any required financial-control signal is unavailable.\n",
"inputSchema": "{\u0022type\u0022:\u0022object\u0022,\u0022properties\u0022:{\u0022focus\u0022:{\u0022type\u0022:\u0022string\u0022}},\u0022additionalProperties\u0022:false}",
"outputSchema": "{\u0022type\u0022:\u0022object\u0022,\u0022properties\u0022:{\u0022status\u0022:{\u0022type\u0022:\u0022string\u0022},\u0022evidence\u0022:{\u0022type\u0022:\u0022array\u0022,\u0022items\u0022:{\u0022type\u0022:\u0022string\u0022}},\u0022risks\u0022:{\u0022type\u0022:\u0022array\u0022,\u0022items\u0022:{\u0022type\u0022:\u0022string\u0022}}},\u0022required\u0022:[\u0022status\u0022,\u0022evidence\u0022,\u0022risks\u0022]}",
"contextFiles": [
Expand All @@ -45,8 +42,8 @@
],
"provenance": [
{
"field": "skill.contract",
"source": "helio/skills/repository-status@1.0.0"
"field": "skill.capability",
"source": "helio/capabilities/repository-status@1.0.0"
},
{
"field": "skill.implementation",
Expand All @@ -56,69 +53,49 @@
}
],
"provenance": [
{
"field": "displayName",
"source": "system/object@1.0.0"
},
{
"field": "description",
"source": "system/object@1.0.0"
},
{
"field": "displayName",
"source": "helio/enterprise-agent@1.0.0"
},
{
"field": "description",
"source": "helio/enterprise-agent@1.0.0"
},
{
"field": "slots.organization",
"source": "helio/enterprise-agent@1.0.0"
"source": "helio/profiles/enterprise-defaults@1.0.0"
},
{
"field": "slots.safetyPolicy",
"source": "helio/enterprise-agent@1.0.0"
"source": "helio/profiles/enterprise-defaults@1.0.0"
},
{
"field": "workingNorms",
"source": "helio/enterprise-agent@1.0.0"
"source": "helio/profiles/enterprise-defaults@1.0.0"
},
{
"field": "workingNorms",
"source": "helio/enterprise-agent@1.0.0"
"source": "helio/profiles/enterprise-defaults@1.0.0"
},
{
"field": "contextFiles",
"source": "helio/enterprise-agent@1.0.0"
"source": "helio/profiles/enterprise-defaults@1.0.0"
},
{
"field": "contextFiles",
"source": "helio/enterprise-agent@1.0.0"
},
{
"field": "displayName",
"source": "helio/repo-agent@1.0.0"
"source": "helio/profiles/enterprise-defaults@1.0.0"
},
{
"field": "description",
"source": "helio/repo-agent@1.0.0"
"field": "embeds.helio/profiles/enterprise-defaults@1.0.0",
"source": "helio/profiles/repository-defaults@1.0.0"
},
{
"field": "slots.repository",
"source": "helio/repo-agent@1.0.0"
"source": "helio/profiles/repository-defaults@1.0.0"
},
{
"field": "workingNorms",
"source": "helio/repo-agent@1.0.0"
"source": "helio/profiles/repository-defaults@1.0.0"
},
{
"field": "contextFiles",
"source": "helio/repo-agent@1.0.0"
"source": "helio/profiles/repository-defaults@1.0.0"
},
{
"field": "interfaces.helio/interfaces/repository-observer@1.0.0",
"source": "helio/repo-agent@1.0.0"
"field": "embeds.helio/profiles/repository-defaults@1.0.0",
"source": "helio/payments-repo-agent@1.0.0"
},
{
"field": "displayName",
Expand All @@ -131,6 +108,10 @@
{
"field": "contextFiles",
"source": "helio/payments-repo-agent@1.0.0"
},
{
"field": "satisfies.helio/interfaces/repository-observer@1.0.0",
"source": "helio/payments-repo-agent@1.0.0"
}
]
}
Loading
Loading