@inflexa-ai/harness 0.28.1 → 0.30.0

package/dist/app/data-profile-view.js

@@ -0,0 +1,123 @@
+/**
+ * One reading of a persisted profile, whichever era wrote it.
+ *
+ * A snapshot carries the fields of its era: rows written under the groups-and-dimensions
+ * model carry `groups`/`dimensions`, and rows written before it carry `kinds`/`axes` and
+ * a `files` list. There is no version field to consult — optionality is the compatibility
+ * mechanism — so a consumer must read both, and reading both in five places is how they
+ * drift apart. They read it here instead.
+ *
+ * The projection is lossy in one direction only: it narrows the newer record to what the
+ * older consumers already handled. Nothing it drops is unavailable — the full record is
+ * on the row, and consumers that want the resolved structure read it directly.
+ */
+/**
+ * Every number the observations reported, side by side and de-duplicated.
+ *
+ * There is no canonical cardinality: a metadata sheet describing one count and files
+ * existing for another both stand, so a single number would be a silent judgement between
+ * disagreeing sources.
+ */
+export function dimensionCardinalities(dimension) {
+    const counts = [];
+    for (const observation of dimension.observations) {
+        if (observation.kind === "slot")
+            counts.push(observation.cardinality);
+        else if (observation.kind === "column" && observation.distinctValues !== undefined)
+            counts.push(observation.distinctValues);
+        else if (observation.kind === "document" && observation.statesCardinality !== undefined)
+            counts.push(observation.statesCardinality);
+    }
+    return [...new Set(counts)];
+}
+function examplesOf(dimension) {
+    for (const observation of dimension.observations) {
+        if (observation.kind === "slot" && observation.sampleValues.length > 0)
+            return observation.sampleValues;
+        if (observation.kind === "column" && observation.exampleValues.length > 0)
+            return observation.exampleValues;
+    }
+    return [];
+}
+function fromGroup(group) {
+    const format = group.formats.length === 1 ? group.formats[0].format : undefined;
+    return {
+        id: group.id,
+        name: group.name,
+        memberRepresents: group.memberRepresents,
+        description: group.description,
+        count: group.count,
+        pattern: group.displayPattern,
+        ...(format ? { format } : {}),
+        ...(group.slots ? { slotIds: group.slots.map((slot) => slot.id) } : {}),
+        ...(group.unclassified ? { unclassified: true } : {}),
+    };
+}
+/** The dataset's structure, from whichever field the snapshot carries it in. */
+export function profileGroups(result) {
+    if (result.groups !== undefined)
+        return result.groups.map(fromGroup);
+    return (result.kinds ?? []).map((kind, index) => ({
+        id: `kind-${index + 1}`,
+        name: kind.name,
+        memberRepresents: kind.memberRepresents,
+        description: kind.description,
+        count: kind.count,
+        pattern: kind.pathPattern,
+        ...(kind.format ? { format: kind.format } : {}),
+    }));
+}
+/** What varies across the dataset, from whichever field the snapshot carries it in. */
+export function profileDimensions(result) {
+    if (result.dimensions !== undefined) {
+        return result.dimensions.map((dimension) => ({
+            label: dimension.label,
+            cardinalities: dimensionCardinalities(dimension),
+            exampleValues: examplesOf(dimension),
+            ...(dimension.description ? { description: dimension.description } : {}),
+        }));
+    }
+    return (result.axes ?? []).map((axis) => ({
+        label: axis.label,
+        cardinalities: [axis.cardinality],
+        exampleValues: axis.exampleValues ?? [],
+        ...(axis.description ? { description: axis.description } : {}),
+    }));
+}
+/**
+ * The files the profile describes individually.
+ *
+ * On a groups-era row those are the members the agent annotated, which ride on the group
+ * they belong to; on an older row they are the `files` list. Either way this is a handful
+ * of notable inputs, never the dataset.
+ */
+export function profileFileRecords(result) {
+    if (result.groups !== undefined) {
+        return result.groups.flatMap((group) => (group.memberAnnotations ?? []).map((annotation) => ({
+            path: annotation.path,
+            description: annotation.note,
+            ...(group.formats.length === 1 ? { format: group.formats[0].format } : {}),
+        })));
+    }
+    return result.files ?? [];
+}
+/**
+ * How many files the dataset holds, as far as the snapshot can establish it.
+ *
+ * The partition is the authority where present — it is a census, not an estimate. Older
+ * rows fall back to coverage, then to summed kind counts, then to `null`: reporting the
+ * described-file count would be a dataset size the row cannot support.
+ */
+export function profileDatasetFileCount(result) {
+    if (result.partition)
+        return result.partition.keptFiles;
+    if (result.coverage)
+        return result.coverage.total;
+    if (result.kinds && result.kinds.length > 0)
+        return result.kinds.reduce((sum, kind) => sum + kind.count, 0);
+    return null;
+}
+/** Dataset-wide findings the agent wrote, from whichever field the snapshot carries them in. */
+export function profileCaveats(result) {
+    return result.caveats ?? result.qualityAssessment?.concerns ?? [];
+}

package/dist/app/synthesize-run.js

@@ -78,7 +78,7 @@ export async function synthesizeRun(deps, params) {
             unwrapOrThrow(await vectorStore.upsert({
                 indexName,
                 vectors: [vector],
-                metadata: [{ text: synthesisText, type: "synthesis", runId }],
+                metadata: [{ text: synthesisText, type: "synthesis", runId, path: `runs/${runId}/synthesis.json` }],
                 ids: [`/${analysisId}/runs/${runId}/synthesis.json`],
             }));
         }

package/dist/config/resource-limits.d.ts

@@ -46,7 +46,7 @@ export type ResourcePolicy = z.infer<typeof ResourcePolicySchema>;
 /** Default LLM-turn budget for a sandbox agent step. Covers simple,
  *  standard, and complex analyses — extra headroom on simple steps is
  *  cheaper than truncating complex ones. */
-export declare const DEFAULT_SANDBOX_MAX_STEPS = 75;
+export declare const DEFAULT_SANDBOX_MAX_STEPS = 200;
 export declare class ResourceLimitsConfigError extends Error {
     constructor(message: string);
 }

package/dist/config/resource-limits.js

@@ -33,7 +33,7 @@ export const ResourcePolicySchema = z.object({
 /** Default LLM-turn budget for a sandbox agent step. Covers simple,
  *  standard, and complex analyses — extra headroom on simple steps is
  *  cheaper than truncating complex ones. */
-export const DEFAULT_SANDBOX_MAX_STEPS = 75;
+export const DEFAULT_SANDBOX_MAX_STEPS = 200;
 // ── Error ───────────────────────────────────────────────────────────
 export class ResourceLimitsConfigError extends Error {
     constructor(message) {

package/dist/contracts/data-profile.d.ts

@@ -61,10 +61,12 @@ export interface DataProfileFile {
     /** Flat, identity-establishing facts (sparsity, delimiter, normalizationState, …). */
     metrics?: Record<string, string | number | boolean>;
 }
-/** Dataset-wide quality findings the profiler recorded. */
+/**
+ * Dataset-wide quality findings, on rows of the era that recorded them. Superseded by
+ * `caveats`, which is agent-authored prose and nothing else.
+ */
 export interface DataProfileQualityAssessment {
     concerns: string[];
-    strengths: string[];
 }
 /**
  * One repeating set of files — the dataset's structure, as opposed to its contents.
@@ -97,6 +99,251 @@ export interface DataProfileAxis {
     exampleValues?: string[];
     description?: string;
 }
+/**
+ * A varying position in a group's display template, as the scan observed it.
+ *
+ * `sampleValues` is bounded and the record carries nothing wider: a full value
+ * enumeration would put the file set back in the row this record exists to keep out of
+ * it. The id is scan-scoped — it names the slot within the scan that produced this
+ * profile, and a dimension's slot observation refers to it.
+ */
+export interface DataProfileGroupSlot {
+    id: string;
+    location: "directory" | "name";
+    index: number;
+    tokenClass: string;
+    distinctValues: number;
+    sampleValues: string[];
+    /** The slot this one repeats — one token in both a directory segment and the stem is ONE identity. */
+    sameAsSlot?: string;
+}
+/** A member the agent wrote about individually. Never exhaustive — that is the filesystem's job. */
+export interface DataProfileMemberAnnotation {
+    path: string;
+    note: string;
+}
+/**
+ * Companion coverage across a group, computed per member.
+ *
+ * A machine finding, deliberately structured rather than folded into `caveats`: an
+ * average hides the one member whose index is missing, and that is the member a
+ * downstream step fails on.
+ */
+export interface DataProfileCompanionCompleteness {
+    expectedCompanions: string[];
+    completeMembers: number;
+    incompleteMembers: number;
+    incompleteSample: {
+        path: string;
+        missingCompanions: string[];
+    }[];
+}
+/**
+ * One declared group — a claim about MEANING, resolved to a membership.
+ *
+ * `count` counts logical members (a data file and its companions count once); `fileCount`
+ * counts the files behind them, and it is `fileCount` that the partition accounting sums.
+ * `displayPattern` is the scanner's own template and is display-only: no agent authored
+ * it, and nothing computes membership from it.
+ */
+export interface DataProfileGroup {
+    /** Stable within the profile, derived from the group's name. */
+    id: string;
+    name: string;
+    /** What ONE member represents. The grouping decision, stated apart from the description. */
+    memberRepresents: string;
+    description: string;
+    role: string;
+    category: string;
+    /** What the group actually is, when `category` is `other`. */
+    categoryLabel?: string;
+    subtype?: string;
+    /** Why the agent overrode a pre-suggestion, or chose an arguable category. */
+    categoryReason?: string;
+    /** Why this group was split off, or why these sets are one group. */
+    reason?: string;
+    count: number;
+    fileCount: number;
+    totalBytes: number;
+    /** The scanner template the members instantiate. Display-only. */
+    displayPattern: string;
+    formats: {
+        format: string;
+        count: number;
+    }[];
+    slots?: DataProfileGroupSlot[];
+    memberAnnotations?: DataProfileMemberAnnotation[];
+    completeness?: DataProfileCompanionCompleteness;
+    /** True for the swept residue — files no operation claimed. Visible by construction. */
+    unclassified?: boolean;
+}
+/** A measurement that was actually performed. Absent means unchecked, never "no overlap". */
+export interface DataProfileChecked {
+    matched: number;
+    of: number;
+}
+/**
+ * Where a slot observation points, in terms that survive the scan that produced it.
+ *
+ * A slot id is per-scan ephemera — the same id names a different slot after a re-scan
+ * reorders the sets — so the durable binding is the set's template plus the slot's
+ * position within it, exactly as the recipe keys a split. A binding that no longer
+ * resolves strands the profile rather than rebinding to whatever now sits at that
+ * position.
+ */
+export interface DataProfileSlotBinding {
+    template: string;
+    slotIndex: number;
+}
+/**
+ * One evidenced sighting of a dimension.
+ *
+ * A slot observation binds to a scanner slot, and its cardinality and values are computed
+ * from the scan rather than asserted; `groupIds` are the groups that carry that slot,
+ * derived from the operations. Slot bindings are the only link between a group and a
+ * dimension.
+ */
+export type DataProfileObservation = {
+    kind: "slot";
+    groupIds: string[];
+    /** Scan-scoped, and display-only past the scan that wrote it. `binding` is what replays. */
+    slotId: string;
+    binding?: DataProfileSlotBinding;
+    tokenClass: string;
+    cardinality: number;
+    sampleValues: string[];
+    checked?: DataProfileChecked;
+    checkedAgainst?: string;
+    /**
+     * The slot the SCANNER found this one repeats, with the members whose two tokens
+     * disagreed. Its own performed measurement, in members rather than values — and
+     * the reason `checked` stays absent for such a pair: affix recovery strips literal
+     * text off one side, so an exact value-set intersection over two positions the
+     * scan matched one-to-one would report them wholly disjoint.
+     */
+    sameAsSlot?: string;
+    sameAsSlotMismatches?: number;
+    note?: string;
+} | {
+    kind: "column";
+    path: string;
+    column: string;
+    exampleValues: string[];
+    distinctValues?: number;
+    checked?: DataProfileChecked;
+    checkedAgainst?: string;
+    note?: string;
+} | {
+    kind: "document";
+    path: string;
+    citation: string;
+    statesCardinality?: number;
+    checked?: DataProfileChecked;
+    checkedAgainst?: string;
+    note?: string;
+};
+/**
+ * A dataset-level thing that varies, with the evidence it was seen in.
+ *
+ * There is no canonical cardinality: observations that disagree both stand, and
+ * `reconciliations` carries the delta. A renderer shows the numbers side by side.
+ */
+export interface DataProfileDimension {
+    label: string;
+    category: string;
+    categoryLabel?: string;
+    /** Derived from the category, never agent-authored. */
+    scope: "biological" | "technical";
+    description?: string;
+    observations: DataProfileObservation[];
+    reconciliations?: {
+        note: string;
+        delta?: number;
+    }[];
+    nestsUnder?: {
+        dimension: string;
+        evidence: string;
+    };
+    /** Why the dataset deviates from the category's default treatment. */
+    treatmentReason?: string;
+}
+/** What the agent found when it looked for one of the standard dimensions. */
+export interface DataProfileProbeReport {
+    probe: string;
+    outcome: "found" | "not-found" | "found-but-constant" | "attested";
+    dimension?: string;
+    searched?: string[];
+    reason?: string;
+    value?: string;
+    evidence?: string;
+    citation?: string;
+    path?: string;
+}
+/** Files the scan removed before structure was observed, with why. */
+export interface DataProfileQuarantine {
+    count: number;
+    totalBytes: number;
+    reasons: {
+        reason: string;
+        count: number;
+    }[];
+    sample: string[];
+}
+/**
+ * The census, derived rather than declared.
+ *
+ * `keptFiles` equals the sum of every group's `fileCount`, `unclassified` included.
+ * Quarantined files are accounted separately, with their reasons. That the numbers sum
+ * is what turns "how much did the profile cover" from a question into a fact.
+ */
+export interface DataProfilePartition {
+    scannedFiles: number;
+    keptFiles: number;
+    keptMembers: number;
+    groups: number;
+    unclassifiedMembers: number;
+    unclassifiedFiles: number;
+    quarantine: DataProfileQuarantine;
+    /**
+     * Members more than one operation claimed after the last repair round. Removed from
+     * every claimant and swept into `unclassified`, never awarded by precedence — a
+     * machine finding, so it is here rather than in the agent's caveats.
+     */
+    contested?: {
+        members: number;
+        sample: string[];
+    };
+    /** True when the walk stopped at its file ceiling, so the census covers part of the tree. */
+    scanTruncated?: boolean;
+}
+/**
+ * One operation, keyed to the scanner TEMPLATES it addressed rather than the menu ids.
+ *
+ * Menu ids are per-scan ephemera; templates survive a re-scan, so the recipe can be
+ * re-resolved against a changed tree.
+ *
+ * `unclassified` is the one step no agent authored: it records the paths resolution swept
+ * because no operation claimed them. It is carried so a replay can tell a file the last
+ * profile already declined to classify from a file that is new to the tree — without it
+ * an unchanged tree re-absorbs as partial and wakes the agent to re-judge what it already
+ * judged.
+ */
+export interface DataProfileRecipeStep {
+    op: "use" | "split" | "merge" | "group" | "unclassified";
+    /** The templates this step addressed. Empty for an explicit path grouping. */
+    templates: string[];
+    /** Position of the split slot within the addressed set's slots. */
+    slotIndex?: number;
+    /** Slot values each resulting group claimed, for a value-mapped split. */
+    valueMapping?: {
+        groupId: string;
+        values: string[];
+    }[];
+    paths?: string[];
+    /** True when `paths` holds a prefix of the step's membership rather than all of it. */
+    pathsTruncated?: boolean;
+    groupIds: string[];
+}
 /**
  * The comparand identifying WHICH files a profile covered and whether the SAME BYTES
  * were profiled.
@@ -126,17 +373,6 @@ export interface DataProfileCoverage {
     total: number;
     unmatchedSample?: string[];
 }
-/**
- * One profiled input file's legacy drift signature. `fileId` is a path identity (two
- * files at the same path share it regardless of content), so `size` + `mtimeMs` are what
- * let a consumer notice the bytes behind a path changed. Superseded by
- * {@link DataProfileInputSignature}, and still readable on older rows.
- */
-export interface DataProfileInputFile {
-    fileId: string;
-    size: number;
-    mtimeMs: number;
-}
 /**
  * The profile snapshot stored in `cortex_analysis_state.data_profile_result`.
  *
@@ -148,25 +384,39 @@ export interface DataProfileInputFile {
  * It does NOT carry a record per input file. The workspace filesystem is the
  * authoritative file list — listing, grep, and the vector index all read the live tree —
  * so a copy here would be a stale duplicate on a row detoasted by every reader,
- * including the planner's, which reads a few hundred characters of it. `files` holds the
- * individually notable inputs; `kinds` holds the dataset's structure.
+ * including the planner's, which reads a few hundred characters of it. `groups` holds the
+ * dataset's structure, and the members an agent wrote about individually ride on the
+ * group they belong to.
+ *
+ * The writer emits `groups` and `dimensions`; `kinds`, `axes`, `files`, `coverage`, and
+ * `qualityAssessment` are what earlier eras wrote and stay readable. There is no version
+ * field: optionality is the compatibility mechanism, and a discriminator would be a
+ * second mechanism answering the same question.
  */
 export interface DataProfileResult {
     summary: string;
-    /** Individually described files — notable singletons, not the dataset's contents. */
-    files: DataProfileFile[];
-    /** The repeating sets the tree was grouped into. Absent on a pre-kinds snapshot. */
+    /** The resolved groups the tree partitions into, `unclassified` included. */
+    groups?: DataProfileGroup[];
+    /** What varies across the dataset, each with its observations. */
+    dimensions?: DataProfileDimension[];
+    /** One outcome per standard dimension the agent was asked to look for. */
+    probes?: DataProfileProbeReport[];
+    /** The census. Derived at resolution — kept equals the sum over groups. */
+    partition?: DataProfilePartition;
+    /** The operations that produced the groups, keyed to scanner templates. */
+    recipe?: DataProfileRecipeStep[];
+    /** What a planner must know, in the agent's words. Machine findings live in the structured fields. */
+    caveats?: string[];
+    /** Individually described files — notable singletons on a pre-groups snapshot. */
+    files?: DataProfileFile[];
+    /** The repeating sets the tree was grouped into, on a snapshot of the kinds era. */
     kinds?: DataProfileKind[];
-    /** What varies across those sets. Absent for the same reason as `kinds`. */
+    /** What varies across those sets, on a snapshot of the same era. */
     axes?: DataProfileAxis[];
-    /** The drift comparand. Preferred over `inputFileIds`, which it replaces. */
+    /** The drift comparand. */
     inputSignature?: DataProfileInputSignature;
-    /** How much of the scanned tree the kinds describe. Absent on pre-coverage snapshots. */
+    /** How much of the scanned tree the kinds describe, on a snapshot of the kinds era. Superseded by `partition`. */
     coverage?: DataProfileCoverage;
-    /** The legacy identity-list comparand, on rows written before the signature existed. */
-    inputFileIds?: string[];
-    /** The legacy per-file drift signature, on rows of the same era. */
-    inputFiles?: DataProfileInputFile[];
     /** ISO 8601 timestamp of profile completion. */
     profiledAt: string;
     /** Scientific domain (transcriptomics, cheminformatics, clinical, …). */
@@ -186,6 +436,7 @@ export interface DataProfileResult {
     accessions?: string[];
     /** Conditions, groups, comparisons, replicates, pairing. */
     experimentalDesign?: string;
+    /** Dataset-wide findings, on a snapshot of the era that recorded them. Superseded by `caveats`. */
     qualityAssessment?: DataProfileQualityAssessment;
 }
 /** The profile's lifecycle, as the ledger records it. */

package/dist/contracts/index.d.ts

@@ -6,7 +6,9 @@ export type { PlanStep, PresentationContent, PresentationPart, PlanPart, RunCard
 export type { EventSource, TextDeltaEvent, ToolStartedEvent, ToolFinishedEvent, FinishEvent, ChatErrorEvent, CortexChatEvent } from "./chat-events.js";
 export type { TokenUsageRollup } from "./usage.js";
 export { DATA_PROFILE_RUN_LITERAL } from "./data-profile.js";
-export type { DataProfileAxis, DataProfileCoverage, DataProfileFile, DataProfileInputFile, DataProfileInputSignature, DataProfileKind, DataProfileLifecycleStatus, DataProfileOrganism, DataProfileQualityAssessment, DataProfileResult, DataProfileSubjectSource, } from "./data-profile.js";
+export type { DataProfileAxis, DataProfileChecked, DataProfileCompanionCompleteness, DataProfileCoverage, DataProfileDimension, DataProfileFile, DataProfileGroup, DataProfileGroupSlot, DataProfileInputSignature, DataProfileKind, DataProfileLifecycleStatus, DataProfileMemberAnnotation, DataProfileObservation, DataProfileOrganism, DataProfilePartition, DataProfileProbeReport, DataProfileQualityAssessment, DataProfileQuarantine, DataProfileRecipeStep, DataProfileResult, DataProfileSubjectSource, } from "./data-profile.js";
+export { DIMENSION_CATEGORIES, DIMENSION_CATEGORY_IDS, DIMENSION_PROBE_IDS, DIMENSION_PROBES, GROUP_CATEGORIES, GROUP_CATEGORY_IDS, GROUP_ROLE_IDS, GROUP_ROLES, PROBE_OUTCOME_IDS, dimensionCategoryEntry, dimensionScope, groupCategoryEntry, } from "./profile-vocabulary.js";
+export type { DimensionCategory, DimensionCategoryEntry, DimensionProbe, DimensionProbeEntry, DimensionScope, DimensionTreatment, GroupCategory, GroupCategoryEntry, GroupRole, GroupRoleEntry, ProbeOutcome, } from "./profile-vocabulary.js";
 export type { TextPart, ToolCallPart, CortexPart, CortexMessage } from "./message.js";
 export { PART_REGISTRY, isTransient, isReconciling, isSidebarPart } from "./part-registry.js";
 export type { CortexChatPartType, PartDescriptor, PartEmitter, PartConsumer } from "./part-registry.js";

package/dist/contracts/index.js

@@ -1,6 +1,7 @@
 export { ORGAN_SYSTEMS, OrganSystemSchema, ORGAN_SYSTEM_LABELS, organSystemLabel } from "./organ-system.js";
 export { SEVERITIES, SeveritySchema } from "./severity.js";
 export { DATA_PROFILE_RUN_LITERAL } from "./data-profile.js";
+export { DIMENSION_CATEGORIES, DIMENSION_CATEGORY_IDS, DIMENSION_PROBE_IDS, DIMENSION_PROBES, GROUP_CATEGORIES, GROUP_CATEGORY_IDS, GROUP_ROLE_IDS, GROUP_ROLES, PROBE_OUTCOME_IDS, dimensionCategoryEntry, dimensionScope, groupCategoryEntry, } from "./profile-vocabulary.js";
 export { PART_REGISTRY, isTransient, isReconciling, isSidebarPart } from "./part-registry.js";
 export { AnalogyCoverageSchema, AnalogyReportSchema, AnalogyReportErrorSchema, AnalogicalReasonerOutputSchema } from "./analogy-report.js";
 export { CoverageSchema, RowCoverageSchema, EntitySchema, ClaimSupportSchema, ClaimEvidenceSchema, LiabilityBulletSchema, LiabilitySummarySchema, TractabilitySchema, IndicationsSchema, DrugInteractionsSchema, ClinicalTrialAttributionSchema, ClinicalDevelopmentSchema, OrganRiskRowSchema, OffTargetRowSchema, OffTargetPanelSchema, RegulatoryActionRowSchema, SafetyFlagSchema, SafetyProfileSchema, OffTissueRowSchema, OffTissueRiskSchema, ReferenceBiologyShape, EvidenceConflictsSchema, EvidenceTimelineSchema, TranslationalChainSchema, AdditionalEvidenceSchema, DiscoveryTrialsSchema, QualityGateStatusSchema, QualityGatesSchema, DerivedSchema, DossierSchema, DossierBodySchema, isDossier, dossierJsonSchema, SECTION_BLURBS, TargetAssessmentPhaseSchema, TargetAssessmentProgressEventSchema, } from "./target-dossier.js";

package/dist/contracts/profile-vocabulary.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The controlled vocabulary the profiler draws from, as data.
+ *
+ * One source, two readers: submit validation derives its enums from these lists and
+ * prompt assembly renders from the same entries, so the catalogue the agent is shown
+ * and the catalogue the validator enforces cannot diverge. Growth is an edit to these
+ * lists, measured by how often `other` is reached for.
+ *
+ * It lives in `contracts/` because the persisted profile carries these ids: a consumer
+ * rendering a stored group needs the category's meaning without importing the ledger,
+ * the schema module, or zod. Hosts do not extend it — the package owns the catalogue and
+ * versions it with the harness.
+ *
+ * Every category carries its nearest neighbour and the rule that separates them, because
+ * a category list without one is a list of labels an author picks by vibe. Every
+ * dimension category additionally carries a default treatment: whether a downstream step
+ * would TYPICALLY consume one value's files as a different substrate than another's.
+ * The agent follows the default and deviates only with a stated reason.
+ */
+export declare const GROUP_ROLE_IDS: readonly ["data", "metadata", "index", "documentation", "reference"];
+export type GroupRole = (typeof GROUP_ROLE_IDS)[number];
+export interface GroupRoleEntry {
+    readonly id: GroupRole;
+    readonly definition: string;
+}
+/**
+ * Companions (`.bai`/`.tbi`/per-file `.md5`) take no role — they attach to members. A
+ * checksum or inventory file spanning MANY members is not a companion but a member of
+ * its own, category `manifest`; `index` is for tables that exist to be joined against,
+ * never for binary sidecars.
+ */
+export declare const GROUP_ROLES: readonly GroupRoleEntry[];
+export declare const GROUP_CATEGORY_IDS: readonly ["sequencing-reads", "alignment", "variant-calls", "copy-number", "structural-variants", "association-results", "regions-signal", "expression-matrix", "single-cell-matrix", "methylation", "proteomics", "metabolomics", "cytometry", "chemical-structures", "imaging", "clinical-table", "sample-annotation", "code", "document", "manifest", "reference-data", "other"];
+export type GroupCategory = (typeof GROUP_CATEGORY_IDS)[number];
+export interface GroupCategoryEntry {
+    readonly id: GroupCategory;
+    readonly definition: string;
+    /** The nearest neighbour and the rule that separates them. */
+    readonly note: string;
+}
+/**
+ * Coarse on purpose — a free `subtype` refines below the category. Content beats shape:
+ * a beta-value matrix is methylation whatever its layout, and a MAF is variant-calls
+ * whatever its extension. Grain and meaning decide.
+ */
+export declare const GROUP_CATEGORIES: readonly GroupCategoryEntry[];
+export declare const DIMENSION_CATEGORY_IDS: readonly ["subject", "sample", "organism-species", "model-system", "cohort-arm", "disease-state", "treatment", "timepoint", "tissue-site", "cell-type", "genetic-perturbation", "sex", "age-group", "developmental-stage", "environment", "assay-modality", "assay-target", "variant-origin", "sample-pairing", "processing-level", "assay-version", "batch", "replicate", "tool-variant", "library-prep", "data-partition", "other"];
+export type DimensionCategory = (typeof DIMENSION_CATEGORY_IDS)[number];
+export type DimensionScope = "biological" | "technical";
+/**
+ * What the substrate test says for this category by default. `split` means one value's
+ * files are typically a different substrate to a downstream step, so the set is split
+ * into groups; `dimension` means the values are variants of one substrate and stay a
+ * slot, possibly bound to a dimension.
+ */
+export type DimensionTreatment = "split" | "dimension";
+export interface DimensionCategoryEntry {
+    readonly id: DimensionCategory;
+    readonly scope: DimensionScope;
+    readonly definition: string;
+    readonly defaultTreatment: DimensionTreatment;
+    /** Why the default reads the way it does, and the nearest neighbour it is not. */
+    readonly note: string;
+}
+export declare const DIMENSION_CATEGORIES: readonly DimensionCategoryEntry[];
+export declare const DIMENSION_PROBE_IDS: readonly ["subject", "sample", "cohort-arm", "timepoint", "batch"];
+export type DimensionProbe = (typeof DIMENSION_PROBE_IDS)[number];
+/**
+ * A probe outcome, exactly one per probe.
+ *
+ * `not-found` is a correct and complete answer once the searched set is named — that is
+ * what removes the completeness pressure that otherwise invents dimensions. `attested`
+ * records prose-only evidence and can never justify a split.
+ */
+export declare const PROBE_OUTCOME_IDS: readonly ["found", "not-found", "found-but-constant", "attested"];
+export type ProbeOutcome = (typeof PROBE_OUTCOME_IDS)[number];
+export interface DimensionProbeEntry {
+    readonly id: DimensionProbe;
+    /** Where a `found` typically comes from. */
+    readonly guidance: string;
+}
+/**
+ * The only dimensions the agent actively looks for. The searchable set is bounded and
+ * named: files in metadata- or documentation-role groups plus clinical-table and
+ * sample-annotation members, up to about ten files. Everything off this list is recorded
+ * only when encountered during ordinary orientation reading.
+ *
+ * Assay-modality and replicate are deliberately absent: varying modality is already
+ * surfaced by group categories, and probing for replicates invites inferring replicate
+ * structure from sample counts, which is fabrication by another name.
+ */
+export declare const DIMENSION_PROBES: readonly DimensionProbeEntry[];
+export declare function groupCategoryEntry(id: GroupCategory): GroupCategoryEntry;
+export declare function dimensionCategoryEntry(id: DimensionCategory): DimensionCategoryEntry;
+/**
+ * The scope a dimension takes.
+ *
+ * Derived from the category for everything in the catalogue. `other` is by definition
+ * outside it, so there is nothing to derive from and the scope is the agent's to declare:
+ * a biological thing that varies and has no category is still biological, and pinning
+ * every `other` to technical would misfile it. Undeclared, it defaults to technical.
+ */
+export declare function dimensionScope(id: DimensionCategory, declared?: DimensionScope): DimensionScope;