@unifyplane/logsdk 1.0.0

package/contracts/specs/sink-contract.v1.md

@@ -0,0 +1,223 @@
+
+# 🧩 LogSDK Core — Sink / Emitter Contract (v1.0)
+
+## Table of Contents
+
+- [Purpose (Non-Negotiable)](#section-purpose-non-negotiable)
+- [1. Conceptual Definition](#section-1-conceptual-definition)
+- [2. Core Sink Contract (Conceptual Interface)](#section-2-core-sink-contract-conceptual-interface)
+- [3. Input Guarantees (What the Core Promises to Sinks)](#section-3-input-guarantees-what-the-core-promises-to-sinks)
+- [4. Sink Guarantees (What Sinks Must Promise)](#section-4-sink-guarantees-what-sinks-must-promise)
+- [5. Sink Categories (Semantic, Not Technical)](#section-5-sink-categories-semantic-not-technical)
+- [6. Failure Semantics (High-Level Only)](#section-6-failure-semantics-high-level-only)
+- [7. What Sinks Are Explicitly Forbidden To Do](#section-7-what-sinks-are-explicitly-forbidden-to-do)
+- [8. Why This Contract Is Minimal (And Correct)](#section-8-why-this-contract-is-minimal-and-correct)
+- [9. Freeze Statement](#section-9-freeze-statement)
+
+<a id="section-purpose-non-negotiable"></a>
+## Purpose (Non-Negotiable)
+
+A **Sink (Emitter)** is a **pure output boundary**.
+
+Its only responsibility is to:
+
+> **Accept an immutable Step Record and persist or forward it elsewhere.**
+
+A sink:
+
+* does **not** enrich
+* does **not** interpret
+* does **not** derive meaning
+* does **not** influence execution
+
+---
+
+<a id="section-1-conceptual-definition"></a>
+## 1. Conceptual Definition
+
+A **Sink** is a component that:
+
+1. Receives a **fully constructed, immutable Step Record**
+2. Emits it to a destination
+3. Acknowledges success or failure
+4. Never mutates the record
+
+That is all.
+
+---
+
+<a id="section-2-core-sink-contract-conceptual-interface"></a>
+## 2. Core Sink Contract (Conceptual Interface)
+
+Every sink **must** conform to the following conceptual contract:
+
+### Required Capability
+
+| Capability     | Meaning                          |
+| -------------- | -------------------------------- |
+| `emit(record)` | Accept one immutable Step Record |
+
+### Optional Capability
+
+| Capability | Meaning                                 |
+| ---------- | --------------------------------------- |
+| `flush()`  | Ensure buffered records are persisted   |
+| `close()`  | Finalize resources (files, connections) |
+
+---
+
+<a id="section-3-input-guarantees-what-the-core-promises-to-sinks"></a>
+## 3. Input Guarantees (What the Core Promises to Sinks)
+
+Before a record reaches any sink, LogSDK Core guarantees:
+
+* record is **canonical**
+* record is **schema-complete**
+* record is **immutable**
+* record is **bounded**
+* record integrity hash is present
+* context is referenced, not embedded
+
+Sinks **must not validate semantics** again.
+
+---
+
+<a id="section-4-sink-guarantees-what-sinks-must-promise"></a>
+## 4. Sink Guarantees (What Sinks Must Promise)
+
+A compliant sink must guarantee:
+
+### 4.1 Non-Mutation
+
+* No field modification
+* No field addition
+* No field removal
+* No re-interpretation
+
+Transport metadata (e.g. HTTP headers) is allowed **outside** the record.
+
+---
+
+### 4.2 Deterministic Handling
+
+Given the same Step Record:
+
+* the sink must behave the same way
+* ordering must be preserved *as received*
+
+---
+
+### 4.3 Isolation
+
+A sink:
+
+* must not call other sinks
+* must not depend on other sinks
+* must not affect core behavior
+
+---
+
+<a id="section-5-sink-categories-semantic-not-technical"></a>
+## 5. Sink Categories (Semantic, Not Technical)
+
+### 5.1 Authoritative Evidence Sinks (Required)
+
+These sinks define **evidence ownership**.
+
+Examples:
+
+* append-only file sink
+* object storage sink
+* immutable log archive
+
+Rules:
+
+* long retention
+* append-only semantics
+* replayable
+* system-owned
+
+At least **one authoritative sink is mandatory**.
+
+---
+
+### 5.2 Observability Sinks (Optional)
+
+These sinks exist for **human visibility**.
+
+Examples:
+
+* Grafana Loki
+* stdout / console
+* debug streams
+
+Rules:
+
+* best-effort delivery
+* retention not guaranteed
+* never authoritative
+* may be dropped without governance impact
+
+---
+
+<a id="section-6-failure-semantics-high-level-only"></a>
+## 6. Failure Semantics (High-Level Only)
+
+Sink failures are classified conceptually:
+
+| Sink Type     | Failure Impact         |
+| ------------- | ---------------------- |
+| Authoritative | **System-significant** |
+| Observability | **Non-blocking**       |
+
+**Important:**
+This classification informs **fan-out rules** (next step), not sink behavior itself.
+
+---
+
+<a id="section-7-what-sinks-are-explicitly-forbidden-to-do"></a>
+## 7. What Sinks Are Explicitly Forbidden To Do
+
+A sink must never:
+
+* inject labels / tags
+* infer severity
+* drop fields
+* reorder records
+* batch across executions
+* correlate records
+* compute metrics
+* call UnifyPlane
+* call other sinks
+
+If any occur, the sink is **non-compliant**.
+
+---
+
+<a id="section-8-why-this-contract-is-minimal-and-correct"></a>
+## 8. Why This Contract Is Minimal (And Correct)
+
+This design ensures:
+
+* replayability
+* deterministic intelligence derivation
+* language neutrality
+* storage freedom
+* safe observability fan-out
+* no governance coupling
+
+Anything more would leak responsibility.
+
+---
+
+<a id="section-9-freeze-statement"></a>
+## 9. Freeze Statement
+
+This **Sink / Emitter Contract v1.0** is now:
+
+* stable
+* minimal
+* sufficient
+* extensible without breaking meaning
+
+All current and future sinks **must** conform to this.

package/contracts/specs/step-record.v1.md

@@ -0,0 +1,292 @@
+
+# 🧩 LogSDK Core — Canonical Step Record (v1.1)
+
+## Table of Contents
+- [Purpose (Non-Negotiable)](#section-purpose-non-negotiable)
+- [Canonical Record: Field Set](#section-canonical-record-field-set)
+- [1. Identity & Versioning](#section-1-identity-and-versioning)
+- [2. Time (Dual Clock — Mandatory)](#section-2-time-dual-clock-mandatory)
+- [3. System Ownership (Evidence Boundary)](#section-3-system-ownership-evidence-boundary)
+- [4. Execution Correlation (SDK-Derived Only)](#section-4-execution-correlation-sdk-derived-only)
+- [5. Execution Surface (Where This Happened)](#section-5-execution-surface-where-this-happened)
+- [6. Source Location (Best-Effort, Factual)](#section-6-source-location-best-effort-factual)
+- [7. Step Message (Only Human Input)](#section-7-step-message-only-human-input)
+- [8. Context Capsule Reference (Frozen Once)](#section-8-context-capsule-reference-frozen-once)
+- [9. Evidence References (Optional, Structured)](#section-9-evidence-references-optional-structured)
+- [10. Integrity (Normative)](#section-10-integrity-normative)
+- [Explicit Exclusions (Hard Rules)](#section-explicit-exclusions-hard-rules)
+- [Semantic Meaning (Locked)](#section-semantic-meaning-locked)
+- [Determinism Guarantees (Explicit)](#section-determinism-guarantees-explicit)
+- [Freeze Statement](#section-freeze-statement)
+- [Appendix A. Revision Notes (Non-Normative)](#appendix-a-revision-notes-non-normative)
+<a id="section-purpose-non-negotiable"></a>
+## Purpose (Non-Negotiable)
+
+A **Step Record** represents **one execution step** as immutable execution evidence.
+
+It must be:
+
+* replayable
+* bounded
+* deterministic
+* storage-agnostic
+* derivation-ready
+
+It must **not** encode decisions, payloads, intelligence, or interpretation.
+
+---
+<a id="section-canonical-record-field-set"></a>
+## Canonical Record: Field Set
+
+<a id="section-1-identity-and-versioning"></a>
+### 1. Identity & Versioning
+
+| Field            | Description                                                  |
+| ---------------- | ------------------------------------------------------------ |
+| `record_version` | Fixed identifier of the record contract (e.g. `log.step.v1`) |
+| `record_id`      | Unique identifier for this step record                       |
+| `sequence`       | Monotonic sequence number scoped to the SDK instance         |
+
+**Rules**
+
+* `record_version` is immutable and schema-defining
+* `record_id` must be globally unique per process and SDK instance
+* `sequence` must start at `0` and increment by exactly `1`
+
+---
+
+<a id="section-2-time-dual-clock-mandatory"></a>
+### 2. Time (Dual Clock — Mandatory)
+
+| Field            | Description                                             |
+| ---------------- | ------------------------------------------------------- |
+| `timestamp_utc`  | Wall-clock time in UTC (RFC 3339 / ISO-8601 profile)    |
+| `monotonic_time` | Monotonic clock value for strict intra-process ordering |
+
+**Rules**
+
+* Both fields are required
+* Ordering **must never** depend on wall clock alone
+* `monotonic_time` must be strictly increasing per record
+
+---
+
+<a id="section-3-system-ownership-evidence-boundary"></a>
+### 3. System Ownership (Evidence Boundary)
+
+| Field            | Description                                         |
+| ---------------- | --------------------------------------------------- |
+| `institution`    | Owning organization or authority domain             |
+| `system_name`    | Logical system emitting the step                    |
+| `system_type`    | `process` / `pipeline` / `service` / `content`      |
+| `environment`    | `local` / `dev` / `staging` / `prod`                |
+| `system_version` | Deployed version or build identifier                |
+| `instance_id`    | Runtime instance identifier (optional but expected) |
+
+These fields define **who owns the evidence** and where its trust boundary lies.
+
+They must be injected by the SDK or system adapter, never manually set per step.
+
+---
+
+<a id="section-4-execution-correlation-sdk-derived-only"></a>
+### 4. Execution Correlation (SDK-Derived Only)
+
+| Field            | Description                                              |
+| ---------------- | -------------------------------------------------------- |
+| `trace_id`       | Distributed trace identifier (if available)              |
+| `span_id`        | Span identifier (if available)                           |
+| `parent_step_id` | Parent step record ID (if hierarchical execution exists) |
+
+**Rules**
+
+* These fields are **derived automatically**
+* No developer may set or override them
+* Absence is valid if the execution model does not support correlation
+
+---
+
+<a id="section-5-execution-surface-where-this-happened"></a>
+### 5. Execution Surface (Where This Happened)
+
+| Field              | Description                                             |
+| ------------------ | ------------------------------------------------------- |
+| `surface_type`     | `http` / `job` / `worker` / `page` / `cli` / `internal` |
+| `surface_name`     | Route, job name, page name, etc.                        |
+| `surface_instance` | Request ID / job ID / execution ID                      |
+
+**Rules**
+
+* Derived by thin SDKs or runtime adapters only
+* Must reflect *execution context*, not business semantics
+
+---
+
+<a id="section-6-source-location-best-effort-factual"></a>
+### 6. Source Location (Best-Effort, Factual)
+
+| Field             | Description             |
+| ----------------- | ----------------------- |
+| `source_file`     | Repo-relative file path |
+| `source_module`   | Module or package name  |
+| `source_function` | Function or method name |
+| `source_line`     | Line number (nullable)  |
+
+**Rules**
+
+* Automatically injected by the SDK where possible
+* Must never be developer-supplied
+* Absence (`null`) is acceptable when not reliably obtainable
+
+---
+
+<a id="section-7-step-message-only-human-input"></a>
+### 7. Step Message (Only Human Input)
+
+| Field          | Description                                      |
+| -------------- | ------------------------------------------------ |
+| `message`      | Human-readable step description (bounded string) |
+| `message_code` | Optional registry-defined step code              |
+
+**Hard Constraints**
+
+* String only
+* Non-empty
+* Hard length limit
+* No JSON, arrays, or objects
+* No payloads
+* No free-form metadata
+
+This is the **only expressive input** a developer provides.
+
+---
+
+<a id="section-8-context-capsule-reference-frozen-once"></a>
+### 8. Context Capsule Reference (Frozen Once)
+
+| Field             | Description                                       |
+| ----------------- | ------------------------------------------------- |
+| `context_hash`    | Hash reference to frozen context injected at init |
+| `context_version` | Version of the context schema                     |
+
+**Rules**
+
+* Context is injected once at SDK initialization
+* Context is normalized, canonicalized, and deeply frozen
+* Context is **never embedded** in records
+* Records reference context **by hash only**
+
+---
+
+<a id="section-9-evidence-references-optional-structured"></a>
+### 9. Evidence References (Optional, Structured)
+
+| Field           | Description                                        |
+| --------------- | -------------------------------------------------- |
+| `evidence_refs` | Array of references to external evidence artifacts |
+
+**Rules**
+
+* References only (IDs, URIs, digests)
+* No embedded data
+* No payload material
+
+---
+
+<a id="section-10-integrity-normative"></a>
+### 10. Integrity (Normative)
+
+| Field            | Description                             |
+| ---------------- | --------------------------------------- |
+| `record_hash`    | Hash of the canonical serialized record |
+| `hash_algorithm` | Algorithm used (explicit, versioned)    |
+
+**Rules**
+
+* Record must be canonically serialized before hashing
+* `record_hash` must **exclude itself** from hash scope
+* Canonical serialization must be deterministic across runtimes
+* UTF-8 encoding is mandatory
+
+This guarantees:
+
+* immutability
+* tamper detection
+* replay stability
+
+---
+<a id="section-explicit-exclusions-hard-rules"></a>
+## Explicit Exclusions (Hard Rules)
+
+A Step Record **must never contain**:
+
+* business payloads
+* metrics or counters
+* severity levels
+* labels or tags
+* inferred meaning
+* decisions or judgments
+* AI outputs
+* free-form metadata
+
+Presence of any of the above renders the record **invalid**.
+
+---
+<a id="section-semantic-meaning-locked"></a>
+## Semantic Meaning (Locked)
+
+> A Step Record asserts only:
+> **“This execution step occurred at this point in this system.”**
+
+It does **not** assert:
+
+* correctness
+* success
+* legitimacy
+* intent
+* impact
+
+---
+<a id="section-determinism-guarantees-explicit"></a>
+## Determinism Guarantees (Explicit)
+
+Given identical:
+
+* initialization context
+* execution order
+* SDK version
+
+The sequence, structure, and meaning of Step Records must be **replay-stable**, aside from timestamps and identifiers.
+
+---
+<a id="section-freeze-statement"></a>
+## Freeze Statement
+
+This **Canonical Step Record v1.1** is:
+
+* language-independent
+* runtime-agnostic
+* ABI-like
+* safe for long-term replay and audit
+
+All thin SDKs **must map into this shape exactly**, without extension or semantic enrichment.
+
+---
+
+<a id="appendix-a-revision-notes-non-normative"></a>
+## Appendix A. Revision Notes (Non-Normative)
+
+### Why this update matters
+
+* Hashing and determinism are now **normative**, not implied
+* Source and surface fields are clearly bounded
+* The record is now **unambiguously evidence-only**
+* This shape can survive **decades of system evolution**
+
+If you want next, the logically correct follow-ups are:
+
+* a **canonical JSON Schema** for this record
+* a **hash canonicalization appendix** (RFC-aligned)
+* or a **LogSDK → Step Record conformance checklist**
+
+Say which one you want to proceed with.