{ "$schema": "https://flow.jig.md/schemas/channel-contract-0.schema.json", "id": "https://jig.md/contracts/reporting", "version": "0.1.0", "semantics": "Reporting carries optional application observations over an ordinary FLOW channel. Messages are closed JSON/0 objects. All strings contain Unicode scalar values. A canonical encoded item is at most 32768 UTF-8 bytes. notice text has 1–4096 scalars and is one complete attributed message, with newlines allowed; it appends to the transcript and is not a fragment. Optional notice severity is info, warning or error; absent means info. It classifies author-reported importance, never host-attested failure, blocking state, retry or cancellation authority. Severity does not change ordering, quotas, pacing or optional delivery. Report known blocking failures promptly and retain essential reasons in application results or artifacts independently of observation. activity id has 1–64 scalars and label has 1–256; a progress unit has 1–32. Labels and units contain no CR, LF, U+2028 or U+2029. IDs are opaque presentation slots, not durable tasks, native paths or host-attested provenance. An activity fully replaces label and optional progress for (connected source instance,id); omission removes previous progress. Replacement retains first-appearance order. clear removes that slot idempotently; unknown IDs do nothing and later reuse creates a new appearance. Retirement removes only that source's slots, without restoring old snapshots or undoing work. Validated complete notices already accepted by a bounded presenter retain its ownership and order through ordinary source retirement, subject to output failure, quota and cancellation. Printed notices cannot be retracted. Only consecutive unsent tail replacements of the same activity or view may coalesce; notices, clears and retirements are ordering barriers. Transport sequence establishes accepted order, not an application revision counter. completed and total are safe nonnegative integers through 9007199254740991; completed must not exceed total when present. Zero total requires zero completed and means a count without a percentage; omitted total also means a count only. Later snapshots may decrease counts, change totals or units, or omit progress. Never round an incomplete count to 100%. Counts, exact 100%, clear and EOF are observations, never execution success. No monotonicity, rate, ETA, hierarchy, replay, acknowledgement or completeness guarantee is provided. EOF ends the selected sequence; it does not establish complete upstream history or domain success. Every source ending retires its activities. Host cancellation/stopping/cleanup/terminal state takes precedence over application observation; late callbacks cannot restore retired state. Shared budgets may stop healthy contributors; isolated retirement is not commutativity, fairness, independent transcript or outcome invariance. Absent or lost observation does not restart, retry or rebind domain work. Parents deliberately validate and relay separate child channels, own receiver disposal, map each bounded child occurrence to fresh collision-free outgoing IDs, fence producers before ordered clears, and settle pending relay work before ID reuse. ACP fragments and plans retain their separate contract and cannot be silently reinterpreted as these complete notices or counts. Output delivery may fail independently of application results; important outcome evidence also belongs in application results or artifacts. Views are whole atomic replacements scoped to the actual publishing invocation and local ID. A view fixes its landing hint and own-call operationId until retirement. IDs are never reused in a publisher lifetime, including unknown retired IDs. Source EOF removes activities but freezes views with observation-ended context; abnormal endings mark them incomplete. View retirement removes that view only. Retained domain statuses are application data, never host execution evidence. References resolve dynamically only in the actual publisher namespace: records in current retained views, original caller-local IDs of its actual calls, and declared output attachment paths admitted into verified delivered-file evidence. Unavailable targets remain explicit; no references confer authority. Output previews use immutable authenticated capture, never reopen mutable destination files. Every row has exactly the declared column keys and matching non-null cell types. Collections have unique IDs per view, unique column keys and row IDs; counts may only describe supplied records or a reported total. Limits: 8 sections, 32 total blocks including row details, 128 rows, 8 columns per collection, 1024 cells, 8 non-collection detail blocks per row, 32 facts per block, 8 references per report. View, collection, row IDs and keys are 1–64 scalars; titles and labels 1–128; summary 1–1024; report/text values 0–4096; units 1–32. IDs, titles, labels, keys and units contain no line separators. Operation IDs use 1–128 ASCII characters matching [A-Za-z0-9][A-Za-z0-9._:/-]*. Artifact attachment names use 1–64 lowercase letters, digits and separated hyphens. Relative paths use at most 512 UTF-8 bytes and 16 nonempty slash-separated segments without dot, dot-dot, backslash, controls or protected .jig segments. Progress and collection counts are safe nonnegative integers; completed never exceeds total and collection total never undercounts supplied rows. Per source: 16 lifetime view IDs and 8 retained views /128 KiB; per command: 64 lifetime IDs and 32 retained views /512 KiB. Only consecutive unsent tail replacements of the same view or activity may coalesce; notices, clears, retirements and in-flight sends are barriers. There is no executable content, arbitrary layout, domain ontology, overall percentage, inferred ETA, durable UI history or execution-changing action in this read-only agreement. Known blocking causes must also be offered as notices and retained in final evidence independently. The scoped publisher retains at most 16 items including the in-flight item /256 KiB, serializes sends with at least 200 ms between starts, and uses a 500 ms per-send wait and 4000 ms aggregate best-effort drain allowance starting at body exit. The drain adds no delay when already drained or unwired. These budgets stop publication and initiate abnormal close, not cancel original sends. Original send and close settlement remain owned and joined and may exceed these allowances. Four seconds accommodates a full backlog with prompt acknowledgements, not every individually sub-500 ms send pattern. Cancellation and the root deadline remain authoritative and are never extended; the deadline may expire during final observation drain.", "item": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "notice" }, "text": { "type": "string", "minLength": 1, "maxLength": 4096 }, "severity": { "enum": ["info", "warning", "error"] } }, "required": ["kind", "text"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "activity" }, "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "label": { "type": "string", "minLength": 1, "maxLength": 256 }, "progress": { "type": "object", "properties": { "completed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "unit": { "type": "string", "minLength": 1, "maxLength": 32 } }, "required": ["completed"], "additionalProperties": false }, "detail": { "type": "string", "minLength": 1, "maxLength": 4096 }, "operationId": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": ["kind", "id", "label"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "clear" }, "id": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": ["kind", "id"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "view" }, "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "title": { "type": "string", "minLength": 1, "maxLength": 128 }, "summary": { "type": "string", "minLength": 1, "maxLength": 1024 }, "landing": { "const": true }, "operationId": { "type": "string", "minLength": 1, "maxLength": 128 }, "sections": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 128 }, "blocks": { "type": "array", "items": { "$ref": "#/$defs/block" }, "maxItems": 32 } }, "required": ["blocks"], "additionalProperties": false }, "maxItems": 8 } }, "required": ["kind", "id", "title", "summary", "sections"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "retire-view" }, "id": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": ["kind", "id"], "additionalProperties": false } ] }, "$defs": { "reference": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "record" }, "viewId": { "type": "string", "minLength": 1, "maxLength": 64 }, "collectionId": { "type": "string", "minLength": 1, "maxLength": 64 }, "rowId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": ["kind", "viewId", "collectionId", "rowId"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "call" }, "operationId": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": ["kind", "operationId"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "artifact" }, "attachment": { "type": "string", "minLength": 1, "maxLength": 64 }, "path": { "type": "string", "minLength": 1, "maxLength": 512 } }, "required": ["kind", "attachment", "path"], "additionalProperties": false } ] }, "value": { "oneOf": [ { "type": "string", "minLength": 0, "maxLength": 4096 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "$ref": "#/$defs/reference" } ] }, "detail": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "report" }, "text": { "type": "string", "minLength": 0, "maxLength": 4096 }, "references": { "type": "array", "items": { "$ref": "#/$defs/reference" }, "maxItems": 8 } }, "required": ["kind", "text"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "facts" }, "items": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 128 }, "value": { "$ref": "#/$defs/value" } }, "required": ["label", "value"], "additionalProperties": false }, "maxItems": 32 } }, "required": ["kind", "items"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "progress" }, "label": { "type": "string", "minLength": 1, "maxLength": 128 }, "completed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "unit": { "type": "string", "minLength": 1, "maxLength": 32 } }, "required": ["kind", "label", "completed"], "additionalProperties": false } ] }, "block": { "oneOf": [ { "$ref": "#/$defs/detail" }, { "type": "object", "properties": { "kind": { "const": "collection" }, "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "title": { "type": "string", "minLength": 1, "maxLength": 128 }, "columns": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64 }, "label": { "type": "string", "minLength": 1, "maxLength": 128 }, "type": { "enum": ["text", "number", "boolean", "reference"] } }, "required": ["key", "label", "type"], "additionalProperties": false }, "maxItems": 8, "minItems": 1 }, "rows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "cells": { "type": "object", "additionalProperties": { "$ref": "#/$defs/value" } }, "details": { "type": "array", "items": { "$ref": "#/$defs/detail" }, "maxItems": 8 } }, "required": ["id", "cells"], "additionalProperties": false }, "maxItems": 128 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["kind", "id", "title", "columns", "rows"], "additionalProperties": false } ] } } }