@ggui-ai/protocol 0.1.0-rc.1

package/dist/validation/cross-references.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Cross-reference invariants for `DataContract`. Validates that every
+ * intra-contract pointer resolves to a declared catalog entry on the
+ * SAME contract — i.e., the contract is internally consistent.
+ *
+ * The protocol exposes two such pointers:
+ *
+ *   - `actionSpec[*].nextStep`     → `agentCapabilities.tools[*]` key
+ *   - `streamSpec[*].source.tool`  → `agentCapabilities.tools[*]` key
+ *
+ * These are pure in-contract checks. A contract that declares
+ * `nextStep: 'archive_email'` MUST also declare `archive_email` in its
+ * own `agentCapabilities.tools` catalog — same-MCP and cross-MCP both
+ * funnel through this single resolution path (the catalog is the
+ * declarative source of truth for every referenced tool). Violations
+ * are author-recoverable at push time.
+ */
+import type { DataContract, ActionSpec, StreamSpec, AgentCapabilitiesSpec } from '../types/data-contract';
+import type { ContractViolation } from './contract-validator';
+/**
+ * Stable error code emitted when an `actionSpec[*].nextStep` value
+ * does not resolve to a declared `agentCapabilities.tools[*]` key on
+ * the same contract.
+ *
+ * Intended for downstream consumers that switch on the code rather
+ * than pattern-matching message strings.
+ */
+export declare const CTR_REF_NEXT_STEP = "CTR_REF_NEXT_STEP";
+/**
+ * Stable error code emitted when a `streamSpec[*].source.tool` value
+ * does not resolve to a declared `agentCapabilities.tools[*]` key on
+ * the same contract.
+ *
+ * Intended for downstream consumers that switch on the code rather
+ * than pattern-matching message strings. Mentioned by name in
+ * `packages/protocol/src/types/data-contract.ts` (StreamChannelEntry
+ * docstring) — keep in sync.
+ */
+export declare const CTR_REF_STREAM_SOURCE = "CTR_REF_STREAM_SOURCE";
+/**
+ * Cross-reference violation — adds a stable `code` field on top of
+ * `ContractViolation`. Lives here rather than on the base type so
+ * existing structural violations stay code-less; cross-ref violations
+ * are designed to be machine-discriminated.
+ */
+export interface CrossReferenceViolation extends ContractViolation {
+    code: typeof CTR_REF_NEXT_STEP | typeof CTR_REF_STREAM_SOURCE;
+}
+/**
+ * Validate every `actionSpec[*].nextStep` resolves to a declared
+ * `agentCapabilities.tools[*]` key on the same contract. Entries
+ * without a `nextStep` are skipped (they're pure event signals — the
+ * agent decides unconstrained by author intent).
+ *
+ * When `agentCapabilities` is undefined but a `nextStep` is declared,
+ * the reference still doesn't resolve — a violation surfaces. Authors
+ * can fix by adding the referenced tool to `agentCapabilities.tools`
+ * or by dropping the `nextStep` hint (no-hint action remains valid).
+ */
+export declare function checkActionNextStepRefs(actionSpec: ActionSpec | undefined, agentCapabilities: AgentCapabilitiesSpec | undefined): CrossReferenceViolation[];
+/**
+ * Validate every `streamSpec[*].source.tool` resolves to a declared
+ * `agentCapabilities.tools[*]` key on the same contract. Channels
+ * without a `source` declaration are skipped (they're agent-written by
+ * some other mechanism, or server-owned reserved channels).
+ *
+ * When `agentCapabilities` is undefined but a `source.tool` is
+ * declared, the reference still doesn't resolve — a violation
+ * surfaces. Authors fix by adding the referenced tool to
+ * `agentCapabilities.tools` or by dropping `source` (channel becomes
+ * agent-written rather than tool-sourced).
+ */
+export declare function checkStreamSourceRefs(streamSpec: StreamSpec | undefined, agentCapabilities: AgentCapabilitiesSpec | undefined): CrossReferenceViolation[];
+/**
+ * Run every cross-reference invariant. Returns the aggregated
+ * violation list — order is stable: `nextStep` invariants first,
+ * `stream.source` invariants second.
+ *
+ * Pure check; doesn't throw. Callers that want fail-fast semantics
+ * use {@link assertCrossReferences}.
+ */
+export declare function checkCrossReferences(contract: DataContract): CrossReferenceViolation[];
+/**
+ * Throwable form of {@link checkCrossReferences}. Use at protocol
+ * boundaries where an unresolved cross-reference is a contract bug
+ * the caller must fix (push handler, blueprint registration).
+ *
+ * Carries the full violation list so error renderers can show every
+ * dangling reference in one pass instead of fix-and-retry per-field.
+ */
+export declare class CrossReferenceError extends Error {
+    readonly code: "cross_reference_unresolved";
+    readonly violations: readonly CrossReferenceViolation[];
+    constructor(violations: readonly CrossReferenceViolation[]);
+}
+/**
+ * Throw-on-violation wrapper around {@link checkCrossReferences}.
+ * No-op when the contract is internally consistent.
+ *
+ * Invoked at handshake AND push time: contract-internal mistakes
+ * surface at the earliest possible boundary so the agent can fix and
+ * retry on the SAME handshakeId.
+ */
+export declare function assertCrossReferences(contract: DataContract): void;
+//# sourceMappingURL=cross-references.d.ts.map

package/dist/validation/cross-references.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-references.d.ts","sourceRoot":"","sources":["../../src/validation/cross-references.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC1G,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AAErD;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAE7D;;;;;GAKG;AACH,MAAM,WAAW,uBAAwB,SAAQ,iBAAiB;IAChE,IAAI,EAAE,OAAO,iBAAiB,GAAG,OAAO,qBAAqB,CAAC;CAC/D;AAOD;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,UAAU,GAAG,SAAS,EAClC,iBAAiB,EAAE,qBAAqB,GAAG,SAAS,GACnD,uBAAuB,EAAE,CAsB3B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,UAAU,GAAG,SAAS,EAClC,iBAAiB,EAAE,qBAAqB,GAAG,SAAS,GACnD,uBAAuB,EAAE,CAwB3B;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,YAAY,GACrB,uBAAuB,EAAE,CAK3B;AAED;;;;;;;GAOG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,EAAG,4BAA4B,CAAU;IACtD,QAAQ,CAAC,UAAU,EAAE,SAAS,uBAAuB,EAAE,CAAC;gBAE5C,UAAU,EAAE,SAAS,uBAAuB,EAAE;CAQ3D;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAKlE"}

package/dist/validation/cross-references.js

@@ -0,0 +1,164 @@
+/**
+ * Cross-reference invariants for `DataContract`. Validates that every
+ * intra-contract pointer resolves to a declared catalog entry on the
+ * SAME contract — i.e., the contract is internally consistent.
+ *
+ * The protocol exposes two such pointers:
+ *
+ *   - `actionSpec[*].nextStep`     → `agentCapabilities.tools[*]` key
+ *   - `streamSpec[*].source.tool`  → `agentCapabilities.tools[*]` key
+ *
+ * These are pure in-contract checks. A contract that declares
+ * `nextStep: 'archive_email'` MUST also declare `archive_email` in its
+ * own `agentCapabilities.tools` catalog — same-MCP and cross-MCP both
+ * funnel through this single resolution path (the catalog is the
+ * declarative source of truth for every referenced tool). Violations
+ * are author-recoverable at push time.
+ */
+/**
+ * Stable error code emitted when an `actionSpec[*].nextStep` value
+ * does not resolve to a declared `agentCapabilities.tools[*]` key on
+ * the same contract.
+ *
+ * Intended for downstream consumers that switch on the code rather
+ * than pattern-matching message strings.
+ */
+export const CTR_REF_NEXT_STEP = 'CTR_REF_NEXT_STEP';
+/**
+ * Stable error code emitted when a `streamSpec[*].source.tool` value
+ * does not resolve to a declared `agentCapabilities.tools[*]` key on
+ * the same contract.
+ *
+ * Intended for downstream consumers that switch on the code rather
+ * than pattern-matching message strings. Mentioned by name in
+ * `packages/protocol/src/types/data-contract.ts` (StreamChannelEntry
+ * docstring) — keep in sync.
+ */
+export const CTR_REF_STREAM_SOURCE = 'CTR_REF_STREAM_SOURCE';
+function agentToolKeys(spec) {
+    if (!spec)
+        return [];
+    return Object.keys(spec.tools);
+}
+/**
+ * Validate every `actionSpec[*].nextStep` resolves to a declared
+ * `agentCapabilities.tools[*]` key on the same contract. Entries
+ * without a `nextStep` are skipped (they're pure event signals — the
+ * agent decides unconstrained by author intent).
+ *
+ * When `agentCapabilities` is undefined but a `nextStep` is declared,
+ * the reference still doesn't resolve — a violation surfaces. Authors
+ * can fix by adding the referenced tool to `agentCapabilities.tools`
+ * or by dropping the `nextStep` hint (no-hint action remains valid).
+ */
+export function checkActionNextStepRefs(actionSpec, agentCapabilities) {
+    if (!actionSpec)
+        return [];
+    const violations = [];
+    const knownTools = agentToolKeys(agentCapabilities);
+    for (const [actionName, entry] of Object.entries(actionSpec)) {
+        if (entry === null || typeof entry !== 'object')
+            continue;
+        const nextStep = entry.nextStep;
+        if (nextStep === undefined)
+            continue;
+        if (knownTools.includes(nextStep))
+            continue;
+        const known = knownTools.length > 0 ? knownTools.join(', ') : '(none)';
+        violations.push({
+            code: CTR_REF_NEXT_STEP,
+            field: `actionSpec.${actionName}.nextStep`,
+            message: `actionSpec.${actionName}.nextStep references '${nextStep}', which is not declared in agentCapabilities.tools. Declared: ${known}.`,
+            expected: knownTools.join(' | ') || '(declare in agentCapabilities.tools)',
+            received: nextStep,
+        });
+    }
+    return violations;
+}
+/**
+ * Validate every `streamSpec[*].source.tool` resolves to a declared
+ * `agentCapabilities.tools[*]` key on the same contract. Channels
+ * without a `source` declaration are skipped (they're agent-written by
+ * some other mechanism, or server-owned reserved channels).
+ *
+ * When `agentCapabilities` is undefined but a `source.tool` is
+ * declared, the reference still doesn't resolve — a violation
+ * surfaces. Authors fix by adding the referenced tool to
+ * `agentCapabilities.tools` or by dropping `source` (channel becomes
+ * agent-written rather than tool-sourced).
+ */
+export function checkStreamSourceRefs(streamSpec, agentCapabilities) {
+    if (!streamSpec)
+        return [];
+    const violations = [];
+    const knownTools = agentToolKeys(agentCapabilities);
+    for (const [channelName, entry] of Object.entries(streamSpec)) {
+        if (entry === null || typeof entry !== 'object')
+            continue;
+        const source = entry.source;
+        if (!source)
+            continue;
+        const toolName = source.tool;
+        if (typeof toolName !== 'string' || toolName.length === 0)
+            continue;
+        if (knownTools.includes(toolName))
+            continue;
+        const known = knownTools.length > 0 ? knownTools.join(', ') : '(none)';
+        violations.push({
+            code: CTR_REF_STREAM_SOURCE,
+            field: `streamSpec.${channelName}.source.tool`,
+            message: `streamSpec.${channelName}.source.tool references '${toolName}', which is not declared in agentCapabilities.tools. Declared: ${known}.`,
+            expected: knownTools.join(' | ') || '(declare in agentCapabilities.tools)',
+            received: toolName,
+        });
+    }
+    return violations;
+}
+/**
+ * Run every cross-reference invariant. Returns the aggregated
+ * violation list — order is stable: `nextStep` invariants first,
+ * `stream.source` invariants second.
+ *
+ * Pure check; doesn't throw. Callers that want fail-fast semantics
+ * use {@link assertCrossReferences}.
+ */
+export function checkCrossReferences(contract) {
+    return [
+        ...checkActionNextStepRefs(contract.actionSpec, contract.agentCapabilities),
+        ...checkStreamSourceRefs(contract.streamSpec, contract.agentCapabilities),
+    ];
+}
+/**
+ * Throwable form of {@link checkCrossReferences}. Use at protocol
+ * boundaries where an unresolved cross-reference is a contract bug
+ * the caller must fix (push handler, blueprint registration).
+ *
+ * Carries the full violation list so error renderers can show every
+ * dangling reference in one pass instead of fix-and-retry per-field.
+ */
+export class CrossReferenceError extends Error {
+    code = 'cross_reference_unresolved';
+    violations;
+    constructor(violations) {
+        const summary = violations
+            .map((v) => `[${v.code}] ${v.message}`)
+            .join(' | ');
+        super(`Contract cross-reference invariants failed: ${summary}`);
+        this.name = 'CrossReferenceError';
+        this.violations = violations;
+    }
+}
+/**
+ * Throw-on-violation wrapper around {@link checkCrossReferences}.
+ * No-op when the contract is internally consistent.
+ *
+ * Invoked at handshake AND push time: contract-internal mistakes
+ * surface at the earliest possible boundary so the agent can fix and
+ * retry on the SAME handshakeId.
+ */
+export function assertCrossReferences(contract) {
+    const violations = checkCrossReferences(contract);
+    if (violations.length > 0) {
+        throw new CrossReferenceError(violations);
+    }
+}

package/dist/validation/hygiene-rules.d.ts

@@ -0,0 +1,250 @@
+/**
+ * Authoring-hygiene rules for `DataContract`. Lint rule registry —
+ * warnings only, never thrown by {@link validateContract}; surfaced
+ * by {@link lintContract} so authoring tools can offer "your contract
+ * is technically valid, but here are the polish items" feedback.
+ *
+ * Ships the most universally applicable subset:
+ *
+ *   - `LINT_ORPHAN_AGENT_TOOL` — `agentCapabilities.tools[X]` is
+ *     declared but never referenced from any `actionSpec[*].nextStep`
+ *     or `streamSpec[*].source.tool`. The entry is dead weight — either
+ *     wire it up or drop it. (Catches the common "agent dropped a
+ *     reference but left the catalog entry behind" drift.)
+ *
+ *   - `LINT_MISSING_USAGE` — `agentCapabilities.tools[*]` or
+ *     `clientCapabilities.gadgets[*]` lacks a `usage` field.
+ *     `usage` is the free-form LLM-targeted prose that bare
+ *     `description` lacks — when omitted, the agent's reasoning
+ *     loop loses important context-of-use information.
+ *
+ *   - `LINT_MISSING_EXAMPLE` — `agentCapabilities.tools[*]` lacks an
+ *     `example`. Examples ground the agent's invocation patterns; a
+ *     tool without one is harder to use correctly on the first call.
+ *
+ *   - `LINT_GADGET_DUPLICATE_EXPORT` — two `clientCapabilities.gadgets[*]`
+ *     entries declare the same export name (a `hook` name or a
+ *     `component` name). The boilerplate generator emits one import
+ *     per export name; a collision is unresolvable in module scope.
+ *     Keyed on the export name alone.
+ *
+ * Gadget lints split by timing into two surfaces:
+ *
+ *   - **Wire-side** ({@link checkHygiene}, input `DataContract`):
+ *     `checkGadgetHookNames` + `checkDuplicateGadgetHooks`.
+ *   - **Registry-side** ({@link lintGadgetCatalog}, input
+ *     `readonly GadgetDescriptor[]`): permission + immutability +
+ *     duplicate-hook + unscoped-package checks, run at registration
+ *     time. Some codes are fatal — see {@link FATAL_CATALOG_LINT_CODES}.
+ *
+ * Pure checks; return violations rather than throwing. The wire-side
+ * set is wired into `lintContract` via `phaseHygiene`; consumers that
+ * want strict gates layer their own assertions on top.
+ */
+import type { DataContract, GadgetDescriptor } from '../types/data-contract';
+/**
+ * Stable codes for hygiene rules. Each is a `LINT_*` rather than a
+ * `CTR_*` — the convention: errors are `CTR_*`, warnings are `LINT_*`.
+ *
+ * The gadget lints split into two timing buckets:
+ *
+ *   - **Wire-side** (run on a `DataContract` by {@link checkHygiene}):
+ *     `LINT_GADGET_UNKNOWN_HOOK`, `LINT_GADGET_DUPLICATE_EXPORT`.
+ *   - **Registry-side** (run on an `App.gadgets` catalog at
+ *     registration time by {@link lintGadgetCatalog}):
+ *     `LINT_GADGET_MISSING_PERMISSION`, `LINT_GADGET_UNKNOWN_PERMISSION`,
+ *     `LINT_GADGET_UNSCOPED_PACKAGE`, `LINT_GADGET_IMMUTABLE_MUTATION`,
+ *     `LINT_GADGET_DUPLICATE_EXPORT_IN_CATALOG`.
+ */
+export declare const LINT_ORPHAN_AGENT_TOOL = "LINT_ORPHAN_AGENT_TOOL";
+export declare const LINT_MISSING_USAGE = "LINT_MISSING_USAGE";
+export declare const LINT_MISSING_EXAMPLE = "LINT_MISSING_EXAMPLE";
+export declare const LINT_GADGET_UNKNOWN_HOOK = "LINT_GADGET_UNKNOWN_HOOK";
+export declare const LINT_GADGET_DUPLICATE_EXPORT = "LINT_GADGET_DUPLICATE_EXPORT";
+export declare const LINT_CONTRACT_RETIRED_FIELD = "LINT_CONTRACT_RETIRED_FIELD";
+export declare const LINT_GADGET_MISSING_PERMISSION = "LINT_GADGET_MISSING_PERMISSION";
+export declare const LINT_GADGET_UNKNOWN_PERMISSION = "LINT_GADGET_UNKNOWN_PERMISSION";
+export declare const LINT_GADGET_UNSCOPED_PACKAGE = "LINT_GADGET_UNSCOPED_PACKAGE";
+export declare const LINT_GADGET_IMMUTABLE_MUTATION = "LINT_GADGET_IMMUTABLE_MUTATION";
+export declare const LINT_GADGET_DUPLICATE_EXPORT_IN_CATALOG = "LINT_GADGET_DUPLICATE_EXPORT_IN_CATALOG";
+export declare const LINT_GADGET_DUPLICATE_PACKAGE = "LINT_GADGET_DUPLICATE_PACKAGE";
+/**
+ * Registry-side lint codes that denote a HARD integrity violation —
+ * registration handlers MUST reject the catalog (not just warn) when
+ * {@link lintGadgetCatalog} emits one of these. The lint function
+ * itself stays pure (returns warnings); severity classification is
+ * the caller's, so this set is the single source of truth for "which
+ * codes are fatal."
+ *
+ *   - `LINT_GADGET_IMMUTABLE_MUTATION` — two descriptors share a
+ *     `(package, version)` tuple but disagree on `bundleSri`. The
+ *     same immutable bundle cannot have two hashes; cached blueprints
+ *     keyed on that version would silently break.
+ *   - `LINT_GADGET_DUPLICATE_EXPORT_IN_CATALOG` — two descriptors
+ *     export the same name (a `hook` name or a `component` name). The
+ *     boilerplate generator emits one
+ *     `import { <name> } from '<package>'` per export; a name
+ *     collision in module scope is unresolvable.
+ */
+export declare const FATAL_CATALOG_LINT_CODES: ReadonlySet<string>;
+/**
+ * Retired top-level `DataContract` field names. The contract schema
+ * is `.passthrough()` at the type system level (forward-compat
+ * hedge), but these specific names denote fields that have a known
+ * replacement in the current protocol. Carrying one of them is a
+ * caller bug — silent pass-through would mask the migration.
+ *
+ * Replacements (kept here so the lint message can teach the fix):
+ *   - `libraries`     → `clientCapabilities.gadgets`
+ *   - `dispatch`      → `agentCapabilities.tools` + `actionSpec[*].nextStep`
+ *   - `wiredTools`    → `agentCapabilities.tools`
+ *   - `clientTools`   → `clientCapabilities.gadgets`
+ *   - `broadcast`     → `streamSpec[ch].source`
+ *   - `capabilities`  → `agentCapabilities` + `clientCapabilities`
+ *
+ * Push-gate handlers re-use this list to hard-reject; surfacing it
+ * here keeps the wire vocabulary single-sourced.
+ */
+export declare const RETIRED_CONTRACT_FIELDS: Readonly<Record<string, string>>;
+/**
+ * Permission strings the Web Permissions API ratifies, plus the
+ * MCP Apps `_meta.ui.permissions` enum members for host
+ * passthrough.
+ *
+ * Exported as a tuple + literal-union type so
+ * `strictGadgetDescriptorSchema.permission` can use
+ * `z.enum(KNOWN_PERMISSION_NAMES)` for a hard reject at parse time:
+ * typos (`'geolocaiton'`) and unsupported values fail at the wire
+ * boundary instead of being demoted to a soft warning. Forward-compat
+ * additions land via a protocol version bump.
+ */
+export declare const KNOWN_PERMISSION_NAMES: readonly ["geolocation", "notifications", "microphone", "camera", "persistent-storage", "midi", "clipboard-read", "clipboard-write", "speaker-selection", "storage-access", "background-sync", "accelerometer", "gyroscope", "magnetometer", "ambient-light-sensor", "screen-wake-lock"];
+export type KnownPermissionName = (typeof KNOWN_PERMISSION_NAMES)[number];
+/**
+ * Hygiene-rule warning. Internal — surfaced through `ContractIssue`
+ * via the converters in `lint-contract.ts`. Keep the shape minimal:
+ * code + path + message + fixHint cover the rendering needs of the
+ * authoring tools that consume `lintContract` warnings.
+ */
+export interface HygieneWarning {
+    readonly code: string;
+    readonly path: string;
+    readonly message: string;
+    readonly fixHint?: string;
+}
+/**
+ * Find agentCapabilities.tools entries that are declared but never
+ * referenced from actionSpec or streamSpec. Each orphan is dead
+ * weight — either wire it up or drop it from the catalog.
+ */
+export declare function checkOrphanAgentTools(contract: DataContract): HygieneWarning[];
+/**
+ * Find `agentCapabilities.tools` entries missing the `usage` field.
+ * `usage` is the LLM-targeted "when / why / by-whom" prose; without it
+ * the agent's reasoning loop loses context-of-use information.
+ *
+ * Scope is `agentCapabilities.tools` ONLY. `clientCapabilities.gadgets`
+ * is intentionally NOT linted here: `GadgetExportUse.usage` is an
+ * OPTIONAL intent-OVERRIDE, and the SPEC-documented canonical wire
+ * form is the bare identity reference `gadgets[<pkg>][<export>] = {}`.
+ * Push-time resolution inherits the registered descriptor's `usage`,
+ * and the registry-side `lintGadgetCatalog` (via
+ * `strictGadgetExportSchema`) already enforces real teaching text at
+ * registration time. Flagging an empty wire-side use object would
+ * false-positive the documented happy path.
+ */
+export declare function checkMissingUsage(contract: DataContract): HygieneWarning[];
+/**
+ * Find agentCapabilities.tools entries missing the `example` field.
+ * Examples ground the agent's invocation patterns; a tool without
+ * one is harder to use correctly on the first call.
+ */
+export declare function checkMissingExample(contract: DataContract): HygieneWarning[];
+/**
+ * Wire-side gadget hook-name lint. For every
+ * `clientCapabilities.gadgets[*]` whose `package` is the first-party
+ * stdlib (`@ggui-ai/gadgets`), the `hook` MUST be one the stdlib
+ * actually exports — catches typos (`useGeoLocation`) + stale
+ * references against a constant catalog.
+ *
+ * Third-party packages (any `package !== DEFAULT_GADGET_PACKAGE`) are
+ * NOT checked here — the lint can't know an operator's own hook
+ * names. The registry-side {@link lintGadgetCatalog} + the push-time
+ * {@link assertGadgetsRegistered} gate cover third-party resolution.
+ *
+ * Permission checks live on the registry-side `lintGadgetCatalog`
+ * (the wire gadget reference carries no `permission` field). This
+ * function is the pure wire-only residue: a constant-catalog
+ * hook-name check.
+ */
+export declare function checkGadgetHookNames(contract: DataContract): HygieneWarning[];
+/**
+ * Find `clientCapabilities.gadgets` exports that declare the same
+ * export NAME from two different packages.
+ *
+ * The wire is package-keyed, so the same name cannot repeat WITHIN a
+ * package (object-key uniqueness). The hazard is cross-package: two
+ * packages each exporting `useCheckout`. The boilerplate generator
+ * emits one `import { <name> } from '<package>'` per export; two
+ * imports of the same name — from different packages — produce an
+ * unresolvable identifier collision in the generated module scope.
+ *
+ * Keys on the export name alone, matching the push-time hard gate
+ * `assertNoDuplicateGadgetHooks`. Soft mirror of that gate so
+ * authoring tools surface the issue before a push round-trip.
+ */
+export declare function checkDuplicateGadgetHooks(contract: DataContract): HygieneWarning[];
+/**
+ * Registry-side catalog lint — runs on an `App.gadgets` descriptor
+ * array at registration time (ggui.json load, `ops_register_gadget`,
+ * registry install). Pure function; returns warnings. The caller
+ * (registration handler) treats any code in
+ * {@link FATAL_CATALOG_LINT_CODES} as a hard reject.
+ *
+ * Checks:
+ *
+ *   - `LINT_GADGET_DUPLICATE_EXPORT_IN_CATALOG` (fatal) — two
+ *     descriptors export the same name (a `hook` name or a
+ *     `component` name). Each export name is unique per app; the
+ *     boilerplate's per-export import would collide.
+ *   - `LINT_GADGET_IMMUTABLE_MUTATION` (fatal) — two descriptors
+ *     carry the same `(package, version)` tuple but different
+ *     `bundleSri`. The same immutable bundle cannot have two hashes;
+ *     a cached blueprint pinned to that version would break.
+ *   - `LINT_GADGET_MISSING_PERMISSION` — a known-permission stdlib
+ *     hook (geolocation, camera, …) registered without a
+ *     `permission` field. The agent's reasoning loop reads it to
+ *     surface "this UI prompts for X."
+ *   - `LINT_GADGET_UNKNOWN_PERMISSION` — `permission` set to a value
+ *     outside the Web Permissions API set. (The strict registry
+ *     schema enum-checks this too; the lint is defence-in-depth for
+ *     permissively-parsed catalogs.)
+ *   - `LINT_GADGET_UNSCOPED_PACKAGE` — `package` lacks an `@scope/`
+ *     prefix. Soft recommendation: scoped names avoid registry
+ *     squatting + name collisions.
+ */
+export declare function lintGadgetCatalog(descriptors: readonly GadgetDescriptor[]): HygieneWarning[];
+/**
+ * Find top-level retired-field carriers on the contract. The schema
+ * is `.passthrough()`, so a stray `libraries`/`dispatch`/`wiredTools`/
+ * `clientTools`/`broadcast`/`capabilities` slips through silently. The
+ * push-gate hard-rejects these (see
+ * `mcp-server-handlers/.../assert-contract-no-retired-fields.ts`); this
+ * lint surface keeps authoring tools symmetric — show the warning before
+ * the push call so the author can fix it without a server round-trip.
+ */
+export declare function checkRetiredContractFields(contract: DataContract): HygieneWarning[];
+/**
+ * Run every WIRE-side hygiene rule on a `DataContract`. Aggregates
+ * warnings; order is stable (orphans → usage → example → gadget
+ * hook-names → duplicate-hook → retired fields) so authoring tools
+ * render a predictable checklist.
+ *
+ * Registry-side gadget lints (`lintGadgetCatalog`) are NOT run here:
+ * they need an `App.gadgets` descriptor array, not a contract, and
+ * fire at registration time rather than push time.
+ * Call {@link lintGadgetCatalog} separately at the registration
+ * boundary.
+ */
+export declare function checkHygiene(contract: DataContract): HygieneWarning[];
+//# sourceMappingURL=hygiene-rules.d.ts.map

package/dist/validation/hygiene-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hygiene-rules.d.ts","sourceRoot":"","sources":["../../src/validation/hygiene-rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAW7E;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,sBAAsB,2BAA2B,CAAC;AAC/D,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AACvD,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAC3D,eAAO,MAAM,wBAAwB,6BAA6B,CAAC;AACnE,eAAO,MAAM,4BAA4B,iCAAiC,CAAC;AAC3E,eAAO,MAAM,2BAA2B,gCAAgC,CAAC;AAEzE,eAAO,MAAM,8BAA8B,mCAAmC,CAAC;AAC/E,eAAO,MAAM,8BAA8B,mCAAmC,CAAC;AAC/E,eAAO,MAAM,4BAA4B,iCAAiC,CAAC;AAC3E,eAAO,MAAM,8BAA8B,mCAAmC,CAAC;AAC/E,eAAO,MAAM,uCAAuC,4CACT,CAAC;AAC5C,eAAO,MAAM,6BAA6B,kCAAkC,CAAC;AAE7E;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,MAAM,CAIvD,CAAC;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAO3D,CAAC;AAoBX;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,0RAoBzB,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAsB1E;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAoCD;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,YAAY,GACrB,cAAc,EAAE,CAkBlB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,YAAY,GAAG,cAAc,EAAE,CAmB1E;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,YAAY,GACrB,cAAc,EAAE,CAiBlB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,YAAY,GACrB,cAAc,EAAE,CAgClB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,YAAY,GACrB,cAAc,EAAE,CAmBlB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,SAAS,gBAAgB,EAAE,GACvC,cAAc,EAAE,CAoHlB;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,YAAY,GACrB,cAAc,EAAE,CAiBlB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,YAAY,GACrB,cAAc,EAAE,CASlB"}