@precepts/standards 0.1.0

package/standards/integration/standards/data-formats/character-encoding.md

@@ -0,0 +1,206 @@
+---
+identifier: "INTG-STD-005"
+name: "Character Encoding"
+version: "1.0.0"
+status: "MANDATORY"
+
+domain: "INTEGRATION"
+documentType: "standard"
+category: "format"
+appliesTo: ["api", "events", "a2a", "files", "mcp", "webhooks", "grpc", "graphql", "batch", "streaming"]
+
+lastUpdated: "2026-03-28"
+owner: "Integration Architecture Board"
+
+standardsCompliance:
+  iso: ["ISO-10646"]
+  rfc: ["RFC-3629", "RFC-8259", "RFC-5198", "RFC-2277"]
+  w3c: ["Character-Model-for-the-World-Wide-Web"]
+  other: []
+
+taxonomy:
+  capability: "data-format"
+  subCapability: "character-encoding"
+  layer: "contract"
+
+enforcement:
+  method: "automated"
+  validationRules:
+    encoding: "UTF-8"
+    normalization: "NFC"
+    bom: "forbidden-in-json"
+  rejectionCriteria:
+    - "Non-UTF-8 encoded payloads"
+    - "BOM in JSON payloads"
+    - "Unassigned or surrogate code points"
+
+dependsOn: []
+supersedes: ""
+---
+
+# Character Encoding
+
+## Purpose
+
+This standard defines the **REQUIRED** character encoding for all text data exchanged across integration boundaries. Inconsistent encoding causes data corruption, security vulnerabilities, and integration failures. All integration surfaces **MUST** use UTF-8 with NFC normalization to guarantee round-trip fidelity and deterministic string comparison.
+
+> *Normative language (**MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, **MAY**) follows RFC 2119 semantics.*
+
+---
+
+## Rules
+
+### R-1: UTF-8 as Sole Encoding
+
+All text data crossing integration boundaries **MUST** be encoded in UTF-8 (RFC 3629).
+
+- UTF-16, UTF-32, ISO-8859-x, Windows-125x, Shift_JIS, and all other encodings **MUST NOT** be used at integration boundaries.
+- Internal representations **MAY** use other encodings, but **MUST** convert to UTF-8 before crossing any boundary.
+
+### R-2: Valid UTF-8 Sequences Only
+
+All byte sequences **MUST** be well-formed per RFC 3629. The following **MUST** be rejected:
+
+- Overlong encodings (e.g., `C0 80` for U+0000)
+- Surrogate halves (U+D800 through U+DFFF)
+- Code points beyond U+10FFFF
+- Truncated multi-byte sequences
+- Unexpected continuation bytes without a valid leading byte
+
+### R-3: NFC Normalization
+
+All text **MUST** be normalized to NFC (RFC 5198) before transmission.
+
+- Producers **MUST** emit NFC-normalized text.
+- Consumers **SHOULD** verify NFC normalization on input.
+- String comparison at integration boundaries **MUST** compare NFC-normalized forms.
+- NFKC or NFKD **MUST NOT** be applied at integration boundaries - compatibility decomposition is lossy.
+
+### R-4: BOM (Byte Order Mark) Handling
+
+The UTF-8 BOM (`EF BB BF`) **MUST** be handled per format:
+
+| Format | BOM Rule | Rationale |
+|---|---|---|
+| JSON | **MUST NOT** be present | RFC 8259 forbids it |
+| XML | **MAY** be present; parsers **MUST** tolerate | XML spec permits BOM |
+| CSV | **SHOULD** be present for spreadsheet interop | Required for UTF-8 detection in common tools |
+| Protocol Buffers / gRPC | **MUST NOT** be present | Binary framing; BOM is meaningless |
+| GraphQL | **MUST NOT** be present | Spec treats BOM as insignificant |
+| Plain text (logs, config) | **SHOULD NOT** be present | Breaks concatenation and Unix tools |
+| HTTP bodies | **MUST NOT** be present in JSON/API responses | Redundant with Content-Type header |
+
+If a BOM is encountered where forbidden, the system **MUST** strip it before processing and **MAY** log a warning.
+
+### R-5: Encoding Declaration
+
+The encoding **MUST** be declared through the appropriate mechanism:
+
+| Surface | Declaration Mechanism |
+|---|---|
+| HTTP responses | `Content-Type` header with `charset=utf-8` |
+| HTTP requests | `Content-Type` header **MUST** include `charset=utf-8` for text payloads |
+| XML documents | `<?xml version="1.0" encoding="UTF-8"?>` **MUST** be present |
+| HTML documents | `<meta charset="UTF-8">` **MUST** appear within first 1024 bytes |
+| CSV files | UTF-8 BOM as first bytes; `text/csv; charset=utf-8` in HTTP |
+| Event payloads | Schema registry or envelope **MUST** declare encoding |
+| Message queues | Message metadata **MUST** declare `charset=utf-8` |
+| gRPC / Protobuf | Implicit - `string` type is defined as UTF-8 |
+| File transfers | Filename convention or manifest **MUST** declare encoding |
+
+### R-6: Rejection Policy
+
+Systems receiving data at integration boundaries **MUST** validate encoding:
+
+- **API gateways** **MUST** reject non-UTF-8 payloads with HTTP 400 and a descriptive error.
+- **Event consumers** **MUST** route non-UTF-8 messages to a dead-letter queue and emit an alert.
+- **File processors** **MUST** reject non-UTF-8 files and log the detected encoding.
+- **Batch jobs** **MUST** fail the individual record (not the entire batch) and report violations in the summary.
+
+Systems **MUST NOT** silently replace invalid bytes with U+FFFD at integration boundaries. Replacement characters are acceptable only for internal display or logging.
+
+### R-7: Database Storage
+
+Integration-facing tables **MUST** use UTF-8-compatible character sets and collation. Notably, 3-byte "utf8" in MySQL **MUST NOT** be used - it cannot represent characters outside the Basic Multilingual Plane. Use the full 4-byte UTF-8 character set instead.
+
+### R-8: Special Character Handling
+
+| Context | Rule |
+|---|---|
+| JSON strings | Control characters (U+0000 - U+001F) **MUST** be escaped per RFC 8259 |
+| XML content | Syntax-conflicting characters **MUST** use entities or CDATA; control chars other than TAB, LF, CR **MUST NOT** appear |
+| URL parameters | Non-ASCII characters **MUST** be percent-encoded after UTF-8 encoding (RFC 3986) |
+| SQL | Parameterized queries **MUST** be used; string concatenation with user Unicode input **MUST NOT** be used |
+| Log output | Non-printable characters **SHOULD** be escaped using `\uXXXX` notation |
+
+---
+
+## Examples
+
+### Valid: UTF-8 JSON with Encoding Declaration
+
+A JSON payload containing multilingual text, served with the correct Content-Type header (`application/json; charset=utf-8`). All characters are valid UTF-8, NFC-normalized, and no BOM is present.
+
+### Invalid: Non-UTF-8 Payload
+
+A payload containing bare `0xE9` (Latin-1 "e-acute") without valid UTF-8 continuation bytes. Rejected at the gateway with error code `INVALID_ENCODING` and the byte offset of the invalid sequence.
+
+---
+
+## Enforcement Rules
+
+| Violation | Action | Error Code |
+|---|---|---|
+| Non-UTF-8 encoding detected | Reject (HTTP 400 or equivalent) | `INVALID_ENCODING` |
+| Invalid UTF-8 byte sequence | Reject (HTTP 400 or equivalent) | `INVALID_UTF8` |
+| BOM present in JSON payload | Strip, process, and log warning | `UNEXPECTED_BOM` |
+| Surrogate code point | Reject (HTTP 400 or equivalent) | `SURROGATE_CODEPOINT` |
+| Non-character code point | Reject (HTTP 400 or equivalent) | `NONCHARACTER` |
+| Forbidden control character (C0 other than TAB/LF/CR, or C1) | Reject (HTTP 400 or equivalent) | `FORBIDDEN_CONTROL` |
+| NULL (U+0000) in JSON or XML | Reject (HTTP 400 or equivalent) | `FORBIDDEN_CONTROL` |
+| Private-use code points without bilateral agreement | Reject or log warning | `PRIVATE_USE` |
+| Missing encoding declaration | Log warning; assume UTF-8 | `MISSING_CHARSET` |
+
+Enforcement **MUST** occur at the outermost integration boundary (API gateway, message broker ingress, file intake). Interior services **MAY** rely on gateway validation.
+
+---
+
+## Security Considerations
+
+| Threat | Attack Vector | Mitigation |
+|---|---|---|
+| Encoding injection | Overlong UTF-8 sequences bypass path/input filters (e.g., `C0 AF` encodes `/`) | R-2 eliminates overlong sequences; R-6 rejects non-UTF-8 before application logic |
+| Normalization bypass | Visually identical strings with different byte representations bypass auth checks | R-3 mandates NFC; comparison **MUST** use normalized forms |
+| Homoglyph spoofing | Characters from different scripts appear identical (Latin "a" vs Cyrillic "a") | Systems processing user-visible identifiers **SHOULD** apply confusable detection (UTS #39) |
+| Null byte injection | Embedded U+0000 truncates strings in C-based systems, enabling filter bypass | Enforcement rules forbid NULL in text payloads |
+
+---
+
+## References
+
+- [**RFC 3629**](https://www.rfc-editor.org/rfc/rfc3629) - UTF-8 (STD 63)
+- [**RFC 8259**](https://datatracker.ietf.org/doc/html/rfc8259) - JSON Data Interchange Format
+- [**RFC 5198**](https://www.rfc-editor.org/rfc/rfc5198) - Unicode Format for Network Interchange
+- [**RFC 2277 / BCP 18**](https://www.rfc-editor.org/rfc/rfc2277.html) - IETF Policy on Character Sets and Languages
+- [**RFC 3986**](https://www.rfc-editor.org/rfc/rfc3986) - URI Generic Syntax
+- [**W3C Character Model**](https://www.w3.org/TR/charmod/) - Fundamentals
+- [**Unicode Standard Annex #15**](https://unicode.org/reports/tr15/) - Normalization Forms
+- [**Unicode Technical Standard #39**](https://unicode.org/reports/tr39/) - Security Mechanisms
+
+---
+
+## Rationale
+
+**UTF-8 exclusively:** UTF-8 encodes every Unicode code point, is mandated by RFC 8259 (JSON) and BCP 18 (IETF protocols), is ASCII-compatible, self-synchronizing, and used by over 98% of web pages.
+
+**NFC over other forms:** NFC is the most compact canonical form, preserves compatibility characters (unlike lossy NFKC/NFKD), and is recommended by both W3C and RFC 5198.
+
+**Per-format BOM rules:** No single BOM policy fits all consumers - JSON forbids it (RFC 8259), while spreadsheet tools require it for reliable UTF-8 detection.
+
+---
+
+## Version History
+
+| Version | Date       | Change             |
+| ------- | ---------- | ------------------ |
+| 1.0.0   | 2026-03-28 | Initial definition |

package/standards/integration/standards/data-formats/date-format.md

@@ -0,0 +1,102 @@
+---
+identifier: "INTG-STD-001"
+name: "Date Format"
+version: "1.0.0"
+status: "MANDATORY"
+
+domain: "INTEGRATION"
+documentType: "standard"
+category: "format"
+appliesTo: ["api", "events", "a2a", "mcp"]
+
+lastUpdated: "2026-02-16"
+owner: "Integration Architecture Board"
+
+standardsCompliance:
+  iso: ["ISO-8601"]
+  rfc: []
+  w3c: []
+  other: []
+
+taxonomy:
+  capability: "data-format"
+  subCapability: "date"
+  layer: "contract"
+
+enforcement:
+  method: "automated"
+  validationRules:
+    dateFormat: "YYYY-MM-DD"
+    regex: "^\\d{4}-\\d{2}-\\d{2}$"
+  rejectionCriteria:
+    - "Unix Epoch format"
+    - "Local timezone offsets"
+    - "Non-ISO date separators (slash, space)"
+  supportedFormats: ["ISO-8601"]
+  authoritativeModel: "ISO-8601"
+
+dependsOn: []
+supersedes: ""
+---
+
+# Date
+
+## Purpose
+
+All date values transmitted across any interface **MUST** follow the ISO-8601 format. This ensures deterministic interpretation across all systems, languages, and timezones.
+
+## Conceptual Model
+
+A date represents a calendar day without time-of-day or timezone information. The canonical representation is the ISO-8601 extended format: `YYYY-MM-DD`.
+
+## Rules
+
+- All date fields **MUST** use the `YYYY-MM-DD` format
+- Unix Epoch representations **MUST** be rejected
+- Local timezone offsets **MUST NOT** be included in date-only fields
+- Non-ISO separators (slash, space) **MUST** be rejected
+
+## Examples
+
+### Valid
+
+```json
+{ "created_at": "2026-02-16" }
+```
+
+### Invalid
+
+```json
+{ "created_at": "16-02-2026" }
+```
+```json
+{ "created_at": "16/02/2026" }
+```
+```json
+{ "created_at": "02-16-2026" }
+```
+
+## Validation Rules
+
+**Regex:** `^\d{4}-\d{2}-\d{2}$`
+
+Validation **MUST** occur at contract boundary (API gateway, event schema registry, message broker).
+
+## Enforcement Rules
+
+- **Constraint:** Reject any payload using Unix Epoch or local timezone offsets.
+- **Reference:** [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)
+
+## References
+
+- [**ISO-8601**](https://en.wikipedia.org/wiki/ISO_8601) - Date and time format standard
+
+## Rationale
+
+ISO-8601 `YYYY-MM-DD` is unambiguous across locales (unlike `DD/MM/YYYY` vs `MM/DD/YYYY`), sorts lexicographically, and is natively supported by all major programming languages and databases.
+
+## Version History
+
+| Version | Date       | Change             |
+| ------- | ---------- | ------------------ |
+| 1.0.0   | 2026-02-16 | Initial definition |

package/standards/integration/standards/data-formats/datetime-formats.md

@@ -0,0 +1,265 @@
+---
+identifier: "INTG-STD-002"
+name: "Date and Time"
+version: "2.0.0"
+status: "MANDATORY"
+
+domain: "INTEGRATION"
+documentType: "standard"
+category: "format"
+appliesTo: ["api", "events", "a2a", "mcp"]
+
+lastUpdated: "2026-01-29"
+owner: "Integration Architecture Board"
+
+standardsCompliance:
+  iso: ["ISO-8601"]
+  rfc: ["RFC-3339", "RFC-9557"]
+  w3c: []
+  other: []
+
+taxonomy:
+  capability: "data-format"
+  subCapability: "date-time"
+  layer: "contract"
+
+enforcement:
+  method: "automated"
+  absolute:
+    format: "RFC3339_UTC"
+    allowOffset: false
+    allowUnixEpoch: false
+    timezoneRequired: true
+    regex: "^d{4}-d{2}-d{2}Td{2}:d{2}:d{2}(.d{1,9})?Z$"
+  scheduled:
+    zoneRequired: true
+    allowOffsetOnly: false
+    authoritativeTuple: ["local_timestamp", "zone"]
+    supportedFormats:
+      - "RFC9557"
+      - "TRIPLE_FIELD_MODEL"
+
+classifications: ["ABSOLUTE", "SCHEDULED"]
+dependsOn: ["INTG-STD-001"]
+supersedes: ""
+---
+
+# Date and Time
+
+## Purpose
+
+This standard defines the **REQUIRED** representation of date and time values exchanged across all integration boundaries.
+
+The objective is to,
+
+- Deterministic interpretation
+- Cross-platform interoperability
+- DST and timezone resilience
+- Machine-governable validation
+- Long-term scheduling correctness
+
+> *Normative language (MUST, MUST NOT, SHOULD) follows RFC 2119 semantics.*
+
+---
+
+## Classifications
+
+There are two distinct semantic classifications of date-time representations.
+
+| Classification| Description                                  | Deterministic at creation time |
+|---------------|----------------------------------------------|--------------------------------|
+| **ABSOLUTE**  | Represents a past or present instant in time | Yes                            |
+| **SCHEDULED** | Represents a future planned occurrence       | No (offset subject to change)  |
+
+Representation strategy depends on the applicable classification.
+
+---
+
+## Rules
+
+### ABSOLUTE Timestamp Standard
+
+### Rules
+
+All **ABSOLUTE** timestamps **MUST**,
+1. Conform to RFC 3339
+2. Be expressed in UTC
+3. Use the literal `Z` suffix
+4. NOT use Unix Epoch format
+5. NOT use timezone offsets (`+01:00`)
+6. Represent a single unambiguous instant
+
+### Canonical Format
+
+`YYYY-MM-DDTHH:mm:ssZ`
+
+Optionally, fractional seconds **MAY** be allowed, with a maximum of 9 fractional digits.
+
+`YYYY-MM-DDTHH:mm:ss.SSSZ`
+
+### Validation Regex
+
+`^d{4}-d{2}-d{2}Td{2}:d{2}:d{2}(.d{1,9})?Z$`
+
+---
+
+### SCHEDULED (Future) Timestamp Standard
+
+### Distinction
+
+Future timestamps are not deterministic because,
+- DST (*Daylight Saving Time*) rules may change
+- Jurisdictions may modify timezone legislation
+- Offsets are derived values
+- Offset alone does not uniquely identify a timezone
+
+→ Offsets **MUST NOT** be authoritative for future scheduled timestamps.
+
+### Rules
+
+If a date-time represents a **SCHEDULED** future event,
+- An IANA (*Internet Assigned Numbers Authority*) timezone identifier (ZoneId) is **MANDATORY**
+- Zone **MUST** take precedence over offset
+- Offset-only representations **MUST** be rejected
+
+### Canonical Formats
+
+#### Timezone-Aware Systems (Preferred)
+
+Use **RFC-9557** format
+
+`YYYY-MM-DDTHH:mm:ss[Area/Location]`
+
+This preserves timezone identity independent of offset.
+
+#### Timezone-Unaware Systems (Fallback)
+
+Use the *Triple-Field Model*
+- `local_timestamp`: LocalDateTime without offset
+- `zone`: Valid IANA ZoneId
+- `utc_timestamp`: RFC-3339 canonical UTC
+
+Here, the authoritative representation is `(local_timestamp, zone)`, while `utc_timestamp` is a derived projection.
+
+### Interpretation Algorithm
+
+To compute execution instant,
+- Read `zone`
+- Apply current **tzdb** (*Timezone DB*) rules
+- Derive offset
+- Compute `utc_timestamp`
+- Execute at derived instant
+
+**NEVER** reverse this order.
+
+---
+
+## Examples
+
+### ABSOLUTE Timestamps
+
+#### Valid
+
+```json
+{ "created_at": "2026-02-16T09:30:45Z" }
+```
+
+```json
+{ "created_at": "2026-02-16T09:30:45.123Z" }
+```
+
+#### Invalid
+
+```json
+{ "created_at": "1698393600" }
+```
+
+```json
+{ "created_at": "2026-02-16T10:30:45+01:00" }
+```
+
+### SCHEDULED Timestamps
+
+#### Valid
+
+```json
+{ "scheduled_at": "2027-12-01T11:00:00[America/New_York]" }
+```
+
+```json
+{
+  "local_timestamp": "2027-12-01T11:00:00",
+  "zone": "America/New_York",
+  "utc_timestamp": "2027-12-01T16:00:00Z"
+}
+```
+
+#### Invalid
+
+```json
+{ "scheduled_at": "2027-12-01T11:00:00Z" }
+```
+
+```json
+{ "scheduled_at": "2026-02-16T10:30:45+01:00" }
+```
+
+```json
+{ "scheduled_at": "1698393600" }
+```
+
+---
+
+## Enforcement Rules
+
+The following payloads **MUST** be *rejected*,
+
+For **ABSOLUTE** timestamps:
+- Unix Epoch format
+- Offset-based timestamps
+- Missing timezone indicator
+- Local timestamps without Z
+
+For **SCHEDULED** timestamps:
+- Missing zone
+- Invalid IANA (*Internet Assigned Numbers Authority*) ZoneId
+- Offset-only representation
+- UTC timestamp inconsistent with tzdb projection
+
+Validation **MUST** occur at contract boundary.
+
+---
+
+## Rationale
+
+This standard ensures,
+- Deterministic event replay (event-driven systems)
+- Cross-language interoperability
+- Protection against DST drift
+- Regulatory resilience
+- AI-governable timestamp validation
+- Future-proof scheduling semantics
+
+UTC guarantees stability for **ABSOLUTE** time.
+
+Zone-based representation guarantees correctness for **SCHEDULED** time.
+
+---
+
+## References
+
+- [**ISO-8601**](https://en.wikipedia.org/wiki/ISO_8601) (Date)
+- [**RFC-3339**](https://www.rfc-editor.org/rfc/rfc3339.html#page-4) ((Z Form))
+- [**RFC-9557**](https://www.rfc-editor.org/rfc/rfc9557#name-internet-extended-date-time)
+- [**TZDB**](https://www.iana.org/time-zones)
+  - Current [**TZDB Explorer**](https://nodatime.org/TimeZones), with historic versions
+
+---
+
+## Version History
+
+| Version | Date       | Change                               |
+| ------- | ---------- | ------------------------------------ |
+| 2.0.0   | 2026-02-16 | Introduced scheduled timestamp model |
+| 1.1.0   | 2026-02-16 | Added fractional seconds             |
+| 1.0.0   | 2023-10-27 | Initial definition                   |

package/standards/integration/standards/data-formats/monetary-format.md

@@ -0,0 +1,61 @@
+---
+identifier: "INTG-STD-003"
+name: "Money and Currency"
+version: "1.0.0"
+status: "DRAFT"
+
+domain: "INTEGRATION"
+documentType: "standard"
+category: "format"
+appliesTo: ["api", "events", "a2a", "files", "mcp"]
+
+lastUpdated: "2026-02-17"
+owner: "Integration Architecture Board"
+
+standardsCompliance:
+  iso: ["ISO-4217"]
+  rfc: []
+  w3c: []
+  other: []
+
+taxonomy:
+  capability: "data-format"
+  subCapability: "monetary"
+  layer: "contract"
+
+enforcement:
+  method: "automated"
+  validationRules: {}
+  rejectionCriteria: []
+  supportedFormats: []
+  authoritativeModel: ""
+
+dependsOn: []
+supersedes: ""
+---
+
+# Money and Currency
+
+## Purpose
+
+## Conceptual Model
+
+## Rules
+
+## Examples
+
+## Allowed Representations
+
+## Validation Rules
+
+## Enforcement Rules
+
+## References
+
+## Rationale
+
+## Version History
+
+| Version | Date       | Change             |
+| ------- | ---------- | ------------------ |
+| 1.0.0   | 2026-02-17 | Initial definition |

package/standards/integration/standards/events/_category_.json

@@ -0,0 +1 @@
+{"label": "Events", "position": 4}