tasknotes-spec 0.2.0

package/conformance/docs/ADAPTER_CONTRACT.md

@@ -0,0 +1,245 @@
+# Adapter Contract
+
+Conformance fixtures are implementation-agnostic and live in `tasknotes-spec`. Each implementation provides an **adapter** — a callable component that bridges the conformance runner to the implementation under test.
+
+---
+
+## Conceptual interface
+
+An adapter is any callable that satisfies this interface:
+
+```
+execute(operation: string, input: object) → { ok: bool, result?: object, error?: string, error_details?: object }
+```
+
+And a metadata query:
+
+```
+metadata() → {
+  implementation: string,
+  version: string,
+  spec_version: string,
+  validation_modes: string[],
+  profiles: string[],
+  capabilities: string[]
+}
+```
+
+### `execute`
+
+- Accepts `operation` (a string operation name, e.g. `"date.parse_utc"`) and `input` (a plain object of arguments).
+- Returns an **envelope** object:
+  - `ok` (boolean, required): `true` on success, `false` on failure
+  - `result` (object, optional): the operation's output, present when `ok` is `true`
+  - `error` (string, optional): a human-readable error message, present when `ok` is `false`
+  - `error_details` (object, optional): structured error fields (`operation`, `code`, `message`, optional `field/path`) when available
+- Must never throw or panic for invalid inputs; all errors must be returned in the envelope.
+
+### `metadata` / `meta.claim`
+
+The runner calls the `meta.claim` operation (with `input = {}`) to obtain adapter metadata. The result object must contain:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `implementation` | string | Name of the implementation under test |
+| `version` | string | Version of the implementation |
+| `spec_version` | string | `tasknotes-spec` version targeted by the adapter |
+| `validation_modes` | string[] | Supported validation modes; must include `strict` |
+| `profiles` | string[] | Conformance profiles claimed (e.g. `["core-lite", "recurrence"]`) |
+| `capabilities` | string[] | Optional capability tokens claimed (e.g. `["dependencies", "links"]`) |
+
+Profile-token consistency requirements:
+
+- If `profiles` includes `extended`, `capabilities` must include `dependencies`, `reminders`, `links`, and `time-tracking`.
+- If `profiles` includes `templating`, `capabilities` must include `templating`.
+- If `profiles` includes `materialized-occurrences`, `profiles` must also include `recurrence` and `capabilities` must include `materialized-occurrences`.
+
+---
+
+## Language bindings
+
+### JavaScript binding
+
+For JavaScript implementations, an adapter is an **ESM module** that the runner imports directly. It must export:
+
+- `metadata` — an object (not a function) with the fields above
+- `execute(operation, input)` — an async function returning an envelope
+
+The runner locates the adapter module via the `TASKNOTES_ADAPTER` environment variable (an absolute or relative path to the `.mjs` file).
+
+**Minimal example**:
+
+```js
+// my-adapter.mjs
+export const metadata = {
+  implementation: "my-tasknotes",
+  version: "1.2.3",
+  spec_version: "0.2.0-draft",
+  validation_modes: ["strict"],
+  profiles: ["core-lite"],
+  capabilities: [],
+};
+
+export async function execute(operation, input) {
+  try {
+    const result = await myImplementation.run(operation, input);
+    return { ok: true, result };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+```
+
+Run with:
+
+```bash
+TASKNOTES_ADAPTER=./my-adapter.mjs npm run conformance:test
+```
+
+### Other language bindings
+
+Any language may implement its own runner that calls the implementation directly, without the JS adapter module mechanism. The fixtures and this documentation are the normative source; the JS runner is the reference implementation.
+
+A non-JS runner should:
+
+1. Load the fixture JSON files from `fixtures/` (see `manifest.json` for the file list)
+2. For each fixture, call the implementation's equivalent of `execute(operation, input)`
+3. Apply the assertions as specified in `FIXTURE_FORMAT.md`
+4. Skip fixtures whose `profile` is not satisfied by claimed profiles (including cumulative expansion rules from §7.3)
+5. Skip fixtures whose `requires[]` capabilities are not claimed by the implementation
+6. Report results (TAP output recommended; see `RUNNER_GUIDE.md`)
+
+See `RUNNER_GUIDE.md` for a complete step-by-step guide to implementing a runner in any language.
+
+---
+
+## Supported operations
+
+All operation names that appear in the fixture files are listed here. Operations marked "(requires capability)" are only exercised when the adapter claims that capability via `meta.claim`.
+
+### Core operations (no capability required)
+
+- `date.parse_utc`
+- `date.parse_local`
+- `date.validate`
+- `date.get_part`
+- `date.has_time`
+- `date.is_same`
+- `date.is_before`
+- `date.resolve_operation_target`
+- `date.day_in_timezone`
+- `field.default_mapping`
+- `field.build_mapping`
+- `field.normalize`
+- `field.denormalize`
+- `field.resolve_display_title`
+- `field.is_completed_status`
+- `field.default_completed_status`
+- `recurrence.complete`
+- `recurrence.recalculate`
+- `recurrence.uncomplete_instance`
+- `recurrence.skip_instance`
+- `recurrence.unskip_instance`
+- `recurrence.effective_state`
+- `occurrence.materialize`
+- `occurrence.complete`
+- `occurrence.skip`
+- `occurrence.uncomplete`
+- `occurrence.unskip`
+- `occurrence.unmaterialize`
+- `create_compat.create`
+- `meta.claim`
+- `meta.has_capability`
+- `meta.has_profile`
+- `config.resolve_collection_path`
+- `config.merge_top_level`
+- `config.spec_version_effective`
+- `config.map_tasknotes_plugin`
+- `config.detect_task_file`
+- `config.provider_behavior`
+- `config.validate_schema`
+- `validation.core_evaluate`
+- `validation.time_entries`
+- `op.mutate_with_validation`
+- `op.atomic_write`
+- `op.idempotency_check`
+- `op.update_patch`
+- `op.complete_nonrecurring`
+- `op.uncomplete_nonrecurring`
+- `op.error_shape`
+- `delete.remove`
+
+### Capability-gated operations
+
+| Operation | Required capability |
+|-----------|-------------------|
+| `dependency.validate_entry` | `dependencies` |
+| `dependency.validate_set` | `dependencies` |
+| `dependency.add` | `dependencies` |
+| `dependency.remove` | `dependencies` |
+| `dependency.replace` | `dependencies` |
+| `dependency.missing_target_behavior` | `dependencies` |
+| `reminder.validate_entry` | `reminders` |
+| `reminder.validate_set` | `reminders` |
+| `reminder.add` | `reminders` |
+| `reminder.update` | `reminders` |
+| `reminder.remove` | `reminders` |
+| `link.parse` | `links` |
+| `link.resolve` | `links` |
+| `link.update_references_on_rename` | `links` + `rename` |
+| `occurrence.materialize` | `materialized-occurrences` |
+| `occurrence.complete` | `materialized-occurrences` |
+| `occurrence.skip` | `materialized-occurrences` |
+| `occurrence.uncomplete` | `materialized-occurrences` |
+| `occurrence.unskip` | `materialized-occurrences` |
+| `occurrence.unmaterialize` | `materialized-occurrences` |
+| `templating.expand_variables` | `templating` |
+| `templating.merge_frontmatter` | `templating` |
+| `templating.handle_failure` | `templating` |
+| `templating.parse_sections` | `templating` |
+| `templating.tokenize` | `templating` |
+| `templating.create_pipeline` | `templating` |
+| `templating.config_defaults` | `templating` |
+| `templating.profile_claim_requirements` | `templating` |
+| `migration.normalize_aliases` | `migration` |
+| `migration.compat_mode` | `migration` |
+| `migration.plan` | `migration` |
+| `migration.normalize_temporal` | `migration` |
+| `migration.resolve_instance_overlap` | `migration` |
+| `migration.normalize_dependencies` | `migration` + `dependencies` |
+| `migration.normalize_reminders` | `migration` + `reminders` |
+| `migration.normalize_links` | `migration` + `links` |
+| `migration.report_summary` | `migration` |
+| `migration.divergence_register` | `migration` |
+| `migration.deprecation_policy` | `migration` |
+| `migration.safety_guards` | `migration` |
+| `migration.compat_statement` | `migration` |
+| `archive.apply` | `archive` |
+| `rename.apply` | `rename` |
+| `rename.title_storage_interaction` | `rename` |
+| `batch.apply` | `batch` |
+| `op.detect_conflict` | `concurrency` |
+| `op.dry_run` | `dry-run` |
+| `time.start` | `time-tracking` |
+| `time.stop` | `time-tracking` |
+| `time.replace_entries` | `time-tracking` |
+| `time.remove_entry` | `time-tracking` |
+| `time.auto_stop_on_complete` | `time-tracking` |
+| `time.report_totals` | `time-tracking` |
+
+---
+
+## Fixture shape
+
+Fixture files are JSON arrays. Each element is a fixture object with fields defined in `FIXTURE_FORMAT.md`.
+
+Summary of fields:
+
+- `id` (string, unique)
+- `section` (string, spec reference)
+- `profile` (string)
+- `operation` (string)
+- `assertion` (string)
+- `requires` (string[], optional)
+- `input` (object)
+- `expect` (object, conditional)

package/conformance/docs/FIXTURE_FORMAT.md

@@ -0,0 +1,247 @@
+# Fixture Format
+
+Each fixture is a JSON object:
+
+```json
+{
+  "id": "date.parse_utc.valid.0001",
+  "section": "§3",
+  "profile": "core-lite",
+  "operation": "date.parse_utc",
+  "assertion": "envelope_equals",
+  "requires": [],
+  "input": { "value": "2026-02-20" },
+  "expect": {
+    "ok": true,
+    "result": { "date": "2026-02-20" }
+  }
+}
+```
+
+## Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | yes | Unique fixture identifier, e.g. `date.parse_utc.valid.0001` |
+| `section` | string | yes | Spec section this fixture exercises, e.g. `§3` |
+| `profile` | string | yes | Conformance profile: `core-lite`, `recurrence`, `extended`, `templating`, or `materialized-occurrences`; runner skips when adapter claim does not satisfy profile (including cumulative expansion rules) |
+| `operation` | string | yes | Operation name passed to the adapter, e.g. `date.parse_utc` |
+| `assertion` | string | yes | Assertion kind; see below |
+| `requires` | string[] | no | Capability tokens required; after profile check, runner skips if the adapter does not claim all listed capabilities |
+| `input` | object | yes | Arguments passed to the operation |
+| `expect` | object | conditional | Expected outcome; required for `envelope_equals` and `envelope_error` |
+
+---
+
+## Assertion kinds
+
+### `envelope_equals`
+
+Recursively deep-matches the adapter's response envelope against `expect` using the matcher directives described below. Every key in `expect` must be present and matching in the actual envelope; extra keys in the actual envelope are allowed.
+
+**Inputs**: `input` (passed to operation), `expect` (partial envelope to match)
+
+**Passes when**: `deepMatch(actualEnvelope, expect)` succeeds without error.
+
+**Example**:
+```json
+{
+  "assertion": "envelope_equals",
+  "input": { "value": "2026-02-20" },
+  "expect": { "ok": true, "result": { "date": "2026-02-20" } }
+}
+```
+
+---
+
+### `envelope_error`
+
+Asserts that the operation returns a failure envelope, and optionally matches the error message.
+
+**Passes when**:
+1. `envelope.ok === false`
+2. If `expect.error` is present: `deepMatch(envelope.error, expect.error)` succeeds
+
+**Example**:
+```json
+{
+  "assertion": "envelope_error",
+  "input": { "value": "not-a-date" },
+  "expect": { "error": { "$regex": "invalid" } }
+}
+```
+
+If `expect` is absent or `expect.error` is absent, only `ok === false` is checked.
+
+---
+
+### `recurrence_complete_invariants`
+
+Asserts structural and semantic invariants on the result of a `recurrence.complete` operation. Does **not** use `expect`; instead applies fixed logical checks derived from `input`.
+
+**Passes when ALL of the following hold**:
+
+1. `envelope.ok === true`
+2. `result.completeInstances` is an array
+3. `result.skippedInstances` is an array
+4. `result.completeInstances` **includes** `input.completionDate`
+5. `result.skippedInstances` does **not** include `input.completionDate`
+6. `result.updatedRecurrence` matches `/FREQ=/`
+7. `result.updatedRecurrence` matches `/DTSTART:/`
+8. **Anchor-conditional DTSTART day** (if `input.recurrenceAnchor === "completion"`):
+   - Extract `dtstartDay` = `input.completionDate` with hyphens removed (e.g. `"2026-03-01"` → `"20260301"`)
+   - `result.updatedRecurrence` matches `/DTSTART:20260301(?:;|$)/`
+9. **Scheduled anchor** (if `input.recurrenceAnchor === "scheduled"` and `input.scheduled` is a string):
+   - Extract `dtstartDay` = first 10 chars of `input.scheduled` with hyphens removed
+   - `result.updatedRecurrence` matches `/DTSTART:{dtstartDay}(?:;|$)/`
+10. If `result.nextScheduled` is present:
+    - It matches `/^\d{4}-\d{2}-\d{2}/`
+    - `result.nextScheduled.slice(0, 10) >= input.completionDate` (string comparison)
+11. If `result.nextScheduled`, `result.nextDue`, `input.scheduled`, and `input.due` are all present strings:
+    - `originalOffset` = `(Date(input.due[0:10]) - Date(input.scheduled[0:10]))` in whole days
+    - `(Date(result.nextDue[0:10]) - Date(result.nextScheduled[0:10]))` in whole days === `originalOffset`
+
+---
+
+### `recurrence_recalculate_invariants`
+
+Asserts structural and semantic invariants on the result of a `recurrence.recalculate` operation. Does **not** use `expect`.
+
+**Passes when ALL of the following hold**:
+
+1. `envelope.ok === true`
+2. `result.updatedRecurrence` matches `/FREQ=/`
+3. If `input.recurrenceAnchor === "scheduled"`:
+   - `result.updatedRecurrence` matches `/DTSTART:/`
+4. If `result.nextScheduled` is present:
+   - `result.nextScheduled.slice(0, 10) >= input.referenceDate` (string comparison)
+   - Let `complete = input.completeInstances ?? []` and `skipped = input.skippedInstances ?? []`
+   - If `input.recurrenceAnchor !== "completion"`: `complete` does **not** include `result.nextScheduled.slice(0, 10)`
+   - `skipped` does **not** include `result.nextScheduled.slice(0, 10)`
+5. If `result.nextScheduled`, `result.nextDue`, `input.scheduled`, and `input.due` are all present strings:
+   - `originalOffset` = `(Date(input.due[0:10]) - Date(input.scheduled[0:10]))` in whole days
+   - `(Date(result.nextDue[0:10]) - Date(result.nextScheduled[0:10]))` in whole days === `originalOffset`
+
+---
+
+### `create_compat_invariants`
+
+Asserts the result of a `create_compat.create` operation. Combines `envelope_equals` matching with additional path invariants.
+
+**Passes when ALL of the following hold**:
+
+1. `deepMatch(actualEnvelope, expect)` succeeds (same as `envelope_equals`)
+2. If `envelope.ok === true` and `envelope.result.path` is present:
+   - `envelope.result.path` ends with `.md`
+   - `envelope.result.path` does **not** contain `{`
+   - `envelope.result.path` does **not** contain `}`
+
+The path checks ensure template variables were fully expanded and no literal brace characters remain.
+
+---
+
+## Matcher directives in `expect`
+
+Matcher directives are special single-key objects that appear within `expect` values. When the deep-matcher encounters an object with exactly one of these keys, it applies the corresponding matching logic instead of a structural equality check.
+
+Directives may appear at any level of nesting. The matching context (the full `input` object) is threaded through all recursive calls to support `$ref`.
+
+### `$regex`
+
+```json
+{ "$regex": "^\\d{4}-\\d{2}-\\d{2}$" }
+```
+
+Asserts the actual value is a **string** matching the given regular expression. The pattern is interpreted as a standard ECMAScript regex (compatible with most language regex engines).
+
+**Algorithm**:
+```
+if actual is not a string → fail
+compile $regex as a regex pattern
+if actual does not match pattern → fail
+```
+
+---
+
+### `$contains`
+
+```json
+{ "$contains": ["item1", "item2"] }
+```
+
+or for objects:
+
+```json
+{ "$contains": { "key": "value" } }
+```
+
+**For arrays**: asserts the actual array contains at least one element matching each item in the `$contains` array (order-independent). Each element is matched with full `deepMatch`.
+
+**For objects**: asserts the actual object contains all key-value pairs in the `$contains` object. Values are matched with full `deepMatch`.
+
+**Algorithm (array)**:
+```
+if actual is not an array → fail
+for each expectedItem in $contains:
+  if no element in actual deepMatches expectedItem → fail
+```
+
+**Algorithm (object)**:
+```
+if actual is not an object → fail
+for each (key, value) in $contains:
+  deepMatch(actual[key], value)
+```
+
+---
+
+### `$oneOf`
+
+```json
+{ "$oneOf": ["OPEN", "IN_PROGRESS", null] }
+```
+
+Asserts the actual value matches **at least one** of the listed alternatives. Each alternative is matched with full `deepMatch` (so alternatives may themselves contain directives).
+
+**Algorithm**:
+```
+for each option in $oneOf:
+  try deepMatch(actual, option)
+  if it succeeds → pass
+fail (no option matched)
+```
+
+---
+
+### `$ref`
+
+```json
+{ "$ref": "input.completionDate" }
+```
+
+Resolves a dotted path into the fixture's `input` object and uses the resolved value as the expected value. The path must start with `"input."`.
+
+**Algorithm**:
+```
+if ref does not start with "input." → treat as literal value (no resolution)
+segments = ref["input.".length:].split(".")
+current = context.input
+for each segment in segments:
+  if current is null or not an object → resolved = undefined; break
+  current = current[segment]
+resolved = current
+deepMatch(actual, resolved)
+```
+
+**Example**: if `input = { "completionDate": "2026-03-01" }` and the expect field is `{ "$ref": "input.completionDate" }`, the matcher checks `actual === "2026-03-01"`.
+
+---
+
+## Reference implementation
+
+The canonical implementation of all matchers and assertion kinds is:
+
+- **Matchers**: `conformance/lib/matchers.mjs` — `applyAssertion(caseDef, envelope)` and internal `deepMatch`
+- **Runner**: `conformance/tests/runner.test.mjs` — loads fixtures, calls adapter, applies assertions
+
+When this documentation and the reference implementation disagree, file an issue; the intent is for them to be identical.