b0c774c2e3
Narrows P3 of ADR-1411 (Resolution Provenance, epic #1411) based on an adversarial fit-analysis that showed a single Resolution<T> envelope adopted by agent-skills, capability-state, and capability-writer fails the deletion test: configured/reason are meaningless for capability verbs, and capability-writer's errors[] (operation-not-applied) cannot fold into warnings[]. The only genuinely shared seam is warnings: string[]. Changes: - src/resolution.cts: new pure types+builder leaf — exports Resolution<T> {value, configured, reason, warnings}, makeResolution<T>() builder, and AgentSkillsValue {block, skills_count}. No other src/ imports. - src/init.cts: cmdAgentSkills --json IR gains additive value:{block, skills_count} field (built via makeResolution). All existing flat fields (agent_type, block, skills_count, warnings, configured, reason, source, degraded) are retained unchanged for back-compat. - src/capability-state.cts: doc comment on ResolveCapabilityRuntimeStateResult naming it the canonical read-verb envelope. No JSON change. - src/capability-writer.cts: doc comment on SetCapabilityStateResult naming it the canonical mutation-verb result (warnings=advisory, errors=operation- not-applied). No JSON change. - CONTEXT.md: new ### Resolution Convention glossary entry after ### Resolution Provenance. - docs/adr/1411-resolution-provenance.md: P3 narrowing amendment appended. - tests/resolution.test.cjs: 9 unit tests for makeResolution (new). - tests/agent-skills.test.cjs: 2 P3 tests for value.block/value.skills_count and back-compat of all flat fields. All 277 tests pass (5 suites). npm run lint clean. All lint checks pass. Part of #1411 Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
65 lines
2.6 KiB
TypeScript
65 lines
2.6 KiB
TypeScript
/**
|
|
* Resolution Convention — canonical shape for config-interpreting read verbs.
|
|
*
|
|
* Extracted as the anchor for ADR-1411 P3 (Resolution Provenance, #1416).
|
|
* Exports the `Resolution<T>` envelope used when a verb reads and interprets
|
|
* configuration (e.g. agent-skills). Not used by mutation verbs (see
|
|
* capability-writer's `SetCapabilityStateResult` for the mutation shape) or
|
|
* plain read verbs (see capability-state's `ResolveCapabilityRuntimeStateResult`).
|
|
*
|
|
* This is a pure types+builder leaf — no other src/ imports.
|
|
*/
|
|
|
|
// ─── Resolution envelope ──────────────────────────────────────────────────────
|
|
|
|
/**
|
|
* Canonical output envelope for **config-interpreting read verbs**.
|
|
*
|
|
* - `value` — the resolved domain value (T)
|
|
* - `configured` — true when the caller's agent/key was found in config
|
|
* - `reason` — machine-readable resolution outcome (e.g. 'resolved',
|
|
* 'not_configured', 'configured_empty', 'configured_unresolved')
|
|
* - `warnings` — diagnostic messages (empty on nominal path)
|
|
*
|
|
* The shared contract across all diagnostic shapes is `warnings: string[]`.
|
|
* `configured`/`reason` appear only on config-interpreting read verbs;
|
|
* mutation verbs add `errors[]` (operation-not-applied) instead.
|
|
*/
|
|
export interface Resolution<T> {
|
|
value: T;
|
|
configured: boolean;
|
|
reason: string;
|
|
warnings: string[];
|
|
}
|
|
|
|
// ─── agent-skills value type ──────────────────────────────────────────────────
|
|
|
|
/**
|
|
* The domain value for the agent-skills config-interpreting read verb.
|
|
* Used as the `T` in `Resolution<AgentSkillsValue>`.
|
|
*
|
|
* - `block` — the formatted XML skills block (empty string when no skills)
|
|
* - `skills_count` — number of resolved skill paths (0 when not configured or empty)
|
|
*/
|
|
export interface AgentSkillsValue {
|
|
block: string;
|
|
skills_count: number;
|
|
}
|
|
|
|
// ─── Builder ──────────────────────────────────────────────────────────────────
|
|
|
|
/**
|
|
* Construct a `Resolution<T>` envelope from a value and its provenance fields.
|
|
*/
|
|
export function makeResolution<T>(
|
|
value: T,
|
|
opts: { configured: boolean; reason: string; warnings: string[] },
|
|
): Resolution<T> {
|
|
return {
|
|
value,
|
|
configured: opts.configured,
|
|
reason: opts.reason,
|
|
warnings: opts.warnings,
|
|
};
|
|
}
|