@empressaio/atom-contract 1.7.0

package/dist/context.js

@@ -0,0 +1,110 @@
+/**
+ * Four-layer context payload returned by `AtomRegistration.contextSummary`.
+ *
+ * Four layers — `prose`, `typed`, `keyMetrics`, `relatedAtoms` — plus
+ * history provenance and a `scopeFiltered` marker that lets the caller
+ * know whether the {@link Scope} object actually changed the result.
+ */
+/**
+ * Build a `contextSummary` callback that wraps `fetch` against a typed
+ * server endpoint. Centralizes the boilerplate every registration would
+ * otherwise have to write by hand and bakes in the 30s TTL cache plus a
+ * mutation-invalidation hook. The server is expected to return a JSON
+ * body matching {@link ContextSummary}; missing fields are filled with
+ * safe defaults.
+ *
+ * @example
+ *   const summary = httpContextSummary<"task">("task", { ttlMs: 30_000 });
+ *   const reg: AtomRegistration<"task", ["card"]> = {
+ *     entityType: "task",
+ *     domain: "sprint",
+ *     supportedModes: ["card"],
+ *     defaultMode: "card",
+ *     contextSummary: summary.contextSummary,
+ *   };
+ *   // On mutation:
+ *   summary.invalidate(taskId);
+ */
+export function httpContextSummary(slug, opts = {}) {
+    const baseUrl = opts.baseUrl ?? "";
+    const ttlMs = opts.ttlMs ?? 30_000;
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const credentials = opts.credentials ?? "include";
+    const cache = new Map();
+    const fillDefaults = (raw) => ({
+        prose: raw.prose ?? "",
+        typed: raw.typed ?? {},
+        keyMetrics: raw.keyMetrics ?? [],
+        relatedAtoms: raw.relatedAtoms ?? [],
+        historyProvenance: raw.historyProvenance ?? {
+            latestEventId: "",
+            latestEventAt: "",
+        },
+        scopeFiltered: raw.scopeFiltered ?? false,
+        // Pass through verbatim. The field is optional so an absent server
+        // response leaves it `undefined`; visibility-gating surfaces fall back
+        // to the registration's `accessPolicy` (or `"public-free"`) per the
+        // ContextSummary.accessPolicy contract.
+        accessPolicy: raw.accessPolicy,
+    });
+    // Build a stable cache key + a stable wire-format string from a Scope.
+    // Cache reuse must respect the Scope object: an `internal` audience
+    // payload must not be served to an `ai` request, and an as-of-T1
+    // payload must not be served for as-of-T2. Keys are produced by
+    // serializing the scope's identity-affecting fields with sorted
+    // permissions so logically-equivalent scopes hit the same cache row.
+    const serializeScope = (scope) => {
+        const perms = scope.permissions ? [...scope.permissions].sort() : [];
+        const requestor = scope.requestor
+            ? `${scope.requestor.kind}:${scope.requestor.id}`
+            : "";
+        const asOf = scope.asOf ? scope.asOf.toISOString() : "";
+        return JSON.stringify({
+            a: scope.audience,
+            r: requestor,
+            t: asOf,
+            p: perms,
+        });
+    };
+    const cacheKeyFor = (entityId, scope) => `${entityId}|${serializeScope(scope)}`;
+    return {
+        async contextSummary(entityId, scope) {
+            const now = Date.now();
+            const key = cacheKeyFor(entityId, scope);
+            const cached = cache.get(key);
+            if (cached && cached.expiresAt > now) {
+                return cached.value;
+            }
+            // Forward the scope to the server as a single `scope` query
+            // parameter (URL-encoded JSON). Atoms that ignore scope still
+            // receive the same payload because the server is free to ignore
+            // the parameter; atoms that filter by scope can decode it.
+            const scopeParam = encodeURIComponent(serializeScope(scope));
+            const url = `${baseUrl}/atoms/${slug}/${encodeURIComponent(entityId)}/summary?scope=${scopeParam}`;
+            const res = await fetchImpl(url, { credentials });
+            if (!res.ok) {
+                throw new Error(`httpContextSummary(${slug}): HTTP ${res.status} fetching ${url}`);
+            }
+            const body = (await res.json());
+            const value = fillDefaults(body);
+            if (ttlMs > 0) {
+                cache.set(key, { value, expiresAt: now + ttlMs });
+            }
+            return value;
+        },
+        invalidate(entityId) {
+            // Drop every cached scope variant for this entity. Mutation
+            // pipelines do not know which scopes a consumer has fetched, so
+            // an entity-level invalidate must clear all of them.
+            const prefix = `${entityId}|`;
+            for (const k of cache.keys()) {
+                if (k.startsWith(prefix))
+                    cache.delete(k);
+            }
+        },
+        clear() {
+            cache.clear();
+        },
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

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

package/dist/encumbrances/administrative-rule.d.ts

@@ -0,0 +1,128 @@
+import { z } from "zod";
+import type { WidthedConfidence } from "../read-contract/common.js";
+import { STRUCTURED_FIELDS_SCHEMA } from "./common.js";
+/**
+ * Unrecorded HOA design guidelines. Same clause shape where applicable;
+ * `legalWeight` is fixed to `advisory`.
+ */
+export interface AdministrativeRuleAtomInstance {
+    entityType: "administrative-rule";
+    clauseDid: string;
+    parentInstrumentCid?: string;
+    clausePath: string;
+    bodyText: string;
+    structuredFields?: z.infer<typeof STRUCTURED_FIELDS_SCHEMA>;
+    confidence: WidthedConfidence;
+    extractedBy: string;
+    humanVerifiedAt?: string;
+    verifiedByActorDid?: string;
+    sourceDocumentCid?: string;
+    accessPolicy: "tenant-private" | "tenant-shared";
+    legalWeight: "advisory";
+    reasoningSummary?: string;
+    sourceCitation: string;
+    evaluatedAt: string;
+}
+export declare const ADMINISTRATIVE_RULE_SCHEMA: z.ZodObject<{
+    confidence: z.ZodReadonly<z.ZodObject<{
+        readonly estimate: z.ZodNumber;
+        readonly n: z.ZodNumber;
+        readonly intervalWidth: z.ZodNumber;
+        readonly provenance: z.ZodEnum<["asserted", "backtest", "seed", "live"]>;
+    }, "strip", z.ZodTypeAny, {
+        estimate: number;
+        n: number;
+        intervalWidth: number;
+        provenance: "asserted" | "backtest" | "seed" | "live";
+    }, {
+        estimate: number;
+        n: number;
+        intervalWidth: number;
+        provenance: "asserted" | "backtest" | "seed" | "live";
+    }>>;
+    evaluatedAt: z.ZodString;
+    reasoningSummary: z.ZodOptional<z.ZodString>;
+    sourceCitation: z.ZodString;
+    entityType: z.ZodLiteral<"administrative-rule">;
+    clauseDid: z.ZodString;
+    parentInstrumentCid: z.ZodOptional<z.ZodString>;
+    clausePath: z.ZodString;
+    bodyText: z.ZodString;
+    structuredFields: z.ZodOptional<z.ZodObject<{
+        maxHeightFt: z.ZodOptional<z.ZodNumber>;
+        prohibitedUses: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        setbackFt: z.ZodOptional<z.ZodNumber>;
+        materialAllowlist: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        maxHeightFt: z.ZodOptional<z.ZodNumber>;
+        prohibitedUses: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        setbackFt: z.ZodOptional<z.ZodNumber>;
+        materialAllowlist: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        maxHeightFt: z.ZodOptional<z.ZodNumber>;
+        prohibitedUses: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        setbackFt: z.ZodOptional<z.ZodNumber>;
+        materialAllowlist: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, z.ZodTypeAny, "passthrough">>>;
+    extractedBy: z.ZodString;
+    humanVerifiedAt: z.ZodOptional<z.ZodString>;
+    verifiedByActorDid: z.ZodOptional<z.ZodString>;
+    sourceDocumentCid: z.ZodOptional<z.ZodString>;
+    accessPolicy: z.ZodEnum<["tenant-private", "tenant-shared"]>;
+    legalWeight: z.ZodLiteral<"advisory">;
+}, "strip", z.ZodTypeAny, {
+    accessPolicy: "tenant-private" | "tenant-shared";
+    entityType: "administrative-rule";
+    confidence: Readonly<{
+        estimate: number;
+        n: number;
+        intervalWidth: number;
+        provenance: "asserted" | "backtest" | "seed" | "live";
+    }>;
+    sourceCitation: string;
+    clauseDid: string;
+    clausePath: string;
+    bodyText: string;
+    extractedBy: string;
+    legalWeight: "advisory";
+    evaluatedAt: string;
+    parentInstrumentCid?: string | undefined;
+    structuredFields?: z.objectOutputType<{
+        maxHeightFt: z.ZodOptional<z.ZodNumber>;
+        prohibitedUses: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        setbackFt: z.ZodOptional<z.ZodNumber>;
+        materialAllowlist: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+    humanVerifiedAt?: string | undefined;
+    verifiedByActorDid?: string | undefined;
+    sourceDocumentCid?: string | undefined;
+    reasoningSummary?: string | undefined;
+}, {
+    accessPolicy: "tenant-private" | "tenant-shared";
+    entityType: "administrative-rule";
+    confidence: Readonly<{
+        estimate: number;
+        n: number;
+        intervalWidth: number;
+        provenance: "asserted" | "backtest" | "seed" | "live";
+    }>;
+    sourceCitation: string;
+    clauseDid: string;
+    clausePath: string;
+    bodyText: string;
+    extractedBy: string;
+    legalWeight: "advisory";
+    evaluatedAt: string;
+    parentInstrumentCid?: string | undefined;
+    structuredFields?: z.objectInputType<{
+        maxHeightFt: z.ZodOptional<z.ZodNumber>;
+        prohibitedUses: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        setbackFt: z.ZodOptional<z.ZodNumber>;
+        materialAllowlist: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+    humanVerifiedAt?: string | undefined;
+    verifiedByActorDid?: string | undefined;
+    sourceDocumentCid?: string | undefined;
+    reasoningSummary?: string | undefined;
+}>;
+//# sourceMappingURL=administrative-rule.d.ts.map

package/dist/encumbrances/administrative-rule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"administrative-rule.d.ts","sourceRoot":"","sources":["../../src/encumbrances/administrative-rule.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,EAGL,wBAAwB,EACzB,MAAM,aAAa,CAAC;AAErB;;;GAGG;AACH,MAAM,WAAW,8BAA8B;IAC7C,UAAU,EAAE,qBAAqB,CAAC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;IAC5D,UAAU,EAAE,iBAAiB,CAAC;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,gBAAgB,GAAG,eAAe,CAAC;IACjD,WAAW,EAAE,UAAU,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAcrC,CAAC"}

package/dist/encumbrances/administrative-rule.js

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import { ENCUMBRANCE_ACCESS_POLICY_SCHEMA, QUALITY_GATE_FIELDS, STRUCTURED_FIELDS_SCHEMA, } from "./common.js";
+export const ADMINISTRATIVE_RULE_SCHEMA = z.object({
+    entityType: z.literal("administrative-rule"),
+    clauseDid: z.string().min(1),
+    parentInstrumentCid: z.string().min(1).optional(),
+    clausePath: z.string().min(1),
+    bodyText: z.string().min(1),
+    structuredFields: STRUCTURED_FIELDS_SCHEMA.optional(),
+    extractedBy: z.string().min(1),
+    humanVerifiedAt: z.string().min(1).optional(),
+    verifiedByActorDid: z.string().min(1).optional(),
+    sourceDocumentCid: z.string().min(1).optional(),
+    accessPolicy: ENCUMBRANCE_ACCESS_POLICY_SCHEMA,
+    legalWeight: z.literal("advisory"),
+    ...QUALITY_GATE_FIELDS,
+});
+//# sourceMappingURL=administrative-rule.js.map

package/dist/encumbrances/administrative-rule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"administrative-rule.js","sourceRoot":"","sources":["../../src/encumbrances/administrative-rule.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EACL,gCAAgC,EAChC,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,aAAa,CAAC;AAyBrB,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,UAAU,EAAE,CAAC,CAAC,OAAO,CAAC,qBAAqB,CAAC;IAC5C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5B,mBAAmB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACjD,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3B,gBAAgB,EAAE,wBAAwB,CAAC,QAAQ,EAAE;IACrD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC7C,kBAAkB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAChD,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC/C,YAAY,EAAE,gCAAgC;IAC9C,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;IAClC,GAAG,mBAAmB;CACvB,CAAC,CAAC"}

package/dist/encumbrances/common.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Shared encumbrance substrate types per ADR-020 / ADR-021.
+ *
+ * Encumbrance atoms are never `public-free`. Schemas use
+ * {@link ENCUMBRANCE_ACCESS_POLICY_SCHEMA} rather than the full
+ * {@link AccessPolicy} union so public tiers fail validation at the
+ * boundary.
+ */
+import { z } from "zod";
+import type { AccessPolicy } from "../registration.js";
+import { type WidthedConfidence } from "../read-contract/common.js";
+/**
+ * ADR-020 instrument categories.
+ * Extended in 1.7.0 (ADR-025) with O&G instrument types including the recorded
+ * unit family per Herbert review (85a): unit-designation, declaration-of-pooling,
+ * ratification-of-unit, amendment-of-unit-designation, release-of-unit.
+ */
+export type InstrumentType = "plat-restriction" | "cc-r-declaration" | "deed-restriction" | "easement" | "lien" | "oil-gas-lease" | "mineral-deed" | "assignment" | "division-order" | "unit-designation" | "declaration-of-pooling" | "ratification-of-unit" | "amendment-of-unit-designation" | "release-of-unit" | "other";
+export declare const INSTRUMENT_TYPES: ReadonlyArray<InstrumentType>;
+/** Ingest source track per {@link 49b_encumbrance_ingestion_pipeline}. */
+export type EncumbranceSourceAdapter = "R1" | "R2" | "R3" | "R4" | "R5";
+export declare const ENCUMBRANCE_SOURCE_ADAPTERS: ReadonlyArray<EncumbranceSourceAdapter>;
+export type VerificationStatus = "machine" | "human" | "title-company";
+export declare const VERIFICATION_STATUSES: ReadonlyArray<VerificationStatus>;
+export type LegalWeight = "recorded" | "advisory";
+export declare const LEGAL_WEIGHTS: ReadonlyArray<LegalWeight>;
+/**
+ * Access tiers allowed on encumbrance payloads. Subset of ADR-017
+ * {@link AccessPolicy}; excludes all public tiers.
+ */
+export type EncumbranceAccessPolicy = "tenant-private" | "tenant-shared";
+export declare const ENCUMBRANCE_ACCESS_POLICIES: ReadonlyArray<EncumbranceAccessPolicy>;
+export declare const ENCUMBRANCE_ACCESS_POLICY_SCHEMA: z.ZodEnum<["tenant-private", "tenant-shared"]>;
+/** Rejects catalog-visible tiers on encumbrance instances. */
+export declare function isEncumbranceAccessPolicy(value: AccessPolicy | undefined): value is EncumbranceAccessPolicy;
+export declare const RECORDING_SCHEMA: z.ZodObject<{
+    county: z.ZodString;
+    state: z.ZodString;
+    book: z.ZodOptional<z.ZodString>;
+    page: z.ZodOptional<z.ZodString>;
+    instrumentNumber: z.ZodOptional<z.ZodString>;
+    recordedAt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    county: string;
+    state: string;
+    recordedAt?: string | undefined;
+    book?: string | undefined;
+    page?: string | undefined;
+    instrumentNumber?: string | undefined;
+}, {
+    county: string;
+    state: string;
+    recordedAt?: string | undefined;
+    book?: string | undefined;
+    page?: string | undefined;
+    instrumentNumber?: string | undefined;
+}>;
+export type RecordingInfo = z.infer<typeof RECORDING_SCHEMA>;
+export declare const APPLIES_TO_SCHEMA: z.ZodEffects<z.ZodObject<{
+    parcelDids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    platId: z.ZodOptional<z.ZodString>;
+    legalDescription: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    parcelDids?: string[] | undefined;
+    platId?: string | undefined;
+    legalDescription?: string | undefined;
+}, {
+    parcelDids?: string[] | undefined;
+    platId?: string | undefined;
+    legalDescription?: string | undefined;
+}>, {
+    parcelDids?: string[] | undefined;
+    platId?: string | undefined;
+    legalDescription?: string | undefined;
+}, {
+    parcelDids?: string[] | undefined;
+    platId?: string | undefined;
+    legalDescription?: string | undefined;
+}>;
+export type AppliesTo = z.infer<typeof APPLIES_TO_SCHEMA>;
+/** Typed extract bucket on {@link RestrictionClauseAtomInstance}. */
+export declare const STRUCTURED_FIELDS_SCHEMA: z.ZodObject<{
+    maxHeightFt: z.ZodOptional<z.ZodNumber>;
+    prohibitedUses: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    setbackFt: z.ZodOptional<z.ZodNumber>;
+    materialAllowlist: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    maxHeightFt: z.ZodOptional<z.ZodNumber>;
+    prohibitedUses: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    setbackFt: z.ZodOptional<z.ZodNumber>;
+    materialAllowlist: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    maxHeightFt: z.ZodOptional<z.ZodNumber>;
+    prohibitedUses: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    setbackFt: z.ZodOptional<z.ZodNumber>;
+    materialAllowlist: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, z.ZodTypeAny, "passthrough">>;
+export type StructuredFields = z.infer<typeof STRUCTURED_FIELDS_SCHEMA>;
+export declare const QUALITY_GATE_FIELDS: {
+    readonly confidence: z.ZodReadonly<z.ZodObject<{
+        readonly estimate: z.ZodNumber;
+        readonly n: z.ZodNumber;
+        readonly intervalWidth: z.ZodNumber;
+        readonly provenance: z.ZodEnum<["asserted", "backtest", "seed", "live"]>;
+    }, "strip", z.ZodTypeAny, {
+        estimate: number;
+        n: number;
+        intervalWidth: number;
+        provenance: "asserted" | "backtest" | "seed" | "live";
+    }, {
+        estimate: number;
+        n: number;
+        intervalWidth: number;
+        provenance: "asserted" | "backtest" | "seed" | "live";
+    }>>;
+    readonly evaluatedAt: z.ZodString;
+    readonly reasoningSummary: z.ZodOptional<z.ZodString>;
+    readonly sourceCitation: z.ZodString;
+};
+/**
+ * Asserted source-quality confidence for encumbrance extract quality gates.
+ * Pre-calibration deposits use `provenance: "asserted"`, `n: 0`, and full
+ * interval width until outcome fuel exists.
+ */
+export declare function createEncumbranceQualityConfidence(estimate: number): WidthedConfidence;
+/**
+ * Recommended render modes for engine / product registrations.
+ * `restriction-clause` includes `focus` for citation surfaces (ADR-020
+ * dispatch).
+ */
+export declare const ENCUMBRANCE_RENDER_MODES: {
+    "recorded-instrument": readonly ["card", "compact", "expanded"];
+    "restriction-clause": readonly ["inline", "compact", "card", "expanded", "focus"];
+    "restriction-corpus": readonly ["card", "expanded"];
+    "administrative-rule": readonly ["inline", "compact", "card", "expanded"];
+    "constraint-resolution": readonly ["card", "expanded"];
+};
+export declare const ENCUMBRANCE_DEFAULT_RENDER_MODE: {
+    readonly "recorded-instrument": "card";
+    readonly "restriction-clause": "focus";
+    readonly "restriction-corpus": "card";
+    readonly "administrative-rule": "compact";
+    readonly "constraint-resolution": "card";
+};
+/** Atom-type default access tiers (never `public-free`). */
+export declare const ENCUMBRANCE_DEFAULT_ACCESS_POLICY: {
+    readonly "recorded-instrument": "tenant-private";
+    readonly "restriction-clause": "tenant-private";
+    readonly "restriction-corpus": "tenant-shared";
+    readonly "administrative-rule": "tenant-private";
+    readonly "constraint-resolution": "tenant-private";
+};
+//# sourceMappingURL=common.d.ts.map

package/dist/encumbrances/common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../src/encumbrances/common.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,YAAY,EAAY,MAAM,oBAAoB,CAAC;AACjE,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,4BAA4B,CAAC;AAEpC;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GACtB,kBAAkB,GAClB,kBAAkB,GAClB,kBAAkB,GAClB,UAAU,GACV,MAAM,GACN,eAAe,GACf,cAAc,GACd,YAAY,GACZ,gBAAgB,GAChB,kBAAkB,GAClB,wBAAwB,GACxB,sBAAsB,GACtB,+BAA+B,GAC/B,iBAAiB,GACjB,OAAO,CAAC;AAEZ,eAAO,MAAM,gBAAgB,EAAE,aAAa,CAAC,cAAc,CAgB1D,CAAC;AAEF,0EAA0E;AAC1E,MAAM,MAAM,wBAAwB,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAExE,eAAO,MAAM,2BAA2B,EAAE,aAAa,CAAC,wBAAwB,CAChD,CAAC;AAEjC,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,OAAO,GAAG,eAAe,CAAC;AAEvE,eAAO,MAAM,qBAAqB,EAAE,aAAa,CAAC,kBAAkB,CAInE,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,UAAU,CAAC;AAElD,eAAO,MAAM,aAAa,EAAE,aAAa,CAAC,WAAW,CAA4B,CAAC;AAElF;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,gBAAgB,GAAG,eAAe,CAAC;AAEzE,eAAO,MAAM,2BAA2B,EAAE,aAAa,CAAC,uBAAuB,CAC1C,CAAC;AAEtC,eAAO,MAAM,gCAAgC,gDAG3C,CAAC;AAEH,8DAA8D;AAC9D,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,YAAY,GAAG,SAAS,GAC9B,KAAK,IAAI,uBAAuB,CAElC;AAED,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;EAO3B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE7D,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;EAe3B,CAAC;AAEJ,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE1D,qEAAqE;AACrE,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;gCAOrB,CAAC;AAEjB,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAExE,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;CAKtB,CAAC;AAEX;;;;GAIG;AACH,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,MAAM,GACf,iBAAiB,CAOnB;AAED;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;;;;;;CAYc,CAAC;AAEpD,eAAO,MAAM,+BAA+B;;;;;;CAMC,CAAC;AAE9C,4DAA4D;AAC5D,eAAO,MAAM,iCAAiC;;;;;;CAMc,CAAC"}

package/dist/encumbrances/common.js

@@ -0,0 +1,124 @@
+/**
+ * Shared encumbrance substrate types per ADR-020 / ADR-021.
+ *
+ * Encumbrance atoms are never `public-free`. Schemas use
+ * {@link ENCUMBRANCE_ACCESS_POLICY_SCHEMA} rather than the full
+ * {@link AccessPolicy} union so public tiers fail validation at the
+ * boundary.
+ */
+import { z } from "zod";
+import { createWidthedConfidence, WIDTHED_CONFIDENCE_SCHEMA, } from "../read-contract/common.js";
+export const INSTRUMENT_TYPES = [
+    "plat-restriction",
+    "cc-r-declaration",
+    "deed-restriction",
+    "easement",
+    "lien",
+    "oil-gas-lease",
+    "mineral-deed",
+    "assignment",
+    "division-order",
+    "unit-designation",
+    "declaration-of-pooling",
+    "ratification-of-unit",
+    "amendment-of-unit-designation",
+    "release-of-unit",
+    "other",
+];
+export const ENCUMBRANCE_SOURCE_ADAPTERS = ["R1", "R2", "R3", "R4", "R5"];
+export const VERIFICATION_STATUSES = [
+    "machine",
+    "human",
+    "title-company",
+];
+export const LEGAL_WEIGHTS = ["recorded", "advisory"];
+export const ENCUMBRANCE_ACCESS_POLICIES = ["tenant-private", "tenant-shared"];
+export const ENCUMBRANCE_ACCESS_POLICY_SCHEMA = z.enum([
+    "tenant-private",
+    "tenant-shared",
+]);
+/** Rejects catalog-visible tiers on encumbrance instances. */
+export function isEncumbranceAccessPolicy(value) {
+    return value === "tenant-private" || value === "tenant-shared";
+}
+export const RECORDING_SCHEMA = z.object({
+    county: z.string().min(1),
+    state: z.string().min(1),
+    book: z.string().min(1).optional(),
+    page: z.string().min(1).optional(),
+    instrumentNumber: z.string().min(1).optional(),
+    recordedAt: z.string().min(1).optional(),
+});
+export const APPLIES_TO_SCHEMA = z
+    .object({
+    parcelDids: z.array(z.string().min(1)).optional(),
+    platId: z.string().min(1).optional(),
+    legalDescription: z.string().min(1).optional(),
+})
+    .refine((v) => (v.parcelDids?.length ?? 0) > 0 ||
+    v.platId !== undefined ||
+    v.legalDescription !== undefined, {
+    message: "appliesTo requires at least one of parcelDids, platId, or legalDescription",
+});
+/** Typed extract bucket on {@link RestrictionClauseAtomInstance}. */
+export const STRUCTURED_FIELDS_SCHEMA = z
+    .object({
+    maxHeightFt: z.number().optional(),
+    prohibitedUses: z.array(z.string()).optional(),
+    setbackFt: z.number().optional(),
+    materialAllowlist: z.array(z.string()).optional(),
+})
+    .passthrough();
+export const QUALITY_GATE_FIELDS = {
+    confidence: WIDTHED_CONFIDENCE_SCHEMA,
+    evaluatedAt: z.string().min(1),
+    reasoningSummary: z.string().min(1).optional(),
+    sourceCitation: z.string().min(1),
+};
+/**
+ * Asserted source-quality confidence for encumbrance extract quality gates.
+ * Pre-calibration deposits use `provenance: "asserted"`, `n: 0`, and full
+ * interval width until outcome fuel exists.
+ */
+export function createEncumbranceQualityConfidence(estimate) {
+    return createWidthedConfidence({
+        estimate,
+        n: 0,
+        intervalWidth: 1,
+        provenance: "asserted",
+    });
+}
+/**
+ * Recommended render modes for engine / product registrations.
+ * `restriction-clause` includes `focus` for citation surfaces (ADR-020
+ * dispatch).
+ */
+export const ENCUMBRANCE_RENDER_MODES = {
+    "recorded-instrument": ["card", "compact", "expanded"],
+    "restriction-clause": [
+        "inline",
+        "compact",
+        "card",
+        "expanded",
+        "focus",
+    ],
+    "restriction-corpus": ["card", "expanded"],
+    "administrative-rule": ["inline", "compact", "card", "expanded"],
+    "constraint-resolution": ["card", "expanded"],
+};
+export const ENCUMBRANCE_DEFAULT_RENDER_MODE = {
+    "recorded-instrument": "card",
+    "restriction-clause": "focus",
+    "restriction-corpus": "card",
+    "administrative-rule": "compact",
+    "constraint-resolution": "card",
+};
+/** Atom-type default access tiers (never `public-free`). */
+export const ENCUMBRANCE_DEFAULT_ACCESS_POLICY = {
+    "recorded-instrument": "tenant-private",
+    "restriction-clause": "tenant-private",
+    "restriction-corpus": "tenant-shared",
+    "administrative-rule": "tenant-private",
+    "constraint-resolution": "tenant-private",
+};
+//# sourceMappingURL=common.js.map

package/dist/encumbrances/common.js.map

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