feat(integration): add versioned naruon rehearsal handoff

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Added
 
+- Add a versioned, dependency-free BandScope → naruon rehearsal handoff contract with Band norm-group identity, Event and Commitment semantics, calibrated provenance, deterministic JSON serialization, and a public JSON Schema while preserving BandScope's standalone local-first operation. Unknown-field errors retain the structural object path without echoing caller-controlled field names.
 - Display the analyzed song tempo (BPM) as a badge in the rehearsal workspace.
 - 각 합주 역할(Role)별 개인 연습 진행도를 0~100% 범위로 기록 및 시각화할 수 있는 연습 진척도(`practiceProgress`) 트래커 기능 추가. UI 컨트롤(슬라이더 및 +/- 버튼)과 한/영 다국어 지원 포함.
 

docs/doctoring/naruon-rehearsal-handoff.md

@@ -0,0 +1,74 @@
+# BandScope → naruon rehearsal handoff standards evidence
+
+## Status
+
+**Active Draft PR evidence.** This record documents the standards basis for the versioned BandScope → naruon rehearsal handoff introduced on PR #737. It is not protected-`develop` shipped truth until the implementation is merged and revalidated on the protected branch.
+
+## Scope and architectural decision
+
+BandScope remains independently useful and local-first. The integration boundary is a dependency-free, versioned JSON artifact rather than a mandatory naruon network dependency. The TypeScript parser is the authoritative application trust boundary; the public JSON Schema is a portable structural companion, not a substitute for application-level semantic validation.
+
+This split is intentional. JSON Schema Draft 2020-12 separates structural validation from semantic `format` handling, and its standard meta-schema does not require `format` to be asserted by default. Therefore, consumers cannot safely assume that a generic schema validator will fully validate date-time semantics merely because a property declares `"format": "date-time"` (Wright et al., 2022). BandScope consequently performs calendrical, IANA-zone, cross-field, size, snapshot, and offset-consistency checks in the TypeScript parser.
+
+## Timestamp profile and time-zone semantics
+
+The handoff uses a deliberately bounded RFC 3339-derived timestamp profile:
+
+- four-digit years, two-digit month/day/time fields, an explicit `T`, and an explicit `Z` or numeric UTC offset;
+- calendar-valid dates and bounded fractional seconds;
+- uppercase `T`/`Z` canonical spelling;
+- no leap-second `:60` values at this application boundary; and
+- an explicit IANA time-zone identifier stored separately in `event.timeZone`.
+
+RFC 3339 permits leap-second `:60` under its leap-second rules and notes that lowercase `t`/`z` can be accepted by the ABNF, while also allowing specifications in case-sensitive contexts to require uppercase spellings (Klyne & Newman, 2002). BandScope intentionally chooses a narrower scheduling profile: rehearsal events do not need leap-second representation, and canonical uppercase serialization avoids cross-runtime ambiguity. Documentation must therefore describe this as BandScope's RFC 3339 profile rather than implying acceptance of every RFC 3339 lexical form.
+
+RFC 9557 updates RFC 3339's interpretation of `Z`: `Z` expresses that the UTC instant is known while the preferred local offset is not asserted; `-00:00` has the same semantic meaning but is less interoperable and `Z` is preferred. By contrast, a numeric offset is an assertion that can be inconsistent with named time-zone information (Sharma & Bormann, 2024). The handoff reflects that distinction:
+
+- `Z` and `-00:00` do not assert local clock fields against `event.timeZone`;
+- numeric `+/-HH:MM` offsets are checked against the required IANA zone at that instant; and
+- an inconsistency is rejected rather than silently choosing one source of temporal truth.
+
+Although RFC 9557 serializes named time zones as IXDTF suffixes, BandScope carries the IANA identifier in a separate required JSON field. The semantic rule is deliberately equivalent to treating the named zone as critical application information: a consumer must not project an event whose asserted numeric offset conflicts with the required zone.
+
+## JSON and schema boundary
+
+RFC 8259 defines JSON's interoperable data model and requires object member names to be strings; it does not provide application authorization, provenance, or semantic identity guarantees (Bray, 2017). The handoff therefore adds fail-closed application constraints beyond JSON syntax:
+
+- `additionalProperties: false` at every public object level;
+- bounded strings, arrays, and serialized UTF-8 size;
+- opaque nonnumeric identifiers;
+- exact artifact kind/version discriminators;
+- canonical key order for deterministic serialization;
+- band identity consistency between `source.bandId` and `normGroup.id`;
+- finite calibrated confidence in `[0, 1]`;
+- dense bounded evidence receipts; and
+- payload-safe diagnostics that report schema-owned locations without echoing attacker-controlled unknown property names.
+
+JSON Schema Draft 2020-12 expects Unicode-aware regular-expression behavior, but validator implementations can still differ in feature support. The checked-in schema therefore documents that consumers must use Unicode semantics for `\p{Nd}` and must invoke the TypeScript parser for semantic checks that are not portable schema assertions.
+
+## Security, privacy, and evidence implications
+
+The artifact carries authorized rehearsal coordination facts and provenance; it is not itself an authorization token. It grants no filesystem, database, calendar, mail, model, or network capability. Connector authentication, tenant binding, consent, signature/authenticated-envelope verification, persistence, and externally visible writeback remain outside the shared-types package.
+
+For audit readiness, a receiving connector should preserve the validated artifact plus transport/signature evidence, maintain tenant/band segregation, and record the mapping from `sourceRecordId`/field evidence to any projected Event or Commitment. Validation errors must remain payload-safe so logs do not become a secondary disclosure channel for person, tenant, credential, or other caller-controlled property names.
+
+## Verification contract
+
+Commercial verification for this boundary requires all of the following:
+
+1. runtime parser and public schema reject unknown fields and malformed structure;
+2. runtime parser enforces the semantic rules the schema cannot portably guarantee, including IANA-zone availability, numeric-offset consistency, cross-field identity, canonical snapshotting, and serialized-size limits;
+3. deterministic serialization is invariant to caller key insertion order;
+4. valid `Z`/`-00:00` unknown-local-offset forms remain accepted with an explicit IANA zone, while inconsistent numeric offsets fail closed;
+5. the deliberately narrower timestamp profile rejects leap-second `:60` and noncanonical lowercase timestamp separators as application policy rather than misclassifying those forms as universally invalid RFC 3339; and
+6. repository exact-head type, lint, test, coverage, SAST, security, SBOM, supply-chain, and independent-review gates remain mandatory.
+
+## References
+
+Bray, T. (2017). *The JavaScript Object Notation (JSON) data interchange format* (RFC 8259). Internet Engineering Task Force. https://doi.org/10.17487/RFC8259
+
+Klyne, G., & Newman, C. (2002). *Date and time on the Internet: Timestamps* (RFC 3339). Internet Engineering Task Force. https://doi.org/10.17487/RFC3339
+
+Sharma, U., & Bormann, C. (2024). *Date and time on the Internet: Timestamps with additional information* (RFC 9557). Internet Engineering Task Force. https://doi.org/10.17487/RFC9557
+
+Wright, A., Andrews, H., Hutton, B., & Dennis, G. (2022). *JSON Schema Draft 2020-12*. JSON Schema. https://json-schema.org/draft/2020-12

docs/integrations/naruon-rehearsal-handoff-v1.schema.json

@@ -0,0 +1,157 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contextualwisdomlab.github.io/bandscope/schemas/naruon-rehearsal-handoff-v1.schema.json",
+  "title": "BandScope naruon rehearsal handoff v1",
+  "description": "A network-agnostic BandScope export that contributes a Band norm-group, rehearsal Event, commitment status, RSVP direction, and provenance to naruon.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "artifactKind",
+    "artifactVersion",
+    "createdAt",
+    "source",
+    "normGroup",
+    "event",
+    "commitment",
+    "provenance"
+  ],
+  "properties": {
+    "artifactKind": {
+      "const": "bandscope.naruon.rehearsal-event"
+    },
+    "artifactVersion": {
+      "const": 1
+    },
+    "createdAt": {
+      "$ref": "#/$defs/timestamp"
+    },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["application", "workspaceId", "bandId", "rehearsalId"],
+      "properties": {
+        "application": {
+          "const": "bandscope"
+        },
+        "workspaceId": {
+          "$ref": "#/$defs/opaqueIdentifier"
+        },
+        "bandId": {
+          "$ref": "#/$defs/opaqueIdentifier"
+        },
+        "rehearsalId": {
+          "$ref": "#/$defs/opaqueIdentifier"
+        }
+      }
+    },
+    "normGroup": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "id", "label"],
+      "properties": {
+        "kind": {
+          "const": "band"
+        },
+        "id": {
+          "$ref": "#/$defs/opaqueIdentifier"
+        },
+        "label": {
+          "$ref": "#/$defs/displayText"
+        }
+      }
+    },
+    "event": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["title", "startsAt", "endsAt", "timeZone"],
+      "properties": {
+        "title": {
+          "$ref": "#/$defs/displayText"
+        },
+        "startsAt": {
+          "$ref": "#/$defs/timestamp"
+        },
+        "endsAt": {
+          "$ref": "#/$defs/timestamp"
+        },
+        "timeZone": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f]+$"
+        },
+        "venue": {
+          "$ref": "#/$defs/displayText"
+        }
+      }
+    },
+    "commitment": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "rsvpDirection"],
+      "properties": {
+        "status": {
+          "enum": ["confirmed", "tentative", "desired"]
+        },
+        "rsvpDirection": {
+          "enum": ["organizer", "attendee"]
+        }
+      }
+    },
+    "provenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sourceRecordId", "confidence", "evidence"],
+      "properties": {
+        "sourceRecordId": {
+          "$ref": "#/$defs/opaqueIdentifier"
+        },
+        "confidence": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "evidence": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 64,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["field", "value"],
+            "properties": {
+              "field": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 256,
+                "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f]+$"
+              },
+              "value": {
+                "$ref": "#/$defs/displayText"
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "opaqueIdentifier": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256,
+      "pattern": "^(?!\\p{Nd}+$)(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f]+$"
+    },
+    "displayText": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 2048,
+      "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f]+$"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "pattern": "^[0-9]{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])T(?:[01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](?:\\.[0-9]{1,9})?(?:Z|[+-](?:[01][0-9]|2[0-3]):[0-5][0-9])$"
+    }
+  }
+}

docs/integrations/naruon.md

@@ -0,0 +1,115 @@
+# BandScope → naruon rehearsal handoff
+
+BandScope remains a fully standalone, local-first desktop application. The naruon bridge is an **explicit export contract**, not a mandatory network dependency: BandScope can produce a versioned JSON artifact, and a separately authorized naruon connector may ingest that artifact as a Band norm-group, rehearsal Event, and status-bearing Commitment.
+
+## Product outcome
+
+The bridge closes the first BandScope side of the platform vertical described by `ContextualWisdomLab/bandscope#610` without coupling the desktop app to naruon internals.
+
+A naruon deployment can use the artifact to:
+
+- identify the band as an overlapping norm/reference group;
+- place a rehearsal on the shared Event graph;
+- preserve `confirmed`, `tentative`, or `desired` commitment strength;
+- preserve organizer-versus-attendee RSVP direction;
+- run status-weighted conflict detection without silently breaking a confirmed commitment;
+- cite the BandScope source record and field-level evidence;
+- calibrate downstream behavior from an explicit `0..1` confidence value.
+
+BandScope itself continues to analyze songs and manage rehearsal material even when naruon is absent, offline, or intentionally disabled.
+
+## TypeScript API
+
+The dependency-free contract is exported from a stable package subpath:
+
+```ts
+import {
+  createNaruonRehearsalHandoff,
+  serializeNaruonRehearsalHandoff
+} from "@bandscope/shared-types/naruon";
+
+const artifact = createNaruonRehearsalHandoff({
+  createdAt: "2026-08-03T01:23:45Z",
+  source: {
+    application: "bandscope",
+    workspaceId: "workspace-local-alpha",
+    bandId: "band-contextual-wisdom",
+    rehearsalId: "rehearsal-2026-08-10"
+  },
+  normGroup: {
+    kind: "band",
+    id: "band-contextual-wisdom",
+    label: "Contextual Wisdom Band"
+  },
+  event: {
+    title: "August rehearsal",
+    startsAt: "2026-08-10T19:00:00+09:00",
+    endsAt: "2026-08-10T21:30:00+09:00",
+    timeZone: "Asia/Seoul",
+    venue: "Studio A"
+  },
+  commitment: {
+    status: "confirmed",
+    rsvpDirection: "organizer"
+  },
+  provenance: {
+    sourceRecordId: "calendar-record-alpha",
+    confidence: 0.94,
+    evidence: [
+      { field: "startsAt", value: "2026-08-10T19:00:00+09:00" },
+      { field: "venue", value: "Studio A" }
+    ]
+  }
+});
+
+const json = serializeNaruonRehearsalHandoff(artifact);
+```
+
+Consumers receiving untrusted bytes must call `deserializeNaruonRehearsalHandoff` or `parseNaruonRehearsalHandoff` before use. Serialized handoffs are limited to 256 KiB of UTF-8 and are size-checked before JSON parsing. Preserve original transport bytes separately only when a detached-signature verification workflow requires them; application logic should use the validated canonical value.
+
+## Boundary guarantees
+
+The contract fails closed on:
+
+- unknown fields at every object level;
+- numeric-only IDs (BandScope and naruon IDs must remain opaque strings);
+- blank, untrimmed, control-character-bearing, or oversized values;
+- malformed or calendrically invalid timestamps outside BandScope's canonical RFC 3339 profile;
+- leap-second `:60` values and noncanonical lowercase timestamp separators, which this scheduling contract deliberately excludes even though RFC 3339 itself defines broader lexical cases;
+- an end time that is not later than its start time;
+- time-zone identifiers rejected by the runtime's IANA/ICU database;
+- numeric UTC offsets whose asserted local clock fields disagree with the required IANA time zone at that instant, including daylight-saving transitions;
+- a norm-group identity that differs from the exported source band identity;
+- unsupported commitment status or RSVP direction;
+- non-finite or out-of-range confidence values;
+- empty, sparse, oversized, or malformed provenance receipt arrays;
+- JSON inputs larger than 256 KiB of UTF-8 or caller-owned values that cannot be safely snapshotted.
+
+`Z` and `-00:00` are accepted with an explicit IANA zone as unknown-local-offset forms; a numeric `+/-HH:MM` offset is treated as an assertion and must agree with that zone. This follows RFC 9557's update to RFC 3339: `Z` and `-00:00` do not assert a preferred local offset, while a numeric offset does.
+
+Validation errors identify the structural object containing an unknown field but never echo the caller-controlled field name. This preserves actionable location without copying tenant, person, credential, or other payload text into logs. Diagnostic locations such as `root`, `source`, and `provenance.evidence[0]` are schema-owned labels derived from validation structure, not from payload keys or values.
+
+Parsing snapshots caller-owned data once before validation and canonicalization. It then returns newly allocated nested objects and evidence receipts, so accessors, proxies, concurrent mutation, or retained input references cannot make validation observe different data from the canonical output.
+
+The standards rationale, semantic profile decisions, and APA 7 references are maintained in `docs/doctoring/naruon-rehearsal-handoff.md`.
+
+## Trust and privacy model
+
+This artifact contains **rehearsal coordination facts only**. It does not grant naruon filesystem, database, calendar, mail, model, or network authority. Transport, tenant authorization, detached signature verification, consent, context bridging, persistence, and writeback remain responsibilities of the naruon plugin/connector installation.
+
+A connector should:
+
+1. authenticate the producing BandScope installation and intended naruon tenant;
+2. verify a detached signature or authenticated transport envelope;
+3. parse the artifact using this contract;
+4. persist provenance before projecting Event/Commitment candidates;
+5. keep per-band context segregated by default;
+6. require explicit approval before any externally visible decline, reschedule, or CalDAV writeback.
+
+## Compatibility
+
+- `artifactKind`: `bandscope.naruon.rehearsal-event`
+- `artifactVersion`: `1`
+- Additive fields require a new version because version 1 rejects unknown keys.
+- Breaking semantic changes require a new artifact kind or major version.
+- The JSON Schema companion is `naruon-rehearsal-handoff-v1.schema.json`; validators must compile schema patterns with Unicode semantics for `\p{Nd}`. Under JSON Schema Draft 2020-12, `format` is not an assertion by default, so schema-only consumers must not treat `"format": "date-time"` as proof of complete temporal validity. The TypeScript parser remains authoritative for payload size, snapshotting, cross-field rules, leading/trailing whitespace normalization, Unicode-aware numeric-only identifier rejection, BandScope's canonical timestamp profile, RFC 9557 offset/time-zone consistency, and IANA time-zone checks.

packages/shared-types/package.json

@@ -2,7 +2,10 @@
   "name": "@bandscope/shared-types",
   "version": "0.1.0",
   "type": "module",
-  "exports": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./naruon": "./src/naruon.ts"
+  },
   "scripts": {
     "lint": "eslint \"src/**/*.ts\" \"test/**/*.ts\"",
     "typecheck": "tsc --noEmit",