v0.8: docs/LIFE_BINDING_SPEC.md + schemas/binding.schema.json + sanity tests (#103)

[devin-ai-integration]

Summary

Closes #103

Adds the per-topic normative spec for Topic 3 (Runtime Binding)
of the v0.8 architecture epic (#106). Tells runtimes which asset
backs each capability, which engines may host it, what is forbidden
(hard_constraints), what user-facing modes are supported
(surface), and whether hosted APIs may be called
(hosted_api_preference).

What this PR contains

• docs/LIFE_BINDING_SPEC.md (new, normative) — full spec.
  Conformance language, document layout, top-level fields, every
  Topic-3 decision against its schema realisation, a worked example,
  and a "what is left out" section.
• schemas/binding.schema.json (new) — JSON Schema for
  binding/runtime_binding.json (dlrs-life-binding/0.1).
  patternProperties enforce both the capability-name hybrid
  vocabulary AND the hard-constraints hybrid keyspace;
  additionalProperties: false makes unknown non-x- keys reject
  statically (D4=C fail-close at schema layer).
• tools/test_binding_schema.py (new) — 52 sanity cases
  (4 happy + 48 negative) covering every required field, every
  conditional, every hybrid-vocabulary boundary, every
  additionalProperties: false boundary. Wired into
  tools/batch_validate.py.
• CHANGELOG.md — v0.8 (Draft) gains a Binding entry next to
  Genesis.

Decisions encoded (Topic 3 + cross-topic)

#	Decision	Schema realisation
D1=C	Hybrid capability vocabulary	capabilities.patternProperties core enum + x- extension regex; everything else rejected.
D2=C	Issuer-self-decided engine strictness	engine_entry.strict boolean (default true).
D3 → tier system	Replaced by tier (#104)	capability_binding.tier_floor references it; full definition lives in [#104].
D4=C	Hybrid hard_constraints + fail-close	hard_constraints.patternProperties ~30 core keys + x-; additionalProperties: false.
D5=A	AND-gate hosted-API decision	hosted_api_preference (issuer half) + policy/hosted_api.json (user half); default-deny when section omitted.
Topic 4 D4=C	Three-field surface shape	supported / preferred / minimum_required.

Local validation

• python tools/test_binding_schema.py → 52/52 cases pass
• python tools/batch_validate.py → 20/20 steps pass
  (this PR adds test_binding_schema as step 14; once v0.8: docs/LIFE_LIFECYCLE_SPEC.md + schemas/lifecycle.schema.json + sanity tests (#102) #110 lands
  master will gain test_lifecycle_schema as step 14 too — trivial
  rebase.)

Review & Testing Checklist for Human

Risk: green — pure spec + JSON Schema + tests. No runtime code,
no changes to existing v0.7 specs or schemas, no example-package
changes. The schema only DEFINES the binding shape — no existing
file is validated against it until v0.9 runtime work consumes it.

• Skim docs/LIFE_BINDING_SPEC.md end-to-end and confirm the
  four locked Topic-3 decisions are encoded faithfully
  (especially D4=C fail-close and D5=A default-deny semantics).
• Spot-check the core capability enum (~20 names) and the core
  hard_constraints keys (~30 names) against the realistic
  vocabulary you want — both lists are intentionally hard to
  shrink later but easy to extend.
• Confirm surface_mode ordering (text_only < chat < voice_chat < avatar_2d < avatar_3d < vr) matches your mental
  model of "render-capability requirements".

Notes

• This is the fourth of six v0.8 PRs. Sequence: v0.8: docs/LIFE_ASSET_ARCHITECTURE.md — overview doc (#100) #107 (overview, ✓
  merged) → v0.8: docs/LIFE_GENESIS_SPEC.md + schemas/genesis.schema.json + sanity tests (#101) #108 (Genesis, ✓ merged) → fix(.life): genesis audit_event_ref pattern is 1-based, matches repo convention (post-#108 review) #109 (#L0 follow-up, ✓
  merged) → v0.8: docs/LIFE_LIFECYCLE_SPEC.md + schemas/lifecycle.schema.json + sanity tests (#102) #110 (Lifecycle, in review) → this PR (v0.8: docs/LIFE_BINDING_SPEC.md + schemas/binding.schema.json + sanity tests #103
  Binding) → v0.8: docs/LIFE_TIER_SPEC.md + life-package.schema.json::tier + Schema D appendix #104 (Tier + Schema D) → v0.8: docs/LIFE_RUNTIME_STANDARD.md update — 5-stage assembly + Provider Registry #105 (Runtime / Assembly).
• audit_event_ref-style paths are not used by the binding (the
  binding is reasoned-about, not append-logged), so the 1-based
  pattern fix from fix(.life): genesis audit_event_ref pattern is 1-based, matches repo convention (post-#108 review) #109 is not relevant here.

Link to Devin session: https://app.devin.ai/sessions/ff7322e18fd94887875daa2c1c75f87d
Requested by: @LING71671

---

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 8 additional findings in Devin Review.

[devin-ai-integration]

🟡 Missing path-traversal rejection on avatar_image_ref and background_audio_ref unlike sibling providers_whitelist_ref

Within the same schema, providers_whitelist_ref (schemas/binding.schema.json:227) has the path-traversal-rejection pattern ^(?!/)(?!.*\.\.).+$ to block absolute paths and .. segments — a cross-schema convention shared with life-package.schema.json:213 and lifecycle.schema.json:146. However, avatar_image_ref and background_audio_ref at lines 189-190 are also _ref path fields inside surface.ui_hints that reference files within the .life zip (avatar image, background audio), yet they only enforce minLength: 1 with no path-traversal pattern. A malicious binding could set avatar_image_ref to ../../etc/passwd or /etc/shadow and pass schema validation; a loader that naively resolves the path could be tricked into reading or exposing files outside the .life archive. The CHANGELOG explicitly calls out path-traversal rejection as a tightened defence-in-depth convention for this PR (CHANGELOG.md:83-86).

Suggested change

	"avatar_image_ref": { "type": "string", "minLength": 1 },
	"background_audio_ref": { "type": "string", "minLength": 1 }
	"avatar_image_ref": { "type": "string", "minLength": 1, "pattern": "^(?!/)(?!.*\\.\\.).+$" },
	"background_audio_ref": { "type": "string", "minLength": 1, "pattern": "^(?!/)(?!.*\\.\\.).+$" }

---

Was this helpful? React with 👍 or 👎 to provide feedback.