feat(sdk): add field extraction utilities for _fields and _mvi (§9.1, §9.2)

Implements SDK runtime utilities that were missing per GitHub Issue #1:
resolveFieldExtraction(), extractFieldFromResult/Envelope(), applyFieldFilter(),
isMVILevel() type guard, MVI_LEVELS constant, and E_FIELD_CONFLICT error code.
Enhances LAFSFlagError to implement LAFSError interface. Amends spec §9.1/§9.2
with MVI level behavioral definitions and wrapper-pattern field selection.

Closes #1

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: kryptobaseddev

CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-02-26
+
+### Added
+
+- **Field extraction utilities** (`src/fieldExtraction.ts`): runtime SDK support for spec-defined `_fields` (§9.2) and `_mvi` (§9.1) features:
+  - `resolveFieldExtraction()` — resolves `--field`, `--fields`, and `--mvi` CLI flags with conflict detection
+  - `extractFieldFromResult()` / `extractFieldFromEnvelope()` — single-field extraction across four result shapes (flat, wrapper-entity, wrapper-array, direct array)
+  - `applyFieldFilter()` — multi-field projection that preserves envelope structure and sets `_meta.mvi = 'custom'` per §9.1
+  - `FieldExtractionInput`, `FieldExtractionResolution` — supporting types
+- **`MVI_LEVELS` constant** (`src/types.ts`): `ReadonlySet<MVILevel>` for CLI completion generators, validation schemas, and docs tools
+- **`isMVILevel()` type guard** (`src/types.ts`): runtime type narrowing for `MVILevel` values
+- **`E_FIELD_CONFLICT` error code** (`schemas/v1/error-registry.json`): for mutually exclusive `--field` + `--fields` flag combinations (category: `CONTRACT`, HTTP 400, gRPC `INVALID_ARGUMENT`, CLI exit 2)
+- **Test fixtures**: `fixtures/field-extraction-success.json` (flat result) and `fixtures/field-extraction-array.json` (direct array result)
+- **44 new tests** in `tests/fieldExtraction.test.ts` covering all functions, edge cases, and integration flow
+- **Migration note** (`migrations/1.4.1-to-1.5.0.md`): documents `_meta` always-present clarification and new exports
+
+### Changed
+
+- **`LAFSFlagError`** (`src/flagSemantics.ts`): now implements `LAFSError` interface with `category`, `retryable`, `retryAfterMs`, and `details` properties resolved from the error registry. Constructor accepts optional third `details` parameter (backwards compatible)
+- **Conformance MVI check** (`src/conformance.ts`): replaced hardcoded `validMviLevels` array with `isMVILevel()` type guard (check name `meta_mvi_present` unchanged)
+
+### Specification
+
+- **§9.1 MVI default** (`lafs.md`): added behavioral definitions for each MVI level (`minimal`, `standard`, `full`, `custom`), clarified that `_meta` is a structural envelope field that MUST always be present regardless of MVI level, and that `custom` is server-set only (not client-requestable)
+- **§9.2 Field selection** (`lafs.md`): expanded to document wrapper-entity and wrapper-array result shapes, path notation exclusion, array-element projection, and automatic `_meta.mvi = 'custom'` when `_fields` is present
+
+### Statistics
+
+- 337 total tests passing (44 new)
+- 13 error codes in registry (1 new)
+
 ## [1.4.1] - 2026-02-25
 
 ### Added
@@ -451,8 +482,18 @@ This is a major release (1.0.0) marking production readiness. All previously dep
 
 ---
 
-[Unreleased]: https://github.com/lafs-protocol/lafs-protocol/compare/v1.0.0...HEAD
-[1.0.0]: https://github.com/lafs-protocol/lafs-protocol/releases/tag/v1.0.0
+[Unreleased]: https://github.com/kryptobaseddev/lafs-protocol/compare/v1.5.0...HEAD
+[1.5.0]: https://github.com/kryptobaseddev/lafs-protocol/compare/v1.4.1...v1.5.0
+[1.4.1]: https://github.com/kryptobaseddev/lafs-protocol/compare/v1.4.0...v1.4.1
+[1.4.0]: https://github.com/kryptobaseddev/lafs-protocol/compare/v1.3.2...v1.4.0
+[1.3.2]: https://github.com/kryptobaseddev/lafs-protocol/compare/v1.3.1...v1.3.2
+[1.3.1]: https://github.com/kryptobaseddev/lafs-protocol/compare/v1.3.0...v1.3.1
+[1.3.0]: https://github.com/kryptobaseddev/lafs-protocol/compare/v1.2.3...v1.3.0
+[1.2.3]: https://github.com/kryptobaseddev/lafs-protocol/compare/v1.2.2...v1.2.3
+[1.2.2]: https://github.com/kryptobaseddev/lafs-protocol/compare/v1.2.0...v1.2.2
+[1.2.0]: https://github.com/kryptobaseddev/lafs-protocol/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/kryptobaseddev/lafs-protocol/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/kryptobaseddev/lafs-protocol/releases/tag/v1.0.0
 [0.5.0]: https://github.com/lafs-protocol/lafs-protocol/releases/tag/v0.5.0
 [0.4.0]: https://github.com/lafs-protocol/lafs-protocol/releases/tag/v0.4.0
 [0.3.0]: https://github.com/lafs-protocol/lafs-protocol/releases/tag/v0.3.0

README.md

@@ -4,7 +4,7 @@
 
 LAFS defines a standard envelope format for structured responses from LLM-powered agents and tools. It complements transport protocols like [MCP](https://modelcontextprotocol.io/) and [A2A](https://github.com/google/A2A) by standardizing what comes back — not how it gets there.
 
-**Current version:** 1.4.1 | [📚 Documentation](https://codluv.gitbook.io/lafs-protocol/) | [Spec](lafs.md) | [Migration Guides](migrations/)
+**Current version:** 1.5.0 | [📚 Documentation](https://codluv.gitbook.io/lafs-protocol/) | [Spec](lafs.md) | [Migration Guides](migrations/)
 
 [![GitBook](https://img.shields.io/badge/docs-gitbook-blue)](https://codluv.gitbook.io/lafs-protocol/)
 [![npm](https://img.shields.io/npm/v/@cleocode/lafs-protocol)](https://www.npmjs.com/package/@cleocode/lafs-protocol)

docs/specification.md

@@ -1,7 +1,7 @@
 # LAFS: LLM-Agent-First Specification
 
 > 📚 **Documentation:** https://codluv.gitbook.io/lafs-protocol/  
-> **Version:** 1.4.1 | **Status:** Production Ready
+> **Version:** 1.5.0 | **Status:** Production Ready
 
 ## 1. Scope
 

fixtures/field-extraction-array.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://lafs.dev/schemas/v1/envelope.schema.json",
+  "_meta": {
+    "specVersion": "1.0.0",
+    "schemaVersion": "1.0.0",
+    "timestamp": "2026-02-26T00:00:00Z",
+    "operation": "tasks.list",
+    "requestId": "req_field_02",
+    "transport": "sdk",
+    "strict": true,
+    "mvi": "standard",
+    "contextVersion": 0
+  },
+  "success": true,
+  "result": [
+    { "id": "T001", "title": "Task One", "status": "active" },
+    { "id": "T002", "title": "Task Two", "status": "pending" }
+  ]
+}

fixtures/field-extraction-success.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://lafs.dev/schemas/v1/envelope.schema.json",
+  "_meta": {
+    "specVersion": "1.0.0",
+    "schemaVersion": "1.0.0",
+    "timestamp": "2026-02-26T00:00:00Z",
+    "operation": "tasks.show",
+    "requestId": "req_field_01",
+    "transport": "sdk",
+    "strict": true,
+    "mvi": "standard",
+    "contextVersion": 0
+  },
+  "success": true,
+  "result": {
+    "id": "T001",
+    "title": "Example Task",
+    "status": "active",
+    "description": "A verbose description",
+    "tags": ["a", "b"]
+  }
+}

lafs.md

@@ -1,7 +1,7 @@
 # LAFS: LLM-Agent-First Specification
 
 > 📚 **Documentation:** https://codluv.gitbook.io/lafs-protocol/  
-> **Version:** 1.4.1 | **Status:** Production Ready
+> **Version:** 1.5.0 | **Status:** Production Ready
 
 ## 1. Scope
 
@@ -431,16 +431,45 @@ To reduce token and I/O overhead, implementations SHOULD support lazy retrieval
 - Default list/batch outputs MUST only contain fields required for next action.
 - Verbose fields SHOULD be omitted by default.
 - Systems SHOULD publish operation-level MVI budgets.
+- `_meta.mvi` MUST be one of: `minimal`, `standard`, `full`, or `custom`.
+- `_meta` is a structural envelope field and MUST always be present regardless
+  of `mvi` level. MVI levels govern the contents of `result` only; they MUST NOT
+  affect envelope structural fields (`$schema`, `_meta`, `success`, `error`,
+  `page`, `_extensions`).
+- `minimal`: MUST include only fields within `result` sufficient for the next
+  agent action (typically identifiers and status). Implementations SHOULD
+  document which fields constitute `minimal` per operation.
+- `standard` (default): MUST include all commonly useful fields for the
+  operation.
+- `full`: MUST include all available fields including verbose and
+  rarely-accessed data.
+- `custom`: MUST be set by the server when `_fields` projection has been
+  applied, indicating the result does not conform to any predefined disclosure
+  level. `custom` is not a client-requestable level.
 
 ### 9.2 Field selection (`_fields`)
 
-Clients MAY request a subset of response fields via the `_fields` request parameter.
-
-- `_fields` MUST be an array of strings identifying top-level result field names.
-- When `_fields` is present, the server MUST return only the requested fields plus any MVI-required fields for the declared disclosure level.
-- When `_fields` is absent, the server MUST return fields appropriate for the declared `_meta.mvi` disclosure level.
-- If a requested field does not exist on the resource, the server SHOULD omit it silently (no error). Servers MAY include a warning in `_meta.warnings` for unknown fields.
-- `_fields` MUST NOT affect envelope structural fields (`$schema`, `_meta`, `success`, `error`, `page`, `_extensions`); it applies only to the contents of `result`.
+Clients MAY request a subset of response fields via the `_fields` request
+parameter.
+
+- `_fields` MUST be an array of strings identifying `result` field names.
+  Path notation (e.g., `task.title`) is not defined by this specification.
+- When `result` is an array, `_fields` applies to the keys of each element.
+- When `result` is a wrapper object whose values are entities or arrays of
+  entities (e.g., `{ "task": { ... } }` or `{ "items": [...] }`), servers
+  SHOULD apply `_fields` to the nested entity fields rather than the wrapper's
+  own keys.
+- When `_fields` is present, the server MUST return only the requested fields
+  plus any MVI-required fields for the declared disclosure level.
+  The server MUST set `_meta.mvi` to `custom` in the response.
+- When `_fields` is absent, the server MUST return fields appropriate for the
+  declared `_meta.mvi` disclosure level.
+- If a requested field does not exist on the resource, the server SHOULD omit
+  it silently (no error). Servers MAY include a warning in `_meta.warnings`
+  for unknown fields.
+- `_fields` MUST NOT affect envelope structural fields (`$schema`, `_meta`,
+  `success`, `error`, `page`, `_extensions`); it applies only to the contents
+  of `result`.
 
 ### 9.3 Expansion mechanism (`_expand`)
 

migrations/1.4.1-to-1.5.0.md

@@ -0,0 +1,30 @@
+# Migration: 1.4.1 → 1.5.0
+
+## `_meta` is always required (§9.1 clarification)
+
+The §9.1 amendment clarifies that `_meta` is a structural envelope field and
+MUST be present regardless of `mvi` level. Existing implementations that strip
+`_meta` for `mvi: 'minimal'` must be updated to always include `_meta`. MVI
+levels govern `result` contents only.
+
+## New exports
+
+- `MVI_LEVELS` — `ReadonlySet<MVILevel>` of all valid MVI levels
+- `isMVILevel()` — type guard for `MVILevel`
+- `resolveFieldExtraction()` — resolves `--field`, `--fields`, and `--mvi` flags
+- `extractFieldFromResult()` / `extractFieldFromEnvelope()` — single-field extraction
+- `applyFieldFilter()` — multi-field projection with `_meta.mvi = 'custom'`
+- `FieldExtractionInput`, `FieldExtractionResolution` — supporting types
+
+## Enhanced `LAFSFlagError`
+
+`LAFSFlagError` now implements `LAFSError`, adding `category`, `retryable`,
+`retryAfterMs`, and `details` properties resolved from the error registry.
+The constructor accepts an optional third `details` parameter. This is a
+backwards-compatible addition.
+
+## New error code: `E_FIELD_CONFLICT`
+
+Added to the error registry for mutually exclusive field selection modes
+(`--field` + `--fields`). Category: `CONTRACT`, HTTP 400, gRPC
+`INVALID_ARGUMENT`, CLI exit 2.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/lafs-protocol",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "private": false,
   "type": "module",
   "description": "LLM-Agent-First Specification schemas and conformance tooling",

schemas/v1/error-registry.json

@@ -109,6 +109,15 @@
       "httpStatus": 413,
       "grpcStatus": "RESOURCE_EXHAUSTED",
       "cliExit": 2
+    },
+    {
+      "code": "E_FIELD_CONFLICT",
+      "category": "CONTRACT",
+      "description": "Mutually exclusive field selection modes (single-field extraction and multi-field filtering cannot be combined)",
+      "retryable": false,
+      "httpStatus": 400,
+      "grpcStatus": "INVALID_ARGUMENT",
+      "cliExit": 2
     }
   ]
 }

src/conformance.ts

@@ -1,5 +1,6 @@
 import { getTransportMapping, isRegisteredErrorCode } from "./errorRegistry.js";
 import { resolveOutputFormat, LAFSFlagError } from "./flagSemantics.js";
+import { isMVILevel } from "./types.js";
 import type { ConformanceReport, FlagInput } from "./types.js";
 import { getChecksForTier, type ConformanceTier } from "./conformanceProfiles.js";
 import { validateEnvelope } from "./validateEnvelope.js";
@@ -161,12 +162,12 @@ export function runEnvelopeConformance(
     }
   }
 
-  const validMviLevels = ["minimal", "standard", "full", "custom"];
+  const mviValid = isMVILevel(typed._meta.mvi);
   pushCheck(
     checks,
     "meta_mvi_present",
-    validMviLevels.includes(typed._meta.mvi),
-    validMviLevels.includes(typed._meta.mvi) ? undefined : `invalid mvi level: ${String(typed._meta.mvi)}`,
+    mviValid,
+    mviValid ? undefined : `invalid mvi level: ${String(typed._meta.mvi)}`,
   );
   pushCheck(checks, "meta_strict_present", typeof typed._meta.strict === "boolean");