# Structure of Archify's Diagnostic Objects: Schema, Properties, and Usage

> Understand Archify's diagnostic objects schema: code, severity, subject, evidence, and supportedFixes. Learn how this structure enables deterministic error reporting and automated repair workflows.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: internals
- Published: 2026-08-28

---

**Archify's diagnostic objects follow a strict five-property schema—`code`, `severity`, `subject`, `evidence`, and `supportedFixes`—that enables deterministic error reporting and automated repair workflows.**

The `tt-a1i/archify` repository uses these structured diagnostics to communicate validation failures, runtime errors, and repair suggestions across its skill ecosystem. Understanding the exact structure of Archify's diagnostic objects is essential for developers building custom skills or integrating with Archify's repair receipt system.

## The Five Required Properties of Every Diagnostic

Every diagnostic emitted by the Archify engine conforms to a rigid contract. According to assertions in `test/repair-receipt.test.mjs`, a valid diagnostic object must contain five required fields, with optional additional metadata permitted.

| Property | Type | Description |
|----------|------|-------------|
| **`code`** | `string` | A stable, namespaced identifier for the rule that generated the diagnostic (e.g., `schema/additionalProperties`, `output/input-alias`). |
| **`severity`** | `"error"` \| `"warning"` \| `"info"` | The seriousness of the issue. Errors halt execution, warnings allow continuation, and info messages are advisory. |
| **`subject`** | `object` | A JSON-pointer-style description of the affected resource, using domain-specific keys like `path`, `output`, or `check`. |
| **`evidence`** | `object` | Concrete data explaining why the diagnostic was raised. Shape varies by diagnostic type (e.g., `reason`, `rowCount`). |
| **`supportedFixes`** | `string[]` | An array of human-readable suggestions or machine-parsable actions that can resolve the problem. |

### code

The `code` property provides a stable identifier for the specific rule violation. As implemented in `tt-a1i/archify`, these codes follow a hierarchical namespace pattern such as `input/json-parse` or `output/symlink-cycle`. This naming convention allows automated tools to parse the category and sub-category of any error without parsing free-form text.

### severity

The `severity` field controls execution flow. Valid values are strictly limited to three literals: `"error"`, `"warning"`, and `"info"`. When `severity` equals `"error"`, the current operation blocks until resolved, whereas `"warning"` permits the skill to complete while logging the issue for review.

### subject

The `subject` object acts as a locator, identifying exactly which file, configuration key, or output path triggered the diagnostic. According to [`docs/authoring-cookbook.md`](https://github.com/tt-a1i/archify/blob/main/docs/authoring-cookbook.md), this property uses JSON-pointer semantics but wraps them in domain-specific keys. For example, `{ path: '/meta/legend' }` points to a specific metadata field, while `{ output: '/public/assets/logo.svg' }` identifies a build artifact.

### evidence

The `evidence` object contains immutable contextual data that justifies the diagnostic's existence. The shape is polymorphic depending on the `code`: a JSON parse error includes `{ reason: 'Unexpected token...' }`, while a symlink cycle includes `{ cycle: ['/path/a', '/path/b'] }`. As noted in [`docs/research-architecture-delta-pr-proof-2026-07-23.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-architecture-delta-pr-proof-2026-07-23.md), this evidence ensures that diagnostics are self-contained and serializable for deterministic receipts.

### supportedFixes

The `supportedFixes` array lists actionable resolutions. Each entry is a string describing either a human-readable instruction or a machine-parsable command. For repairable diagnostics, this array is guaranteed non-empty, enabling the automated repair workflows demonstrated in `scripts/package-smoke.mjs`.

## Real-World Examples from the Test Suite

The following examples from `test/repair-receipt.test.mjs` illustrate how these properties combine in practice.

A malformed input diagnostic:

```javascript
const jsonParseDiagnostic = {
  code: 'input/json-parse',
  severity: 'error',
  subject: { input: '/meta/user' },
  evidence: { reason: 'Unexpected token < in JSON at position 0' },
  supportedFixes: ['repair the JSON syntax and run validation again']
};

```

A filesystem cycle diagnostic:

```javascript
const symlinkCycleDiagnostic = {
  code: 'output/symlink-cycle',
  severity: 'error',
  subject: { output: '/public/assets/logo.svg' },
  evidence: { cycle: ['/public/assets/logo.svg', '/public/assets/logo.png'] },
  supportedFixes: ['remove the symlink that creates the cycle']
};

```

## How Diagnostics Flow Through the System

Archify's diagnostic structure is not merely a logging format—it is the backbone of the repair receipt system.

[`docs/authoring-cookbook.md`](https://github.com/tt-a1i/archify/blob/main/docs/authoring-cookbook.md) defines the contract that skill authors must follow when emitting diagnostics, ensuring that all skills produce compatible error objects. When the engine packages a skill, `scripts/package-smoke.mjs` consumes these diagnostics to validate that no errors exist before publication. Finally, [`docs/research-architecture-delta-pr-proof-2026-07-23.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-architecture-delta-pr-proof-2026-07-23.md) describes how diagnostics are sorted and serialized into deterministic repair receipts, allowing agents to compare states across runs.

## Summary

- Archify diagnostic objects require exactly five properties: `code`, `severity`, `subject`, `evidence`, and `supportedFixes`.
- The `code` uses dot-slash namespacing for stable rule identification.
- `severity` controls execution flow with three strict levels: error, warning, and info.
- `subject` provides JSON-pointer-style locators, while `evidence` contains immutable contextual data.
- `supportedFixes` enables automated repair by listing concrete resolution steps.
- Source definitions appear in `test/repair-receipt.test.mjs`, [`docs/authoring-cookbook.md`](https://github.com/tt-a1i/archify/blob/main/docs/authoring-cookbook.md), and related architecture documents.

## Frequently Asked Questions

### What properties are mandatory in an Archify diagnostic object?

Every diagnostic must include `code`, `severity`, `subject`, `evidence`, and `supportedFixes`. Optional fields such as `message` or `detail` may appear for human readability, but the five core properties are required for structured repair receipts and automated processing.

### How does the severity field affect Archify's behavior?

When `severity` is set to `"error"`, the current operation halts immediately, blocking skill execution until the issue is resolved. `"warning"` allows the process to continue while logging the issue, and `"info"` provides advisory output that does not affect exit codes.

### Where are diagnostic structures enforced in the codebase?

Test assertions in `test/repair-receipt.test.mjs` validate the full object shape, while [`docs/authoring-cookbook.md`](https://github.com/tt-a1i/archify/blob/main/docs/authoring-cookbook.md) documents the contract for skill authors. Runtime consumption occurs in `scripts/package-smoke.mjs`, which checks for diagnostic presence before packaging.

### How do supportedFixes enable automated repairs?

The `supportedFixes` array provides a machine-parseable list of actions that resolve the diagnostic. By standardizing this field, Archify permits automated agents to read the array and apply fixes without human intervention, forming the basis of the repository's repair receipt workflow.