@owlmeans/viable-common 0.0.44 → 0.0.45

package/src/connect/references/types.local.ts

@@ -0,0 +1,5 @@
+import type { EntrypointReference } from '@owlmeans/context'
+import type { RegisteredEntrypoint, RequestShape } from '@owlmeans/entrypoint'
+
+export interface ConnectReference<Request extends RequestShape, Response>
+  extends EntrypointReference<RegisteredEntrypoint<Request, Response>> {}

package/src/connect/references/types.ts

@@ -0,0 +1,73 @@
+import type { ConnectProjectBranding, ConnectProjectBrandingSave } from '../branding/types.js'
+import type {
+  ConnectConvertCreateBody, ConnectConvertProceedBody, ConnectConvertStartBody, ConversionStatusView, ConvertCheck
+} from '../conversion/types.js'
+import type { ConnectKitApplyBody, ConnectKitApplyResult, ConnectKitDescribe } from '../kit/types.js'
+import type { ConnectInquiryAnswerBody, ConnectOp, ConnectOpResult, ConnectOpSubmission } from '../ops/types.js'
+import type { ConnectPipelineParams, ConnectPipelineResumeBody, ConnectPipelineState } from '../pipeline/types.js'
+import type {
+  ConnectAttachBody, ConnectConfirmBody, ConnectCreateBody, ConnectModifyBody, ConnectProjectStatus,
+  ConnectProjectSummary, ConnectStoryStatus
+} from '../project/types.js'
+import type { ConnectPullQuery, ConnectSessionOpen, ConnectSessionParams, ConnectSessionView } from '../session/types.js'
+import type { ConnectReference } from './types.local.js'
+
+export interface ConnectReferences {
+  session: {
+    open: ConnectReference<{ body: ConnectSessionOpen }, ConnectSessionView>
+    openDelegated: ConnectReference<{ body: ConnectSessionOpen }, ConnectSessionView>
+    close: ConnectReference<{ params: ConnectSessionParams }, ConnectSessionView>
+  }
+  op: {
+    pull: ConnectReference<{ params: ConnectSessionParams, query: ConnectPullQuery }, ConnectOp[]>
+    submit: ConnectReference<{
+      params: { sessionId: string, opId: string }, body: ConnectOpResult
+    }, ConnectOpSubmission>
+  }
+  project: {
+    create: ConnectReference<{ body: ConnectCreateBody }, ConnectProjectStatus>
+    confirm: ConnectReference<{ params: { id: string }, body: ConnectConfirmBody }, ConnectProjectStatus>
+    list: ConnectReference<{}, ConnectProjectSummary[]>
+    status: ConnectReference<{ params: { id: string } }, ConnectProjectStatus>
+    attach: ConnectReference<{ body: ConnectAttachBody }, ConnectProjectStatus>
+    reinit: ConnectReference<{ params: { id: string } }, ConnectProjectStatus>
+    modify: ConnectReference<{ params: { id: string }, body: ConnectModifyBody }, ConnectProjectStatus>
+    kit: {
+      describe: ConnectReference<{ params: { id: string } }, ConnectKitDescribe>
+      apply: ConnectReference<{ params: { id: string }, body: ConnectKitApplyBody }, ConnectKitApplyResult>
+    }
+    branding: {
+      get: ConnectReference<{ params: { id: string } }, ConnectProjectBranding>
+      save: ConnectReference<{
+        params: { id: string }, body: ConnectProjectBrandingSave
+      }, ConnectProjectBranding>
+    }
+  }
+  story: {
+    status: ConnectReference<{ params: { id: string, storyId: string } }, ConnectStoryStatus>
+  }
+  files: {
+    list: ConnectReference<{ params: { id: string } }, string[]>
+  }
+  convert: {
+    create: ConnectReference<{ body: ConnectConvertCreateBody }, ConversionStatusView>
+    check: ConnectReference<{ params: { id: string } }, ConvertCheck>
+    start: ConnectReference<{ params: { id: string }, body: ConnectConvertStartBody }, ConversionStatusView>
+    proceed: ConnectReference<{
+      params: { id: string }, body: ConnectConvertProceedBody
+    }, ConversionStatusView>
+    status: ConnectReference<{ params: { id: string } }, ConversionStatusView>
+    purge: ConnectReference<{ params: { id: string } }, ConversionStatusView>
+  }
+  inquiry: {
+    answer: ConnectReference<{
+      params: { id: string, inquiryId: string }, body: ConnectInquiryAnswerBody
+    }, unknown>
+  }
+  pipeline: {
+    state: ConnectReference<{ params: ConnectPipelineParams }, ConnectPipelineState>
+    resume: ConnectReference<{
+      params: ConnectPipelineParams, body: ConnectPipelineResumeBody
+    }, ConnectPipelineState>
+  }
+}

package/src/connect/references.ts

@@ -1,7 +1,18 @@
 import { entrypointRef } from '@owlmeans/entrypoint'
 import { connect } from './consts.js'
-import type { ConnectOp, ConnectOpResult } from './ops.js'
-import type { ConnectAttachBody, ConnectConfirmBody, ConnectCreateBody, ConnectConvertCreateBody, ConnectConvertProceedBody, ConnectConvertStartBody, ConnectInquiryAnswerBody, ConnectKitApplyBody, ConnectKitApplyResult, ConnectKitDescribe, ConnectModifyBody, ConnectOpSubmission, ConnectPipelineParams, ConnectPipelineResumeBody, ConnectPipelineState, ConnectProjectBranding, ConnectProjectBrandingSave, ConnectProjectStatus, ConnectProjectSummary, ConnectPullQuery, ConnectSessionOpen, ConnectSessionParams, ConnectSessionView, ConnectStoryStatus, ConversionStatusView, ConvertCheck, ConnectReferences } from './types.js'
+import type { ConnectProjectBranding, ConnectProjectBrandingSave } from './branding/types.js'
+import type {
+  ConnectConvertCreateBody, ConnectConvertProceedBody, ConnectConvertStartBody, ConversionStatusView, ConvertCheck
+} from './conversion/types.js'
+import type { ConnectKitApplyBody, ConnectKitApplyResult, ConnectKitDescribe } from './kit/types.js'
+import type { ConnectInquiryAnswerBody, ConnectOp, ConnectOpResult, ConnectOpSubmission } from './ops/types.js'
+import type { ConnectPipelineParams, ConnectPipelineResumeBody, ConnectPipelineState } from './pipeline/types.js'
+import type {
+  ConnectAttachBody, ConnectConfirmBody, ConnectCreateBody, ConnectModifyBody, ConnectProjectStatus,
+  ConnectProjectSummary, ConnectStoryStatus
+} from './project/types.js'
+import type { ConnectReferences } from './references/types.js'
+import type { ConnectPullQuery, ConnectSessionOpen, ConnectSessionParams, ConnectSessionView } from './session/types.js'
 
 /**
  * Typed references for adapter packages that address the connector dynamically.  Applications

package/src/connect/schemas.ts

@@ -4,17 +4,16 @@ import {
   CONNECT_BRANDING_COPYRIGHT_MAX, CONNECT_BRANDING_GOOGLE_TAG_MAX,
   CONNECT_BRANDING_ORGANIZATION_MAX, CONNECT_BRANDING_URL_MAX, CONNECT_INQUIRY_MAX_TEXT,
   ConnectHarness, ConnectLlm, ConnectOpErrorKind, ConnectSessionStatus, ConnectTarget,
-  ConnectTransport, ModelTaskResultKind, ModelTier
+  ConnectTransport, ModelTaskResultKind
 } from './consts.js'
-import type { ConnectOpResult, InquiryAnswerPayload } from './ops.js'
-import type {
-  ConnectAttachBody, ConnectConfirmBody, ConnectConvertCreateBody, ConnectConvertProceedBody,
-  ConnectConvertStartBody,
-  ConnectCreateBody, ConnectLlmBody, ConnectModifyBody, ConnectPipelineParams,
-  ConnectPipelineResumeBody, ConnectProjectBrandingSave, ConnectProjectLlmBody, ConnectSession,
-  ConnectSessionOpen, ConnectPullQuery, ConnectSessionParams, ConnectKitApplyBody, ConnectKitApplyResult,
-  ConnectKitDescribe, PlanningKitView
-} from './types.js'
+import type { ConnectProjectBrandingSave } from './branding/types.js'
+import type { ConnectConvertCreateBody, ConnectConvertProceedBody, ConnectConvertStartBody } from './conversion/types.js'
+import type { ConnectKitApplyBody, ConnectKitApplyResult, ConnectKitDescribe, PlanningKitView } from './kit/types.js'
+import type { ConnectOpResult, InquiryAnswerPayload } from './ops/types.js'
+import type { ConnectPipelineParams, ConnectPipelineResumeBody } from './pipeline/types.js'
+import type { ConnectAttachBody, ConnectConfirmBody, ConnectCreateBody, ConnectModifyBody } from './project/types.js'
+import type { ConnectPullQuery, ConnectSession, ConnectSessionOpen, ConnectSessionParams } from './session/types.js'
+import type { ConnectLlmBody, ConnectProjectLlmBody } from './settings/types.js'
 
 /**
  * A nullable ENUM carries `null` as one of its values.
@@ -478,6 +477,3 @@ export const ModelTaskResultSchema = {
   required: ['taskId', 'kind'],
   additionalProperties: false,
 } as any
-
-/** Tier → the model the parent will run it on. Free-form; display only. */
-export const ModelTierValues = Object.values(ModelTier)

package/src/connect/session/types.ts

@@ -0,0 +1,81 @@
+import type {
+  ConnectExecutor, ConnectHarness, ConnectLlm, ConnectSessionStatus, ConnectTarget, ConnectTransport, ModelTier
+} from '../consts.js'
+
+/**
+ * What a parent agent can do, as it reports itself.
+ *
+ * `tiers` is what decides whether the local-LLM mode is usable at all: a parent that names no
+ * model for a tier still gets tasks, clamped to the nearest tier it does offer.
+ */
+export interface ConnectCapabilities {
+  harness: ConnectHarness
+  /** Tier → the parent's own name for the model it will run that tier on. Display only. */
+  tiers: Partial<Record<ModelTier, string>>
+  /** Whether the parent can run a task in an isolated subagent rather than its own conversation. */
+  subagents: boolean
+  /** Whether the parent can ask for low reasoning effort explicitly. */
+  effortControl: boolean
+  /** Which operation kinds this connector will execute. */
+  executors: ConnectExecutor[]
+  /** What the local machine has, learned from the configure op. Absent until one has run. */
+  services?: ConnectServices
+}
+
+/** What a local machine actually provides. Reported by the connector, never assumed. */
+export interface ConnectServices {
+  db: boolean
+  valkey: boolean
+}
+
+export interface ConnectSession {
+  id?: string
+  profileId: string
+  entityId: string
+  projectId?: string
+  /** The absolute directory the target lives in, for a local target. Identity for supersede. */
+  projectDir?: string
+  target: ConnectTarget
+  llm: ConnectLlm
+  harness: ConnectHarness
+  clientVersion: string
+  capabilities: ConnectCapabilities
+  status: ConnectSessionStatus
+  /** How the connector is receiving operations right now. */
+  transport?: ConnectTransport
+  openedAt: Date
+  lastSeenAt: Date
+  closedAt?: Date
+  createdAt: Date
+  updatedAt?: Date
+}
+
+/** What a connector asks for when it attaches. */
+export interface ConnectSessionOpen {
+  projectId?: string
+  projectDir?: string
+  target: ConnectTarget
+  harness: ConnectHarness
+  clientVersion: string
+  capabilities: ConnectCapabilities
+}
+
+export interface ConnectSessionParams {
+  sessionId: string
+}
+
+export interface ConnectSessionView {
+  id: string
+  target: ConnectTarget
+  llm: ConnectLlm
+  projectId?: string
+  status: ConnectSessionStatus
+  /** Operations waiting for this session right now. */
+  pending: number
+  expiresAt: string
+}
+
+export interface ConnectPullQuery {
+  /** Seconds to wait before answering; clamped to the pull ceiling. */
+  wait?: number
+}

package/src/connect/settings/types.ts

@@ -0,0 +1,52 @@
+import type { ConnectLlm } from '../consts.js'
+
+/** The per-profile connector preference. */
+export interface ConnectProfileSettings {
+  llmMode: ConnectLlm
+}
+
+export interface ConnectProfileSettingsView extends ConnectProfileSettings {
+  /** Whether the organization's plan allows the local-LLM mode at all. */
+  canUseLocal: boolean
+  /**
+   * The profile's preference for who performs a CONVERSION's model calls.
+   *
+   * Its own setting rather than a reading of `llmMode`, because the two answer for different
+   * work: a conversion reads somebody else's whole repository, which is the one case where handing
+   * the inference to the parent agent is the cheap default rather than the experimental option.
+   *
+   * OPTIONAL: the two converter fields are answered by a platform build that does not exist yet,
+   * and this package is consumed by the platform through a workspace link rather than a published
+   * range — a required field here is a compile error in every handler that already returns this
+   * view. Tightened to required once the platform's conversion handlers fill them.
+   */
+  converterLlmMode?: ConnectLlm
+  /** Whether this caller may run a conversion's model calls on the parent agent. */
+  canUseConverterLocal?: boolean
+}
+
+export interface ConnectLlmBody {
+  llmMode: ConnectLlm
+}
+
+/** The per-project override, and what it resolves to. */
+export interface ConnectProjectSettings {
+  /** `null` means "inherit the profile setting". */
+  llmMode: ConnectLlm | null
+  effective: ConnectLlm
+  canUseLocal: boolean
+  /**
+   * The project's converter override; `null` inherits the profile's.
+   *
+   * Optional on the same forward-compatibility grounds as
+   * {@link ConnectProfileSettingsView.converterLlmMode} — absent from an answer written before the
+   * platform's conversion handlers land, and never to be read as a value.
+   */
+  converterLlmMode?: ConnectLlm | null
+  /** What the override, the profile and the platform's own floor actually resolve to. */
+  converterEffective?: ConnectLlm
+}
+
+export interface ConnectProjectLlmBody {
+  llmMode: ConnectLlm | null
+}

package/src/convert/analysis/types.ts

@@ -0,0 +1,89 @@
+import type { ProjectArea } from '../../areas/consts.js'
+import type { StoryKind } from '../../ba/consts.js'
+import type { PurposeEvidenceSource, TaxonomyKind } from '../consts.js'
+import type { OriginProof } from '../types.js'
+
+export interface PurposeInference {
+  purpose: string
+  audience: string
+  source: PurposeEvidenceSource
+  confidence: number
+  evidence: OriginProof[]
+}
+
+/** A flow the ORIGIN implements, before it is turned into stories. */
+export interface OriginFlow {
+  id: string
+  name: string
+  actor: string
+  area: ProjectArea
+  steps: string[]
+  /** Whether the extracted story list covers it. An uncovered flow is a gap the user is shown. */
+  covered: boolean
+  kind: 'ui' | 'job' | 'cli'
+  proofs: OriginProof[]
+}
+
+/** One entry of the restored story list, in the order the records are created in. */
+export interface ConversionStoryRef {
+  code: string
+  story: string
+  area: ProjectArea
+  kind: ConversionStoryKind
+  ordinal: number
+}
+
+/**
+ * A restored story with the origin code that proves it.
+ *
+ * `complexity` is what the per-story price band is scaled by — derived from the proofs and the
+ * algorithms, never asked of a model, so two runs over the same extraction price identically.
+ */
+export interface StoryProof {
+  code: string
+  narrative: string
+  specification: string
+  ux: string
+  ui: string
+  proofs: OriginProof[]
+  algorithms: { name: string, steps: string[], proof: OriginProof }[]
+  complexity: number
+}
+
+export interface AreaAlignment {
+  areas: {
+    area: ProjectArea
+    roles: string[]
+    permissions: string[]
+    stories: string[]
+  }[]
+  /** Roles or permissions no area claimed. Recorded; never silently dropped. */
+  unmapped: string[]
+}
+
+/** The machine-readable graph the manager's conversion diagram is drawn from. */
+export interface StructureSummary {
+  nodes: { id: string, label: string, kind: TaxonomyKind | 'package' | 'area' }[]
+  edges: { from: string, to: string, label?: string }[]
+}
+
+export interface OriginFlowList {
+  flows: OriginFlow[]
+}
+
+/** What the origin's styles say about its design, in the terms the target's theme is written in. */
+export interface DesignInference {
+  concept: string
+  palette: string[]
+  radius?: string
+  font?: string
+}
+
+/**
+ * What KIND of story a conversion produced.
+ *
+ * The analysis half of a conversion produces exactly the two kinds an ordinary initialization
+ * does; a conversion adds one more — a `coverage` story, written so an area the origin serves but
+ * the flow never reaches still has something in it.
+ */
+export type ConversionStoryKind = StoryKind | 'coverage'

package/src/convert/{consts.local.ts → census/consts.local.ts}

@@ -1,4 +1,4 @@
-import { FileClass } from './consts.js'
+import { FileClass } from '../consts.js'
 
 /**
  * Extension → class, for the extensions that decide a file on their own.

package/src/convert/census/types.ts

@@ -0,0 +1,181 @@
+import type { DumpKind, EntropyClass, FileClass, SizeClass, WorkspaceKind } from '../consts.js'
+
+/**
+ * The census's file classification: pure, deterministic derivations over the conversion
+ * vocabulary.
+ *
+ * Everything here answers the same way for the same input, in every runtime, forever — which is
+ * what makes the documents a conversion writes byte-stable across two runs, and therefore what
+ * makes the prompt cache prefix they are injected into actually hit. Nothing here reads a file,
+ * calls a model or looks at a clock.
+ */
+export interface CensusHelper {
+  /** Which {@link SizeClass} a byte count falls in. Boundaries are exclusive upper bounds. */
+  sizeClassOf: (bytes: number) => SizeClass
+  /**
+   * What one file of the origin is.
+   *
+   * Location outranks the tail wherever it says more — a `.ts` under `__tests__/` is a test, a
+   * `.json` under `seed/` is data — but only where it says more. The seed/dump rule therefore runs
+   * AFTER the extension table and applies only to {@link DATA_OVERRIDABLE}: asked first, it answered
+   * `Data` for every path merely containing the word (`tests/fixtures/user.ts`, `src/seedUsers.ts`,
+   * `src/exportReport.ts`), which is the census's source budget spent on the wrong files twice over.
+   */
+  fileClassOf: (path: string, ext: string) => FileClass
+  /**
+   * The binary verdict a path already carries, or `null` for a file that has to be probed.
+   *
+   * The three executors that walk a tree — the library-local helper, the publisher and the connector
+   * SDK — must answer the same verdict for the same file, and a probe alone does not: a small `.ico`
+   * with no NUL in its first bytes reads as text, so a census run on a laptop and the same census
+   * run in the slot disagreed about the same repository. The tail is asked first and the probe only
+   * where the tail says nothing, which is also why the probe is affordable at census scale — the
+   * extensions above are the bulk of any repository.
+   *
+   * The extension is taken exactly the way `path.extname` takes it, because two of the three callers
+   * used to: the last dot of the last SEGMENT, and nothing for a name with no dot or for a dotfile.
+   */
+  binaryByExtension: (path: string) => boolean | null
+  /**
+   * How usable a file's head is as evidence.
+   *
+   * The printable ratio over the sampled head, and nothing cleverer: the question is only whether a
+   * model can read it. A minified bundle is printable and useless, so a second rule catches the
+   * shape that gives it away — very long lines with almost no whitespace.
+   */
+  entropyClassOf: (head: string) => EntropyClass
+  /** Whether a path names bulk data — an export, not the application's own data. */
+  isBulkPath: (path: string) => boolean
+  /** Whether a path names seed data — what the application needs in order to make sense. */
+  isSeedPath: (path: string) => boolean
+}
+
+/**
+ * {@link FileStat} is declared in `../../slot/types.js`, not here.
+ *
+ * It is the element of a `statTree` answer, and a slot command's result shape belongs to the slot
+ * vocabulary the publisher and the connector both implement. Redeclaring it beside the census that
+ * consumes it would give the root barrel two `FileStat`s and the two would drift the first time
+ * one end added a field.
+ */
+
+/** One file, as the census classified it. `read` says whether its head was actually opened. */
+export interface FileCensusEntry {
+  path: string
+  bytes: number
+  ext: string
+  cls: FileClass
+  size: SizeClass
+  entropy?: EntropyClass
+  read: boolean
+}
+
+/** A package manifest found in the origin, and what it declares. */
+export interface InventoryPackage {
+  name?: string
+  path: string
+  /** The manifest file itself, root-relative — `package.json`, `pom.xml`, `go.mod`, … */
+  manifest: string
+  /** `member` for a package a workspace root declares; otherwise the workspace kind it declares. */
+  kind: WorkspaceKind | 'member'
+  deps: string[]
+  scripts: Record<string, string>
+  /** Whether something in the tree actually reaches it. See {@link UnlinkedRef}. */
+  linked: boolean
+}
+
+export interface WorkspaceMember {
+  name?: string
+  path: string
+  /** The manifest that declared this member. */
+  declaredBy: string
+  present: boolean
+}
+
+export interface SubmoduleRef {
+  path: string
+  url?: string
+  present: boolean
+}
+
+/**
+ * A directory holding code that nothing in the workspace declares, or a declaration with nothing
+ * behind it.
+ *
+ * Reported rather than silently included: code the build never sees is code the origin does not
+ * run, and converting it produces stories for behaviour the application does not have.
+ */
+export interface UnlinkedRef {
+  path: string
+  reason: 'not-a-member' | 'missing-submodule' | 'declared-not-present'
+}
+
+export interface WorkspaceReport {
+  kind: WorkspaceKind
+  globs: string[]
+  members: WorkspaceMember[]
+  submodules: SubmoduleRef[]
+  unlinked: UnlinkedRef[]
+}
+
+/** A data file the origin carries that is too large, or too generated, to become seed data. */
+export interface DumpRecord {
+  path: string
+  kind: DumpKind
+  bytes: number
+  format: string
+  rows?: number
+  /** At most {@link DUMP_SAMPLE_LINES} lines, read from the head. Never the whole file. */
+  sample: string[]
+  columns?: string[]
+}
+
+/** A small data file the code itself references — the data the application needs to make sense. */
+export interface SeedRecord {
+  name: string
+  path: string
+  bytes: number
+  format: string
+  rows?: number
+  /** The source files that name it. The proof that it is seed rather than an export. */
+  referencedBy: string[]
+  carried: boolean
+  /** Where it was written in the target, once carried. */
+  target?: string
+}
+
+export interface InventorySummary {
+  root: string
+  files: number
+  bytes: number
+  read: number
+  skipped: number
+  /** A census that hit {@link CENSUS_MAX_ENTRIES}. Everything downstream must say so. */
+  truncated: boolean
+  byClass: Record<FileClass, number>
+  bySize: Record<SizeClass, number>
+  extensions: { ext: string, files: number, bytes: number }[]
+  packages: InventoryPackage[]
+  workspace: WorkspaceReport
+  dumps: DumpRecord[]
+  seeds: SeedRecord[]
+  manifests: string[]
+  vcs: { git: boolean, submodules: number }
+  version: number
+  takenAt: string
+}
+
+/** One data file, classified by the model where the path and the size alone were not enough. */
+export interface SeedDetectionItem {
+  path: string
+  name: string
+  /** Whether it is data the application needs rather than an export of what it produced. */
+  seed: boolean
+  /** Whether it should be carried into the target. */
+  carry: boolean
+  reason: string
+}
+
+export interface SeedDetection {
+  items: SeedDetectionItem[]
+}

package/src/convert/census.ts

@@ -0,0 +1,95 @@
+import { EntropyClass, FileClass, SizeClass, SIZE_CLASS_BOUNDS } from './consts.js'
+import {
+  BINARY_EXTENSIONS, BULK_HINTS, DATA_AMBIGUOUS_EXT, DATA_OVERRIDABLE, EXT_CLASS, GENERATED_SEGMENTS, LOCK_NAMES,
+  MANIFEST_NAMES, SEED_HINTS, TEST_SEGMENTS, TEXT_EXTENSIONS
+} from './census/consts.local.js'
+import type { CensusHelper } from './census/types.js'
+
+export const createCensusHelper = (): CensusHelper => {
+  const sizeClassOf = (bytes: number): SizeClass => {
+    if (bytes < SIZE_CLASS_BOUNDS[SizeClass.Tiny]) return SizeClass.Tiny
+    if (bytes < SIZE_CLASS_BOUNDS[SizeClass.Small]) return SizeClass.Small
+    if (bytes < SIZE_CLASS_BOUNDS[SizeClass.Medium]) return SizeClass.Medium
+    if (bytes < SIZE_CLASS_BOUNDS[SizeClass.Large]) return SizeClass.Large
+
+    return SizeClass.Huge
+  }
+
+  const segmentsOf = (path: string): string[] => path.split('/').filter(part => part !== '')
+
+  const hasSegment = (path: string, of: string[]): boolean =>
+    segmentsOf(path).some(part => of.includes(part.toLowerCase()))
+
+  const fileClassOf = (path: string, ext: string): FileClass => {
+    const lower = path.toLowerCase()
+    const base = segmentsOf(lower).pop() ?? lower
+    const tail = (ext.startsWith('.') ? ext.slice(1) : ext).toLowerCase()
+
+    if (LOCK_NAMES.includes(base)) return FileClass.Lock
+    if (hasSegment(lower, GENERATED_SEGMENTS)) return FileClass.Generated
+    if (MANIFEST_NAMES.includes(base)) return FileClass.Manifest
+    if (hasSegment(lower, TEST_SEGMENTS) || base.includes('.test.') || base.includes('.spec.')) {
+      return FileClass.Test
+    }
+    if (base.startsWith('.env')) return FileClass.Config
+
+    const byExt = EXT_CLASS[tail] ?? FileClass.Unknown
+    if (
+      (DATA_OVERRIDABLE.includes(byExt) || DATA_AMBIGUOUS_EXT.includes(tail))
+      && (isSeedPath(lower) || isBulkPath(lower))
+    ) {
+      return FileClass.Data
+    }
+
+    return byExt
+  }
+
+  const binaryByExtension = (path: string): boolean | null => {
+    const base = segmentsOf(path).pop() ?? path
+    const dot = base.lastIndexOf('.')
+    if (dot < 1) return null
+    const ext = base.slice(dot).toLowerCase()
+
+    return TEXT_EXTENSIONS.includes(ext) ? false : BINARY_EXTENSIONS.includes(ext) ? true : null
+  }
+
+  const entropyClassOf = (head: string): EntropyClass => {
+    if (head.length < 1) return EntropyClass.Text
+
+    let printable = 0
+    let whitespace = 0
+    for (const char of head) {
+      const code = char.codePointAt(0) ?? 0
+      if (code === 9 || code === 10 || code === 13 || code === 32) {
+        ++whitespace
+        ++printable
+      } else if (code >= 32 && code !== 127) {
+        ++printable
+      }
+    }
+
+    const ratio = printable / head.length
+    if (ratio < 0.85) return EntropyClass.Opaque
+    // Prose, code and markup all break lines and indent. A body that does neither is minified,
+    // encoded or packed — printable, and not something a model can reason over.
+    if (whitespace / head.length < 0.05) return EntropyClass.Dense
+
+    return EntropyClass.Text
+  }
+
+  const matchesHint = (path: string, hints: string[]): boolean => {
+    const lower = path.toLowerCase()
+    if (hasSegment(lower, hints)) return true
+    const base = segmentsOf(lower).pop() ?? lower
+
+    return hints.some(hint => base.includes(hint))
+  }
+
+  const isBulkPath = (path: string): boolean => matchesHint(path, BULK_HINTS)
+
+  const isSeedPath = (path: string): boolean => matchesHint(path, SEED_HINTS)
+
+  return { sizeClassOf, fileClassOf, binaryByExtension, entropyClassOf, isBulkPath, isSeedPath }
+}
+
+export const censusHelper = createCensusHelper()

package/src/convert/consts.ts

@@ -656,3 +656,8 @@ export const CONVERSION_INQUIRY = {
   areasMap: 'convert.areas.map',
   originRelocate: 'convert.origin.relocate',
 } as const
+
+/** The reasons a convertibility verdict can carry, for a consumer building its own enum check. */
+export const ConvertibilityReasonValues = Object.values(ConvertibilityReason)
+export const ConvertibilityVerdictValues = Object.values(ConvertibilityVerdict)
+export const EstimateSliceValues = Object.values(EstimateSlice)