docs(kiloclaw): add data model spec for instances and subscriptions

[jeanduplessis]

Note

This is the first in a series of PRs that will work to satisfy the data model contract this spec introduces. The spec is therefore forward-looking and does not reflect the state of the codebase at this moment.

Summary

Adds a business-rule spec for the KiloClaw data model — the kiloclaw_instance and kiloclaw_subscription tables and the invariants all consumers must follow.

Why this change is needed

Multiple services (web app, kiloclaw CF worker, kiloclaw-billing, background jobs) operate on instances and subscriptions without a single source of truth for the rules governing record existence, immutability, lookup patterns, and creation order. This leads to ambiguity about what the system must guarantee and makes it harder to evaluate changes for correctness.

How this is addressed

• Introduces .specs/kiloclaw-datamodel.md covering record immutability (including GDPR anonymization), the instance–subscription pairing invariant, early-bird backfill requirements, multi-instance support with per-context limits, primary-key-based lookup rules, a subscription change log spec with actor tracking and transaction semantics, and the target record creation order with partial-failure handling.
• Documents the migration path from current state to target invariants and lists items not yet implemented.
• Adds the new spec to the AGENTS.md specs table so contributors know to consult it.

Human Verification

• Manual review of spec rules.

Visual Changes

N/A

Reviewer Notes

Human Reviewer

• Spec introduction — This is a new spec in .specs/. Review the business rules (especially rules 4–6 on instance–subscription pairing and the early-bird exception, rules 12–18 on the subscription change log, and rules 19–23 on creation order) for accuracy against current system behavior and intended direction.
• Assumptions — The spec assumes early-bird backfill will be completed before enforcing creation-order rules. The "Not Yet Implemented" section calls out three areas where current behavior diverges from the spec's SHOULD-level guidance.

Code Reviewer Agent

Code Reviewer Notes

• Documentation-only change — no code modified.
• Spec uses RFC 2119 / RFC 8174 keywords (MUST, SHOULD, MAY) to distinguish hard invariants from aspirational rules.
• The "Not Yet Implemented" section explicitly marks three items as not enforced in the current codebase.
• AGENTS.md updated to register the new spec in the specs table.

[kilo-code-bot]

WARNING: This exception breaks the audit-trail invariant

Earlier rules say every subscription mutation MUST have a change log entry and that the log is the authoritative history. Allowing the mutation to succeed when the log write fails means the system can permanently miss entries unless the spec also requires retry or reconciliation semantics.

[jeanduplessis]

Valid concern. Rule 15 now requires retry or reconciliation for out-of-transaction change log failures, with a bounded-time SLA for backfilling missing entries. The mutation still proceeds (availability over consistency for the business operation), but the audit trail gap must be closed within a defined window — not silently dropped.

[kilo-code-bot]

WARNING: This creation order conflicts with rule 4

Rule 4 says an instance record MUST NOT exist without a subscription record, but this sequence commits the instance row before the billing service creates the subscription row. Unless both records are created atomically, the database temporarily contains the orphaned state that the spec says must never exist.

[jeanduplessis]

Valid catch. Two changes address this:

1. Rule 4 now explicitly states the invariant is eventually-consistent — a bounded creation window exists between instance INSERT and subscription INSERT during provisioning.
2. Rule 22 now requires subscription creation within the same provisioning request (bounding the window) and mandates retry or remediation marking on failure, so orphaned instances cannot be silently ignored.

[kilo-code-bot]

Code Review Summary

Status: 1 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	1
SUGGESTION	0

Issue Details (click to expand)

WARNING

File	Line	Issue
.specs/kiloclaw-datamodel.md	225	Rule 19 still requires an infra-provider base resource for every instance, but the definition says only some providers have one.

Fix these issues in Kilo Cloud

Other Observations (not in diff)

None.

Files Reviewed (2 files)

• .specs/kiloclaw-datamodel.md - 1 issue
• AGENTS.md

---

_{Reviewed by gpt-5.4-2026-03-05 · 405,807 tokens}

[pandemicsyn]

couple of changes inline just because the NF still will be landing in the next day or two.

[kilo-code-bot]

WARNING: Rule 19 becomes impossible for providers without a base resource

The new Infra Provider Base Resource definition says only some providers have this top-level resource, but rule 19 now requires one for every instance before the row can exist. That makes the precondition unsatisfiable for providers that do not expose a base resource and turns a provider-specific concept into a universal invariant.

[jeanduplessis]

This is an acceptable gap/risk for now which will be handled at the provider integration layer.