@clossys/writer 0.3.9 → 0.5.0

package/dist/generated/advisor-plan-contract.generated.js

@@ -0,0 +1,430 @@
+// AUTO-GENERATED by this package's build-time packer (issue #1586).
+// Do not edit by hand -- edits are overwritten on the next `npm run build`.
+// Source of truth: the shared Advisor plan contract in this package's source
+// repository (not shipped in this package). Every package that validates a
+// plan packs this same contract.
+/** The shared Advisor plan contract (advisor-plan.json) this package validates against. */
+export const ADVISOR_PLAN_CONTRACT = {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$id": "https://github.com/clossys/foundry/blob/main/docs/contracts/advisor-plan.json",
+    "title": "Advisor plan",
+    "description": "Issue #1175 and #1475: the plan record at clossys/advisor/plan.json that Advisor writes and renders into its STATUS document, that Launcher reads before it applies an approved plan, and that Writer reads when it resolves copy a delegate approved for production (issue #1586). packages/advisor/src/status.ts's AdvisorPlan type is the shape's owner; this file is the one definition @clossys/advisor, @clossys/launcher and @clossys/writer validate against (each package packs it at build time, so none depends on another). Every object is closed: a key this contract does not declare is refused, never ignored, because an unknown key is either a typo or a field some other reader would silently drop. A later field is added here first, in the same change as its reader. Every time is a real calendar time, asserted field by field through `format` (see definitions.dateTime and definitions.date), never by shape alone, so each one parses and can be ordered. The canonical plan digest, which an approval binds, is defined in docs/contracts/advisor-plan-digest.md; its fixture corpus is docs/contracts/advisor-plan-digest.fixture.json. CODE RULES (issue #1178). The keywords above cannot relate one field to another, so the rules below are defined here, once, and checked in code by each of those packages after the schema passes; a plan that breaks one is invalid exactly as a plan that breaks the schema is, and so has no digest. Their shared corpus is docs/contracts/advisor-plan-rules.fixture.json, and each of them is tested against every plan case in it. A refusal names the rule and the position of the field at fault (for example staffing[1].repository), never its value. R1: no two staffing entries name the same repository; repository ids compare case-insensitively, as the repository inventory compares them. R2: when staffing is present, every staffing[].roles entry is one of mandate.roles, and every mandate.roles entry that is not a hub-only role (definitions.hubOnlyRoles) appears in at least one staffing entry. R3: every packages[].repository is spelled exactly as some staffing[].repository. R4: no two packages share a planItem. R5: no two packages share both a repository (compared case-insensitively) and a name; when R1 and R3 both hold (staffing ids are distinct case-insensitively, and every package's repository is spelled exactly as one of them), the case-insensitive comparison changes nothing, and it keeps R5 true on its own when either does not. R6: resolution is present exactly when packages is present. R7: no two kits share an id. R8: no role appears twice in one staffing entry's roles. R9: no role appears twice in mandate.roles. R10: a repository has at most one pin-starter act (repositories compared case-insensitively), and a pin-starter act's placement is devDependencies. R11: no staffing[].roles entry is a hub-only role (definitions.hubOnlyRoles). A hub-only role may be in mandate.roles and works from the hub, but it is never staffed in a repository, so no package act installs its package there; Advisor's package resolution also refuses a staffed hub-only role (hub-only-package), but R11 refuses such a plan first, because resolution reads only a valid plan. So a plan whose mandate.roles are all hub-only roles does no work in any product repository: it has no staffing (an empty staffing is refused by minItems, and any entry would break R2 or R11), and so it has no packages. R12: every packages[].planItem is exactly that act's repository, a colon and its name, in the same letter case. So a planItem carries no plan text, and it is the key the repository change set (C16) and the installed-state ledger (L10) use. APPROVAL BINDING. An approval binds bytes only through decisions[].subjectDigest. The latest decision is found by `at` as described under `decisions`; it approves something only when it has chosen \"approved\" and carries a subjectDigest, and the subject it approves is that digest, which names the exact change the approver was shown. When several decisions share the latest instant, they approve only if every one of them has chosen \"approved\" with the same subjectDigest; when any decision time does not parse, nothing is approved. An approval with no subjectDigest binds nothing. FREEZE. From an approving decision until every repository it covers has been applied, or a new plan replaces it, Advisor changes no field the plan digest covers. Recording the approval appends a decision and may update asOf, and the digest excludes both, so the digest at approval equals the digest at apply. DELEGATED COPY APPROVAL (issue #1586). delegatedCopyApproval declares that copy a delegate approved is accepted on production. It grants that only through an approval that binds this plan: @clossys/writer accepts it only when the plan it is given validates (schema and code rules), declares delegatedCopyApproval, and has a latest decision, found as APPROVAL BINDING describes, that has chosen \"approved\" with a subjectDigest equal to this plan's own canonical digest. When scopes is present, only an entry whose id is inside one of those namespaces is covered. The digest covers delegatedCopyApproval, so adding it, removing it or changing its scopes after an approval leaves the plan unapproved for this purpose until a new approval names the new digest. An approval whose subjectDigest names anything other than this plan's digest, such as another plan or an apply bundle, grants nothing here.",
+    "type": "object",
+    "additionalProperties": false,
+    "required": [
+        "schemaVersion",
+        "asOf",
+        "mandate",
+        "whereWeAre",
+        "recommendedNext",
+        "decisions",
+        "blockers"
+    ],
+    "properties": {
+        "schemaVersion": {
+            "const": 1
+        },
+        "asOf": {
+            "$ref": "#/definitions/dateTime",
+            "description": "When this plan record was last written. Excluded from the canonical plan digest."
+        },
+        "mandate": {
+            "$ref": "#/definitions/mandate"
+        },
+        "whereWeAre": {
+            "type": "array",
+            "description": "A few plain-language status lines.",
+            "items": {
+                "$ref": "#/definitions/nonBlankString"
+            }
+        },
+        "recommendedNext": {
+            "description": "The one pending step for the whole plan, or null once nothing is pending.",
+            "oneOf": [
+                {
+                    "type": "null"
+                },
+                {
+                    "$ref": "#/definitions/recommendedNext"
+                }
+            ]
+        },
+        "decisions": {
+            "type": "array",
+            "description": "What was recommended, what was chosen, when, and by whom. The latest decision is the entry with the latest `at`, never the last one in the array; it approves the plan only when it has chosen \"approved\", and it binds an approval to bytes only through its subjectDigest (see APPROVAL BINDING in this contract's description). Append a decision; never rewrite an earlier one. Excluded from the canonical plan digest, because an approval is itself recorded here.",
+            "items": {
+                "$ref": "#/definitions/decision"
+            }
+        },
+        "blockers": {
+            "type": "array",
+            "items": {
+                "$ref": "#/definitions/blocker"
+            }
+        },
+        "kits": {
+            "type": "array",
+            "minItems": 1,
+            "description": "Optional. The kits Advisor recommends for this plan. Code rule R7.",
+            "items": {
+                "$ref": "#/definitions/kit"
+            }
+        },
+        "staffing": {
+            "type": "array",
+            "minItems": 1,
+            "description": "Optional. Which roles work in which repository: one entry per repository, named by its repository inventory id, never a URL or a path. Code rules R1, R2, R8 and R11.",
+            "items": {
+                "$ref": "#/definitions/staffingEntry"
+            }
+        },
+        "packages": {
+            "type": "array",
+            "minItems": 1,
+            "description": "Optional. The exact package acts this plan authorizes, each one version and one integrity value, never a range or a tag. Code rules R3, R4, R5, R6 and R10.",
+            "items": {
+                "$ref": "#/definitions/packageAct"
+            }
+        },
+        "resolution": {
+            "$ref": "#/definitions/resolution",
+            "description": "Optional. Where the exact versions in packages came from. Code rule R6."
+        },
+        "delegatedCopyApproval": {
+            "$ref": "#/definitions/delegatedCopyApproval",
+            "description": "Optional (issue #1586). Declares that copy a delegate approved is accepted on production, in every copy entry-id namespace or only in scopes. @clossys/writer reads it only through an approval that binds this plan: see DELEGATED COPY APPROVAL in this contract's description. The plan digest covers it, so FREEZE applies to it."
+        }
+    },
+    "definitions": {
+        "nonBlankString": {
+            "title": "a string with at least one non-whitespace character",
+            "type": "string",
+            "pattern": "\\S"
+        },
+        "dateTime": {
+            "title": "a real ISO 8601 date-time with a time zone, such as 2026-09-24T12:00:00Z",
+            "description": "format date-time, asserted field by field: YYYY-MM-DDThh:mm, optional :ss and fraction, then Z or +hh:mm/-hh:mm. Month 01-12; a day that exists in that month of that year (leap years included); hours 00-23; minutes and seconds 00-59 (no leap second); offset hours 00-23 and minutes 00-59; and Date.parse must give a finite time. So 2026-02-30, 2026-09-24T24:30:00Z and +24:00 are refused, and every accepted time can be ordered.",
+            "type": "string",
+            "format": "date-time"
+        },
+        "date": {
+            "title": "a real ISO 8601 date such as 2026-09-24",
+            "description": "format date, asserted field by field: YYYY-MM-DD with month 01-12 and a day that exists in that month of that year (leap years included), and a finite Date.parse.",
+            "type": "string",
+            "format": "date"
+        },
+        "dateOrDateTime": {
+            "title": "a real ISO 8601 date such as 2026-09-24, or a date-time with a time zone such as 2026-09-24T12:00:00Z",
+            "oneOf": [
+                {
+                    "$ref": "#/definitions/date"
+                },
+                {
+                    "$ref": "#/definitions/dateTime"
+                }
+            ]
+        },
+        "mandate": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+                "problem",
+                "primaryProblemId",
+                "roles"
+            ],
+            "properties": {
+                "problem": {
+                    "$ref": "#/definitions/nonBlankString",
+                    "description": "The client's problem, in their own words."
+                },
+                "primaryProblemId": {
+                    "$ref": "#/definitions/nonBlankString"
+                },
+                "roles": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/nonBlankString"
+                    }
+                }
+            }
+        },
+        "recommendedNext": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+                "action",
+                "owner"
+            ],
+            "properties": {
+                "action": {
+                    "$ref": "#/definitions/nonBlankString"
+                },
+                "owner": {
+                    "$ref": "#/definitions/nonBlankString"
+                },
+                "due": {
+                    "$ref": "#/definitions/dateOrDateTime",
+                    "description": "Optional."
+                }
+            }
+        },
+        "decision": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+                "at",
+                "recommended",
+                "chosen",
+                "by"
+            ],
+            "properties": {
+                "at": {
+                    "$ref": "#/definitions/dateTime"
+                },
+                "recommended": {
+                    "$ref": "#/definitions/nonBlankString"
+                },
+                "chosen": {
+                    "$ref": "#/definitions/nonBlankString"
+                },
+                "by": {
+                    "$ref": "#/definitions/nonBlankString"
+                },
+                "subjectDigest": {
+                    "$ref": "#/definitions/sha256Digest",
+                    "description": "Optional. On an approving decision, the digest of the exact change the approver was shown. An approval without it binds nothing (see APPROVAL BINDING in this contract's description)."
+                }
+            }
+        },
+        "sha256Digest": {
+            "title": "sha256: followed by 64 lowercase hexadecimal digits",
+            "type": "string",
+            "pattern": "^sha256:[0-9a-f]{64}$"
+        },
+        "sha512Integrity": {
+            "title": "one sha512 integrity value: sha512- followed by the canonical base64 of 64 bytes (88 characters ending in ==)",
+            "description": "Canonical base64 only: the last character before == carries two bits of data and four zero bits, so it is one of A, Q, g or w. Any other character there would decode to the same bytes as one of those, so a second spelling of one value is refused.",
+            "type": "string",
+            "pattern": "^sha512-[A-Za-z0-9+/]{85}[AQgw]==$"
+        },
+        "exactVersion": {
+            "title": "an exact release version such as 1.2.3, with no range, tag, prerelease or build suffix, and at most 16 digits in each part",
+            "description": "Each part is 0 or has no leading zero, and has at most 16 digits, the longest numeric part semver accepts.",
+            "type": "string",
+            "pattern": "^(0|[1-9][0-9]{0,15})\\.(0|[1-9][0-9]{0,15})\\.(0|[1-9][0-9]{0,15})$"
+        },
+        "repositoryId": {
+            "title": "a repository inventory id: a bare repository name, or owner/name",
+            "description": "The repository inventory's id rule (docs/contracts/repository-inventory.json) as one pattern: an optional GitHub owner (letters, digits and single inner hyphens, at most 39 characters) and a slash, then a repository name of letters, digits, '.', '_' and '-' that is not exactly '.' or '..'. No whitespace, no empty segment, at most one slash.",
+            "type": "string",
+            "pattern": "^(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?/)?(?!\\.\\.?$)[A-Za-z0-9._-]+$"
+        },
+        "packageName": {
+            "title": "a scoped package name in lowercase, such as @scope/name, of at most 214 characters",
+            "description": "npm's limit is 214 characters, asserted by the lookahead because the checker has no maxLength. Neither the scope nor the name may start with '.', '_' or '-'.",
+            "type": "string",
+            "pattern": "^(?=.{1,214}$)@[a-z0-9][a-z0-9._-]*/[a-z0-9][a-z0-9._-]*$"
+        },
+        "kit": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+                "id",
+                "source",
+                "verdict"
+            ],
+            "properties": {
+                "id": {
+                    "$ref": "#/definitions/nonBlankString",
+                    "description": "The kit's id: a curated preset's id, or the id Advisor gave a composed kit."
+                },
+                "source": {
+                    "enum": [
+                        "preset",
+                        "composed"
+                    ]
+                },
+                "verdict": {
+                    "enum": [
+                        "recommended"
+                    ],
+                    "description": "One value for now. A later verdict widens this list, and a reader that predates it refuses the new value rather than guessing its meaning."
+                }
+            }
+        },
+        "staffingEntry": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+                "repository",
+                "roles"
+            ],
+            "properties": {
+                "repository": {
+                    "$ref": "#/definitions/repositoryId"
+                },
+                "roles": {
+                    "type": "array",
+                    "minItems": 1,
+                    "description": "Role directories (short names) staffed in this repository, in the order the brief lists them.",
+                    "items": {
+                        "$ref": "#/definitions/nonBlankString"
+                    }
+                }
+            }
+        },
+        "hubOnlyRoles": {
+            "title": "the roles whose package lives in the engagement hub only",
+            "description": "Data, not a schema that any field uses: the list code rules R2 and R11 read, so that every package that validates a plan reads the one list. The apply-approved-plan RFC (issue #1178) places each role here in the hub: its package is pinned exactly once, in the hub, and a product repository runs its commands through npx at the hub's exact version, pinning nothing. Advisor is placed there by decision D24 and Integrator by decision D23; Launcher's hub skeleton and resume pin both Advisor and Integrator, exactly, in the hub's devDependencies. Such a role is never staffed in a repository (R11).",
+            "const": [
+                "advisor",
+                "integrator"
+            ]
+        },
+        "packageAct": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+                "planItem",
+                "repository",
+                "act",
+                "name",
+                "version",
+                "integrity",
+                "placement"
+            ],
+            "properties": {
+                "planItem": {
+                    "$ref": "#/definitions/nonBlankString",
+                    "description": "The act's repository, a colon and its name, exactly (R12); unique in the plan (R4)."
+                },
+                "repository": {
+                    "$ref": "#/definitions/repositoryId",
+                    "description": "One of staffing[].repository, spelled exactly the same (R3)."
+                },
+                "act": {
+                    "enum": [
+                        "install",
+                        "pin-starter"
+                    ],
+                    "description": "install adds a role's package; pin-starter pins the package that checks this repository's pull requests, at most once per repository and always as a devDependency (R10). A later act widens this list, and a reader that predates it refuses the new value."
+                },
+                "name": {
+                    "$ref": "#/definitions/packageName"
+                },
+                "version": {
+                    "$ref": "#/definitions/exactVersion"
+                },
+                "integrity": {
+                    "$ref": "#/definitions/sha512Integrity"
+                },
+                "placement": {
+                    "enum": [
+                        "dependencies",
+                        "devDependencies"
+                    ]
+                }
+            }
+        },
+        "resolution": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+                "snapshotDigest"
+            ],
+            "properties": {
+                "snapshotDigest": {
+                    "$ref": "#/definitions/sha256Digest",
+                    "description": "The digest of the registry snapshot the exact versions and integrity values in packages were read from."
+                }
+            }
+        },
+        "delegatedCopyApproval": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+                "target"
+            ],
+            "properties": {
+                "target": {
+                    "enum": [
+                        "production"
+                    ],
+                    "description": "The resolution target on which a delegate's approval is accepted. One value for now: a delegate's approval already resolves on preview with no declaration. A later target widens this list, and a reader that predates it refuses the new value rather than guessing its meaning."
+                },
+                "scopes": {
+                    "type": "array",
+                    "minItems": 1,
+                    "description": "Optional. The copy entry-id namespaces this declaration covers: an entry is covered when its id equals an item or starts with the item and a dot, so site.home covers site.home and site.home.title but not site.homepage.title. Absent, it covers every entry. An empty list is refused (omit the member instead). A repeated item is redundant, not refused.",
+                    "items": {
+                        "$ref": "#/definitions/copyDelegateScope"
+                    }
+                }
+            }
+        },
+        "copyDelegateScope": {
+            "title": "a copy entry-id namespace such as home or site.home: dot-separated segments of lowercase letters and digits with single inner hyphens, and no wildcard",
+            "description": "The same rule as @clossys/writer's delegate scope item: one or more segments separated by single dots, each one or more lowercase ASCII letters or digits, with single hyphens only between them.",
+            "type": "string",
+            "pattern": "^[a-z0-9]+(-[a-z0-9]+)*(\\.[a-z0-9]+(-[a-z0-9]+)*)*$"
+        },
+        "blockerKind": {
+            "description": "The five blocker kinds of the Controller loop record (docs/contracts/loop.json), in their fixed order.",
+            "enum": [
+                "missing-input",
+                "missing-authority",
+                "failing-evidence",
+                "unavailable-environment",
+                "contradiction"
+            ]
+        },
+        "blocker": {
+            "type": "object",
+            "description": "One capability at rest with exactly one next action. Field for field the same shape as the Controller loop record's Blocker.",
+            "additionalProperties": false,
+            "required": [
+                "capabilityId",
+                "kind",
+                "owner",
+                "nextAction",
+                "since"
+            ],
+            "properties": {
+                "capabilityId": {
+                    "$ref": "#/definitions/nonBlankString"
+                },
+                "kind": {
+                    "$ref": "#/definitions/blockerKind"
+                },
+                "owner": {
+                    "$ref": "#/definitions/nonBlankString"
+                },
+                "nextAction": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": [
+                        "who",
+                        "how",
+                        "byWhen"
+                    ],
+                    "properties": {
+                        "who": {
+                            "$ref": "#/definitions/nonBlankString"
+                        },
+                        "how": {
+                            "$ref": "#/definitions/nonBlankString"
+                        },
+                        "byWhen": {
+                            "$ref": "#/definitions/dateOrDateTime"
+                        }
+                    }
+                },
+                "since": {
+                    "$ref": "#/definitions/dateTime",
+                    "description": "When the blocker was recorded."
+                }
+            }
+        }
+    }
+};
+//# sourceMappingURL=advisor-plan-contract.generated.js.map

package/dist/generated/advisor-plan-contract.generated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"advisor-plan-contract.generated.js","sourceRoot":"","sources":["../../src/generated/advisor-plan-contract.generated.ts"],"names":[],"mappings":"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"}

package/dist/generated/contract-schema.generated.d.ts

@@ -0,0 +1,97 @@
+/**
+ * A minimal JSON Schema (draft-07) checker for this repository's shared
+ * contracts (issue #1475): the plan record and the engagement brief, which
+ * two packages validate against without either depending on the other.
+ *
+ * It implements exactly the keywords those contracts use, and throws on any
+ * other keyword, or keyword form, it meets instead of half-checking it.
+ * `assertImplementedContract()` walks a whole contract, so a test can prove
+ * every subschema is implemented, visited by a value or not. Property
+ * lookups use Object.hasOwn, so an inherited name (toString, constructor,
+ * __proto__) is never mistaken for a declared or present property.
+ *
+ * Messages, paths and errors never echo text from the document under test
+ * -- neither a value nor a key. A brief can carry founder text, a refusal
+ * can end up in a log, and these messages are read by agents: a hostile
+ * document can put prompt-injection text in a key name as easily as in a
+ * value. A path names only fields the contract declares (schema text, not
+ * document text) and array indices. A field the contract does not declare,
+ * or a repeated key, is reported at the object that holds it, by the key's
+ * 1-based position in that object ("key 3 of this object"), never by name.
+ *
+ * Every string, and every object key, must be well-formed Unicode: a lone
+ * surrogate is refused whatever the contract says, because it has no UTF-8
+ * encoding and so no canonical form. A document this checker accepts can
+ * always be digested.
+ *
+ * `readContractDocument()` is the one way to turn a plan or brief FILE into
+ * a value: it refuses bytes that are not valid UTF-8 and any object that
+ * repeats a key, at any depth. `JSON.parse` alone would silently keep the
+ * last of two duplicate keys, so a reviewer reading the file could see a
+ * value that is not the one validated and digested.
+ *
+ * This file imports nothing. It is the one implementation: a package that
+ * cannot import it carries a generated, byte-identical copy.
+ */
+export type ContractSchema = Readonly<Record<string, unknown>>;
+/**
+ * One place a value breaks its contract. `path` is `""` for the document
+ * itself, else like `blockers[0].nextAction.who`: only names the contract
+ * declares, and array indices. Neither `path` nor `message` ever carries
+ * document text.
+ */
+export interface ContractViolation {
+    readonly path: string;
+    readonly message: string;
+}
+/** Resolves a file-level `$ref` (for example `engagement-context.json`) to that contract. Throws when it cannot. */
+export type ContractLoader = (name: string) => ContractSchema;
+/** Walks every subschema of `schema`, visited by a value or not, and throws on the first keyword this checker does not implement. */
+export declare function assertImplementedContract(schema: ContractSchema, at?: string): void;
+/**
+ * Every violation of `value` against `contract`; empty when it conforms. A
+ * type mismatch stops there and returns alone, since every other keyword
+ * assumes the value is already the right type. Otherwise, on an object, any
+ * `const` or `enum` violation of the object itself comes before a missing
+ * required field, which comes before each present key's violations in the
+ * order the keys were written (see `keyOrder()`), then any from `oneOf`,
+ * `allOf` and `not`. Never throws for a bad value. Throws only when the
+ * contract itself uses a keyword this checker does not implement, or a
+ * `$ref` it cannot resolve -- a defect in the contract, not in the value.
+ */
+export declare function validateAgainstContract(contract: ContractSchema, value: unknown, load: ContractLoader): ContractViolation[];
+/** `label.path message` (for example `plan.blockers[0].capabilityId is required`), or `label message` for the document itself. */
+export declare function formatContractViolation(label: string, violation: ContractViolation): string;
+/**
+ * Why `readContractDocument()` refused a file, as data a caller can act on
+ * without parsing the message: `reason` says which rule failed, and
+ * `position` (never file text) is set only for a syntax error or a leading
+ * byte order mark. The message carries no file text either: a repeated key
+ * is named by its 1-based position in its object, and that object as the
+ * top-level object or by its position, never by any key.
+ *
+ * A position, here and in every message, is a 0-based index into the
+ * decoded text in UTF-16 code units: JavaScript's string index. It equals
+ * the byte offset only for ASCII text; a character outside the Basic
+ * Multilingual Plane (an emoji, say) counts as two.
+ */
+export declare class ContractDocumentError extends Error {
+    readonly reason: "encoding" | "syntax" | "repeated-key";
+    readonly position?: number | undefined;
+    constructor(message: string, reason: "encoding" | "syntax" | "repeated-key", position?: number | undefined);
+}
+/**
+ * Reads a plan or brief file's bytes as strict JSON: UTF-8 that decodes
+ * without error (never silently replaced with U+FFFD) and does not start
+ * with a byte order mark, exactly one JSON value, and no object that repeats a key at any depth -- the I-JSON rules
+ * RFC 8785 canonicalization assumes. Refuses bytes that break a rule with a
+ * ContractDocumentError whose message says which rule, by position only: a
+ * syntax error by its position (a UTF-16 code-unit index, see
+ * ContractDocumentError), a repeated key by its 1-based position in its
+ * object and that object's position (or "the top-level object") -- never
+ * any text from the file. It does not validate the value against a contract; call
+ * `validateAgainstContract()` next, which then numbers an undeclared field
+ * by its position as written in the file.
+ */
+export declare function readContractDocument(bytes: Uint8Array): unknown;
+//# sourceMappingURL=contract-schema.generated.d.ts.map

package/dist/generated/contract-schema.generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-schema.generated.d.ts","sourceRoot":"","sources":["../../src/generated/contract-schema.generated.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,oHAAoH;AACpH,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,cAAc,CAAC;AAkE9D,qIAAqI;AACrI,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,cAAc,EAAE,EAAE,SAAM,GAAG,IAAI,CAShF;AA+LD;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,cAAc,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,cAAc,GAAG,iBAAiB,EAAE,CAE3H;AAED,kIAAkI;AAClI,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,iBAAiB,GAAG,MAAM,CAG3F;AAQD;;;;;;;;;;;;GAYG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAG5C,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,QAAQ,GAAG,cAAc;IACvD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM;gBAF1B,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,UAAU,GAAG,QAAQ,GAAG,cAAc,EAC9C,QAAQ,CAAC,EAAE,MAAM,YAAA;CAI7B;AA2HD;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAY/D"}