alphacouncil-agent 0.9.2 → 1.0.0

package/mcp/lib/xbrl-series.mjs

@@ -0,0 +1,339 @@
+/**
+ * XBRL series plumbing shared by every derived fundamental.
+ *
+ * Nothing here knows what a metric means. It answers four mechanical questions about SEC
+ * Company Facts documents -- which periods exist for a concept, which of them align, when the
+ * newest input became public, and how a computed number is packaged with its lineage -- and
+ * `fundamentals.mjs` builds the operating figures on top. Separating them keeps the alignment
+ * rules in one place: a metric that quietly aligned differently from its neighbours would be
+ * the kind of defect no test asks about.
+ *
+ * All network access goes through sec.mjs, which owns the throttle and the User-Agent.
+ */
+
+import { CONCEPTS, annualSeries } from "./sec.mjs";
+import { sha256 } from "./personas-v3/canonical.mjs";
+
+export const TOOL_ID = "sec_fundamentals";
+export const TOOL_VERSION = "1.0.0";
+const HASH_DOMAIN = "alphacouncil.fundamentals.sec-companyfacts.v1";
+
+const finite = (value) => typeof value === "number" && Number.isFinite(value);
+export const decimal = (value) => Number(value.toFixed(6));
+const DAY_MS = 86_400_000;
+export const daysBetween = (from, to) => Math.round((Date.parse(to) - Date.parse(from)) / DAY_MS);
+
+/** Two facts claiming the same period may not disagree by more than this. */
+export const MAX_ALIGNMENT_DRIFT_DAYS = 45;
+
+/**
+ * Concept aliases, ordered by preference, on top of the ones sec.mjs already publishes.
+ *
+ * Aliases inside one entry are the same economic quantity under different taxonomies. They
+ * are never a fallback to a different concept: total liabilities is not reconstructed from
+ * an equity subtraction, and a missing depreciation tag stays missing.
+ */
+export const FUNDAMENTAL_CONCEPTS = Object.freeze({
+  revenue: { tags: CONCEPTS.revenue, unit: "USD" },
+  net_income: { tags: CONCEPTS.netIncome, unit: "USD" },
+  operating_income: { tags: CONCEPTS.operatingIncome, unit: "USD" },
+  capex: { tags: CONCEPTS.capex, unit: "USD" },
+  equity: { tags: CONCEPTS.equity, unit: "USD" },
+  depreciation_amortisation: {
+    tags: [
+      "DepreciationDepletionAndAmortization",
+      "DepreciationAmortizationAndAccretionNet",
+      "DepreciationAndAmortization",
+      "Depreciation",
+    ],
+    unit: "USD",
+  },
+  current_assets: { tags: ["AssetsCurrent"], unit: "USD" },
+  total_liabilities: { tags: ["Liabilities"], unit: "USD" },
+  goodwill: { tags: ["Goodwill"], unit: "USD" },
+  intangibles: { tags: ["IntangibleAssetsNetExcludingGoodwill", "FiniteLivedIntangibleAssetsNet"], unit: "USD" },
+  cash: {
+    tags: [
+      "CashAndCashEquivalentsAtCarryingValue",
+      "CashCashEquivalentsRestrictedCashAndRestrictedCashEquivalents",
+    ],
+    unit: "USD",
+  },
+  // Debt buckets are non-overlapping by construction so they can be summed. `debt_combined`
+  // is the whole of it in one tag and wins outright when a filer publishes it.
+  debt_combined: { tags: ["DebtLongtermAndShorttermCombinedAmount"], unit: "USD" },
+  debt_long_term_noncurrent: { tags: ["LongTermDebtNoncurrent", "LongTermDebtAndCapitalLeaseObligations"], unit: "USD" },
+  debt_long_term_current: { tags: ["LongTermDebtCurrent", "LongTermDebtAndCapitalLeaseObligationsCurrent"], unit: "USD" },
+  debt_short_term: { tags: ["ShortTermBorrowings", "OtherShortTermBorrowings", "CommercialPaper"], unit: "USD" },
+  tax_expense: { tags: ["IncomeTaxExpenseBenefit"], unit: "USD" },
+  pretax_income: {
+    tags: [
+      "IncomeLossFromContinuingOperationsBeforeIncomeTaxesExtraordinaryItemsNoncontrollingInterest",
+      "IncomeLossFromContinuingOperationsBeforeIncomeTaxesMinorityInterestAndIncomeLossFromEquityMethodInvestments",
+    ],
+    unit: "USD",
+  },
+  diluted_shares: {
+    tags: ["WeightedAverageNumberOfDilutedSharesOutstanding", "WeightedAverageNumberOfDilutedSharesOutstandingBasicAndDiluted"],
+    // Share concepts are filed under `shares`, not USD. Asking for USD returns nothing, which
+    // is how the screen's dilution rule once reported "skipped" for every company alive.
+    unit: "shares",
+  },
+});
+
+export const DEBT_BUCKETS = Object.freeze(["debt_long_term_noncurrent", "debt_long_term_current", "debt_short_term"]);
+
+/** A date-only SEC field becomes an explicit UTC instant; anything unparseable becomes null. */
+export function toInstant(value) {
+  if (typeof value !== "string" || value.length < 10) return null;
+  const time = Date.parse(value.length === 10 ? `${value}T00:00:00.000Z` : value);
+  return Number.isFinite(time) ? new Date(time).toISOString() : null;
+}
+
+/** The fiscal year a period belongs to, taken from its end date -- the sec.mjs convention. */
+export const fiscalYearOf = (end) => Number(String(end).slice(0, 4));
+
+/* -------------------------------------------------------------- series and alignment -- */
+
+/** One concept's annual history, flattened the way screen.mjs flattens it. */
+export function conceptSeries(companyFacts, concept, asOf) {
+  const spec = FUNDAMENTAL_CONCEPTS[concept];
+  const found = annualSeries(companyFacts, spec.tags, { asOf, unit: spec.unit });
+  if (!found) return [];
+  return found.series.map((entry) => Object.freeze({
+    concept,
+    tag: entry.tag || found.tag,
+    unit: spec.unit,
+    start: entry.start || null,
+    end: entry.end,
+    filed: entry.filed || null,
+    accession: entry.accn || null,
+    value: entry.val,
+    fiscal_year: fiscalYearOf(entry.end),
+  }));
+}
+
+export function loadSeries(companyFacts, asOf) {
+  return Object.freeze(Object.fromEntries(Object.keys(FUNDAMENTAL_CONCEPTS)
+    .map((concept) => [concept, conceptSeries(companyFacts, concept, asOf)])));
+}
+
+/**
+ * Quarterly history for a concept. sec.mjs only merges annual periods, so this mirrors its
+ * rules for ~quarter-length durations: alias preference decides a period, a later filing of
+ * the same alias supersedes an earlier one, and nothing filed after `asOf` is visible.
+ */
+export function quarterlySeries(companyFacts, tags, { asOf = null, unit = "USD" } = {}) {
+  const cutoff = asOf ? new Date(asOf).getTime() : null;
+  const byEnd = new Map();
+  for (const tag of tags) {
+    const entries = companyFacts?.facts?.["us-gaap"]?.[tag]?.units?.[unit];
+    if (!Array.isArray(entries)) continue;
+    for (const entry of entries) {
+      if (entry.form !== "10-Q" && entry.form !== "10-K") continue;
+      if (!entry.start || !entry.end || !Number.isFinite(entry.val)) continue;
+      const days = daysBetween(entry.start, entry.end);
+      if (days < 80 || days > 100) continue;
+      if (cutoff && new Date(entry.filed).getTime() > cutoff) continue;
+      const prior = byEnd.get(entry.end);
+      if (!prior) {
+        byEnd.set(entry.end, { ...entry, tag });
+      } else if (prior.tag === tag && new Date(entry.filed) > new Date(prior.filed)) {
+        byEnd.set(entry.end, { ...entry, tag });
+      }
+    }
+  }
+  if (!byEnd.size) return null;
+  return [...byEnd.values()].sort((left, right) => Date.parse(left.end) - Date.parse(right.end));
+}
+
+/** The newest filing instant across a set of entries -- the moment the metric became public. */
+export function publicInstant(entries) {
+  const instants = entries.map((entry) => toInstant(entry.filed)).filter(Boolean);
+  if (instants.length !== entries.length) return null;
+  return instants.sort().at(-1);
+}
+
+/**
+ * The most recent fiscal year in which every named concept has a value.
+ *
+ * Aligning matters more than it looks: pairing this year's net income with last year's
+ * balance sheet because one tag stopped being filed is exactly the stale-period carry-forward
+ * this module exists to refuse.
+ */
+export function alignLatest(series, concepts) {
+  const missing = concepts.filter((concept) => !series[concept]?.length);
+  if (missing.length) return { ok: false, reason: "missing_tag", missing };
+
+  const byYear = concepts.map((concept) => new Map(series[concept].map((entry) => [entry.fiscal_year, entry])));
+  const shared = [...byYear[0].keys()].filter((year) => byYear.every((map) => map.has(year)));
+  if (!shared.length) return { ok: false, reason: "no_common_period", missing: [] };
+
+  const fiscalYear = Math.max(...shared);
+  const entries = concepts.map((concept, index) => byYear[index].get(fiscalYear));
+  return finishAlignment(entries, concepts, fiscalYear);
+}
+
+/** The same alignment, pinned to a stated fiscal year rather than to the newest one. */
+export function alignYear(series, concepts, fiscalYear) {
+  const picked = concepts.map((concept) => series[concept]?.find((entry) => entry.fiscal_year === fiscalYear));
+  const missing = concepts.filter((concept, index) => !picked[index]);
+  if (missing.length) return { ok: false, reason: "no_common_period", missing };
+  return finishAlignment(picked, concepts, fiscalYear);
+}
+
+export function finishAlignment(entries, concepts, fiscalYear) {
+  const ends = entries.map((entry) => Date.parse(entry.end));
+  if (Math.max(...ends) - Math.min(...ends) > MAX_ALIGNMENT_DRIFT_DAYS * DAY_MS) {
+    return { ok: false, reason: "period_misaligned", missing: [] };
+  }
+  const publicAt = publicInstant(entries);
+  if (!publicAt) return { ok: false, reason: "missing_filing_date", missing: [] };
+
+  const starts = entries.map((entry) => entry.start).filter(Boolean).sort();
+  return {
+    ok: true,
+    fiscal_year: fiscalYear,
+    period_start: starts[0] || null,
+    period_end: entries.map((entry) => entry.end).sort().at(-1),
+    public_at: publicAt,
+    entries: Object.fromEntries(concepts.map((concept, index) => [concept, entries[index]])),
+    used: entries,
+  };
+}
+
+/** Merge alignments that must describe the same balance sheet or the same fiscal year. */
+export function combineAlignments(alignments) {
+  const ends = alignments.map((alignment) => Date.parse(alignment.period_end));
+  if (Math.max(...ends) - Math.min(...ends) > MAX_ALIGNMENT_DRIFT_DAYS * DAY_MS) {
+    return { ok: false, reason: "period_misaligned", missing: [] };
+  }
+  const used = alignments.flatMap((alignment) => alignment.used);
+  const starts = used.map((entry) => entry.start).filter(Boolean).sort();
+  return {
+    ok: true,
+    fiscal_year: Math.max(...alignments.map((alignment) => alignment.fiscal_year)),
+    period_start: starts[0] || null,
+    period_end: alignments.map((alignment) => alignment.period_end).sort().at(-1),
+    public_at: alignments.map((alignment) => alignment.public_at).sort().at(-1),
+    entries: Object.assign({}, ...alignments.map((alignment) => alignment.entries)),
+    used,
+  };
+}
+
+/* ------------------------------------------------------------------------------- gaps -- */
+
+export const tagsFor = (concepts) => concepts.flatMap((concept) => FUNDAMENTAL_CONCEPTS[concept]?.tags || []);
+
+export function gap({ factId, component = null, code, detail, missingTags = [] }) {
+  return Object.freeze({
+    metric: factId,
+    component,
+    code,
+    detail,
+    missing_tags: Object.freeze([...missingTags]),
+  });
+}
+
+/** Turn a failed alignment into a gap that names the concept and every tag that was tried. */
+export function alignmentGap(factId, alignment, concepts, component = null) {
+  if (alignment.reason === "missing_tag" || (alignment.reason === "no_common_period" && alignment.missing.length)) {
+    const missingTags = tagsFor(alignment.missing);
+    return gap({
+      factId,
+      component,
+      code: alignment.reason,
+      detail: alignment.reason === "missing_tag"
+        ? `no XBRL tag for ${alignment.missing.join(", ")} in Company Facts (tried ${missingTags.join(", ")})`
+        : `${alignment.missing.join(", ")} is not reported for the aligned fiscal year`,
+      missingTags,
+    });
+  }
+  const detail = {
+    no_common_period: `no fiscal year in which all of ${concepts.join(", ")} are reported together`,
+    period_misaligned: `${concepts.join(", ")} disagree on the period end by more than ${MAX_ALIGNMENT_DRIFT_DAYS} days`,
+    missing_filing_date: `an input carries no filing date, so public_at cannot be taken from the filing`,
+  }[alignment.reason] || `inputs unavailable for ${concepts.join(", ")}`;
+  return gap({ factId, component, code: alignment.reason, detail, missingTags: tagsFor(concepts) });
+}
+
+/* --------------------------------------------------------------------- metric factory -- */
+
+const CONFIDENCE = Object.freeze({ reported: 0.95, rederived: 0.9, estimated: 0.6 });
+
+export function sourceRecords(entries) {
+  const seen = new Set();
+  const records = [];
+  for (const entry of entries) {
+    const key = `${entry.tag}:${entry.accession || entry.filed}:${entry.end}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    records.push(Object.freeze({
+      concept: entry.concept,
+      tag: entry.tag,
+      accession: entry.accession,
+      filed: entry.filed,
+      period_end: entry.end,
+      unit: entry.unit,
+      value: entry.value,
+    }));
+  }
+  return Object.freeze(records);
+}
+
+/**
+ * `sec:companyfacts:<cik>:<tag>:<accession|filed>:<period_end>` -- the identity the typed-fact
+ * adapter already knows how to parse back into a filing locator.
+ */
+export function sourceIds(cik, entries) {
+  return Object.freeze([...new Set(sourceRecords(entries)
+    .map((record) => `sec:companyfacts:${cik}:${record.tag}:${record.accession || record.filed}:${record.period_end}`))]);
+}
+
+export function buildMetric({
+  factId,
+  valueKind,
+  value,
+  unit,
+  currency = null,
+  scale = null,
+  ratioDenominator = null,
+  alignment,
+  cik,
+  derivation,
+  inputs,
+  assumptions,
+  components = null,
+}) {
+  const derived = derivation !== "reported";
+  const parameters = { hash_domain: HASH_DOMAIN, fact_id: factId, tool_id: TOOL_ID, tool_version: TOOL_VERSION };
+  return Object.freeze({
+    fact_id: factId,
+    value_kind: valueKind,
+    value,
+    unit,
+    currency,
+    scale,
+    ratio_denominator: ratioDenominator,
+    period_start: alignment.period_start,
+    period_end: alignment.period_end,
+    fiscal_year: Number.isInteger(alignment.fiscal_year) ? alignment.fiscal_year : null,
+    // Never the clock: the newest filing among the inputs is the moment this became knowable.
+    public_at: alignment.public_at,
+    derivation,
+    confidence: CONFIDENCE[derivation],
+    source_ids: sourceIds(cik, alignment.used),
+    source_records: sourceRecords(alignment.used),
+    inputs: Object.freeze(inputs),
+    components: components ? Object.freeze(components) : null,
+    assumptions: Object.freeze([...assumptions]),
+    tool_id: derived ? TOOL_ID : null,
+    tool_version: derived ? TOOL_VERSION : null,
+    // A reported figure is not a calculation, so it carries no calculation hash -- which is
+    // exactly what the typed-fact contract requires of `derivation: "reported"`.
+    calculation_hash: derived ? sha256({ ...parameters, inputs, assumptions, value }) : null,
+  });
+}
+
+/* -------------------------------------------------------------- shared derived pieces -- */
+

package/mcp/lib/xlsx.mjs

@@ -0,0 +1,155 @@
+/**
+ * Read an .xlsx with Node built-ins and nothing else.
+ *
+ * An xlsx is a ZIP of XML parts, and `zlib.inflateRawSync` is enough to open one. Extracted
+ * from the fund adapter because it has no fund-domain knowledge at all: any publisher that
+ * ships a workbook -- issuer holdings, an academic dataset -- reads through the same three
+ * steps. Adding a spreadsheet dependency to a zero-dependency package is not worth it for
+ * what fits in a hundred lines.
+ *
+ * Everything unusual fails closed. This reads the ordinary single-workbook shape; it is not a
+ * general ZIP implementation and must not quietly behave like one.
+ */
+
+import { inflateRawSync } from "node:zlib";
+
+/**
+ * Minimal ZIP central-directory reader.
+ *
+ * An xlsx is a ZIP of XML parts, and `zlib.inflateRawSync` is enough to read one, so a workbook is
+ * readable without adding a dependency. Entries are located through the CENTRAL directory
+ * rather than the local headers on purpose: when the archive uses a data descriptor, the
+ * local header's sizes are zeroed and only the central directory is truthful.
+ *
+ * Everything unusual fails closed. This reads the one archive shape SSGA publishes; it is not
+ * a general ZIP implementation and must not silently behave like one.
+ */
+export function unzip(buffer) {
+  const buf = Buffer.isBuffer(buffer) ? buffer : Buffer.from(buffer);
+  if (buf.length < 22 || buf.readUInt32LE(0) !== 0x04034b50) {
+    throw new Error("response is not a ZIP/xlsx container");
+  }
+  let eocd = -1;
+  for (let i = buf.length - 22; i >= 0; i -= 1) {
+    if (buf.readUInt32LE(i) === 0x06054b50) { eocd = i; break; }
+  }
+  if (eocd < 0) throw new Error("xlsx container has no end-of-central-directory record");
+  if (buf.readUInt16LE(eocd + 10) === 0xffff) throw new Error("ZIP64 xlsx containers are not supported");
+
+  const count = buf.readUInt16LE(eocd + 10);
+  let offset = buf.readUInt32LE(eocd + 16);
+  const entries = new Map();
+  for (let i = 0; i < count; i += 1) {
+    if (offset + 46 > buf.length || buf.readUInt32LE(offset) !== 0x02014b50) {
+      throw new Error("xlsx central directory is malformed");
+    }
+    const flags = buf.readUInt16LE(offset + 8);
+    const method = buf.readUInt16LE(offset + 10);
+    const compressedSize = buf.readUInt32LE(offset + 20);
+    const nameLen = buf.readUInt16LE(offset + 28);
+    const extraLen = buf.readUInt16LE(offset + 30);
+    const commentLen = buf.readUInt16LE(offset + 32);
+    const localOffset = buf.readUInt32LE(offset + 42);
+    const name = buf.toString("utf8", offset + 46, offset + 46 + nameLen);
+    if (flags & 0x0001) throw new Error(`xlsx entry ${name} is encrypted`);
+    if (method !== 0 && method !== 8) throw new Error(`xlsx entry ${name} uses unsupported compression method ${method}`);
+    const localNameLen = buf.readUInt16LE(localOffset + 26);
+    const localExtraLen = buf.readUInt16LE(localOffset + 28);
+    const start = localOffset + 30 + localNameLen + localExtraLen;
+    const raw = buf.subarray(start, start + compressedSize);
+    entries.set(name, () => (method === 0 ? raw : inflateRawSync(raw)).toString("utf8"));
+    offset += 46 + nameLen + extraLen + commentLen;
+  }
+  return entries;
+}
+
+const XML_ENTITIES = Object.freeze({ "&lt;": "<", "&gt;": ">", "&quot;": '"', "&apos;": "'", "&amp;": "&" });
+const unescapeXml = (text) => String(text).replace(/&(?:lt|gt|quot|apos|amp);/gu, (m) => XML_ENTITIES[m]);
+
+/** Concatenate every <t> inside an element: a shared string may be split into rich-text runs. */
+export const xmlText = (fragment) => {
+  let out = "";
+  for (const match of String(fragment).matchAll(/<t[^>]*>([\s\S]*?)<\/t>/gu)) out += match[1];
+  return unescapeXml(out);
+};
+
+/** "AB12" -> 27. Cells are addressed, not ordered: empty cells are simply absent. */
+export const columnIndex = (ref) => {
+  const letters = /^([A-Z]+)/u.exec(String(ref || "").toUpperCase());
+  if (!letters) return -1;
+  return [...letters[1]].reduce((acc, ch) => acc * 26 + (ch.charCodeAt(0) - 64), 0) - 1;
+};
+
+export function xlsxRows(sheetXml, sharedStrings) {
+  const rows = [];
+  for (const rowMatch of sheetXml.matchAll(/<row[^>]*>([\s\S]*?)<\/row>/gu)) {
+    const cells = [];
+    for (const cellMatch of rowMatch[1].matchAll(/<c\s+r="([A-Z]+\d+)"([^>]*)>([\s\S]*?)<\/c>/gu)) {
+      const index = columnIndex(cellMatch[1]);
+      if (index < 0) continue;
+      const type = /t="([^"]+)"/u.exec(cellMatch[2])?.[1] || "n";
+      const body = cellMatch[3];
+      const value = /<v>([\s\S]*?)<\/v>/u.exec(body)?.[1];
+      if (type === "s") cells[index] = sharedStrings[Number(value)] ?? null;
+      else if (type === "inlineStr") cells[index] = xmlText(/<is>([\s\S]*?)<\/is>/u.exec(body)?.[1] || "");
+      else cells[index] = value === undefined ? null : unescapeXml(value);
+    }
+    rows.push(cells);
+  }
+  return rows;
+}
+
+/**
+ * Open a workbook: every sheet's rows, plus the date system its serials are counted in.
+ *
+ * The date system is not optional detail. A workbook written by Mac Excel sets
+ * `date1904="1"` and its serials sit 1,462 days from the default epoch -- read with the wrong
+ * one, every date is silently four years and a day early, which looks entirely plausible and
+ * is how a current dataset gets mistaken for a stale one.
+ *
+ * Callers locate their header row by content rather than by offset: publishers move the table
+ * when the surrounding label and disclosure rows change length.
+ */
+export function readWorkbook(buffer) {
+  const entries = unzip(buffer);
+  const workbookPart = entries.get("xl/workbook.xml");
+  const date1904 = workbookPart ? /date1904\s*=\s*"(?:1|true)"/iu.test(workbookPart()) : false;
+  const sharedPart = entries.get("xl/sharedStrings.xml");
+  const sharedStrings = sharedPart
+    ? [...sharedPart().matchAll(/<si>([\s\S]*?)<\/si>/gu)].map((match) => xmlText(match[1]))
+    : [];
+  const sheets = [...entries.keys()]
+    .filter((name) => /^xl\/worksheets\/[^/]+\.xml$/u.test(name))
+    .sort()
+    .map((name) => ({ name, rows: xlsxRows(entries.get(name)(), sharedStrings) }));
+  if (!sheets.length) throw new Error("workbook contains no worksheet part");
+  return { date1904, sheets };
+}
+
+/**
+ * Excel serial date to ISO, honouring the workbook's date system.
+ *
+ * In the default 1900 system day 1 is 1900-01-01 and the format wrongly treats 1900 as a leap
+ * year, so serials at or above 60 carry an extra day that has to come back out. The 1904
+ * system has neither quirk.
+ */
+export function excelSerialToIso(serial, { date1904 = false } = {}) {
+  const value = Number(serial);
+  if (!Number.isFinite(value) || value < 0) return null;
+  const epoch = date1904 ? Date.UTC(1904, 0, 1) : Date.UTC(1899, 11, 31);
+  const days = date1904 ? value : (value >= 60 ? value - 1 : value);
+  return new Date(epoch + (days * 86400000)).toISOString().slice(0, 10);
+}
+
+export function readWorkbookRows(buffer, { sheetPath = null } = {}) {
+  const entries = unzip(buffer);
+  const sharedPart = entries.get("xl/sharedStrings.xml");
+  const sharedStrings = sharedPart
+    ? [...sharedPart().matchAll(/<si>([\s\S]*?)<\/si>/gu)].map((match) => xmlText(match[1]))
+    : [];
+  const target = sheetPath
+    || [...entries.keys()].find((name) => /^xl\/worksheets\/sheet1\.xml$/u.test(name))
+    || [...entries.keys()].find((name) => /^xl\/worksheets\/.+\.xml$/u.test(name));
+  if (!target) throw new Error("workbook contains no worksheet part");
+  return xlsxRows(entries.get(target)(), sharedStrings);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "alphacouncil-agent",
-  "version": "0.9.2",
-  "description": "Multi-agent public-equity research workflow plugin for Codex & Claude Code: sourced evidence packets, bull/bear debate, and a portfolio-manager Buy/Overweight/Hold/Underweight/Sell decision.",
+  "version": "1.0.0",
+  "description": "Multi-agent company, ETF and market-index research workflow for Codex & Claude Code: sourced evidence, method seats, bull/bear debate and portfolio-manager synthesis.",
   "type": "module",
   "license": "MIT",
   "author": "Zhao73",
@@ -33,7 +33,7 @@
     "check": "node scripts/selfcheck.mjs",
     "test": "node scripts/run-tests.mjs",
     "test:source": "node --test",
-    "test:package": "node scripts/package-smoke.mjs",
+    "test:package": "node scripts/check-packaged-host-parity.mjs --check",
     "sync": "node scripts/sync-personas.mjs",
     "persona:corpus": "node scripts/report-persona-corpus-gaps.mjs",
     "persona:build-specs": "node scripts/report-persona-v3-build-specs.mjs",
@@ -42,7 +42,7 @@
     "persona:release:assemble": "node scripts/assemble-persona-v3-release.mjs",
     "persona:release:promote": "node scripts/promote-persona-v3-release.mjs",
     "persona:release:evidence:check": "node scripts/check-persona-v3-ga.mjs --expected-version 0.9.0 --require-release-evidence",
-    "release:check": "npm run check && node scripts/check-persona-v3-ga.mjs --expected-version 0.9.0 --require-count 26 --require-min-admission operational --forbid-legacy --forbid-prompt-lens --require-release-evidence",
+    "release:check": "npm run check && node scripts/check-persona-v3-ga.mjs --expected-version 0.9.0 --require-count 27 --require-min-admission operational --forbid-legacy --forbid-prompt-lens --require-release-evidence",
     "release:preview:check": "npm run check && npm run test:package",
     "persona:stage:init": "node scripts/scaffold-persona-v3-staging.mjs --write",
     "persona:stage:check": "node scripts/scaffold-persona-v3-staging.mjs --check",
@@ -84,7 +84,7 @@
     "evaluation:artifacts:check": "node scripts/council-experiment-artifacts.mjs --check",
     "host:e2e:artifacts": "node scripts/host-e2e-artifacts.mjs --plan",
     "host:e2e:artifacts:check": "node scripts/host-e2e-artifacts.mjs --check",
-    "prepublishOnly": "npm run check && npm run test:package"
+    "prepublishOnly": "npm test && npm run test:package"
   },
   "bin": {
     "alphacouncil-agent": "mcp/server.mjs"