openalgo-script 0.5.0 → 0.7.0

package/spec/errors.json

@@ -12,14 +12,16 @@
     "parse": "Reading tokens into a tree.",
     "check": "Names, types, scope and call sites, before any bar runs.",
     "runtime": "Executing a bar.",
-    "host": "The host answering the engine: data, limits and order destinations."
+    "host": "The host answering the engine: data, limits and order destinations.",
+    "import": "Reading a script written in another chart language and writing it as OpenScript."
   },
   "stageLabels": {
     "lex": "lexer",
     "parse": "parser",
     "check": "checker",
     "runtime": "engine",
-    "host": "host"
+    "host": "host",
+    "import": "importer"
   },
   "ranges": [
     {
@@ -69,6 +71,12 @@
       "kind": "Warnings",
       "means": "The script compiles and runs, and something in it is probably not meant.",
       "severity": "warning"
+    },
+    {
+      "prefix": "OS9",
+      "kind": "Import",
+      "means": "A script written in another chart language could not be translated as written, or was translated with a stated difference.",
+      "severity": "error or warning"
     }
   ],
   "entries": [
@@ -902,7 +910,7 @@
       },
       "spec": "language.md 15.1",
       "refines": null,
-      "test": null
+      "test": "tests/unit/check-names.test.ts"
     },
     {
       "code": "OS2011",
@@ -1175,7 +1183,7 @@
       "placeholders": {
         "option": "the option that was given a bar-dependent value"
       },
-      "cause": "The declaration builds the legend, the axis and the settings dialog before bar 0 runs, so its options must be literals, arithmetic over literals, or an input(). A value that changes per bar has no single answer at the moment the dialog is built. The rule covers more than the declaration's own options: every argument that lands in a declaration fixed before bar 0 arrives here too, signal's at, shape and color, table's position, rows and cols, and a plot's style arguments among them. An input() counts as a constant for this purpose, because the engine resolves inputs at load and substitutes the resolved value before bar 0 runs.",
+      "cause": "The declaration builds the legend, the axis and the settings dialog before bar 0 runs, so its options must be literals, arithmetic over literals, or an input() written as the whole of the value; an expression over an input is OS3025. A value that changes per bar has no single answer at the moment the dialog is built. The rule covers more than the declaration's own options: every argument that lands in a declaration fixed before bar 0 arrives here too, signal's at, shape and color, table's position, rows and cols, and a plot's style arguments among them. An input() counts as a constant for this purpose, because the engine resolves inputs at load and substitutes the resolved value before bar 0 runs.",
       "fix": "Use a literal, or make it tunable with an input(): {option} = input(2, \"{option}\").",
       "autofix": false,
       "example": {
@@ -1644,6 +1652,48 @@
       "refines": "OS3021",
       "test": "tests/unit/check-calls.test.ts"
     },
+    {
+      "code": "OS3025",
+      "title": "A setting is part of a larger expression here",
+      "severity": "error",
+      "stage": "check",
+      "since": 1,
+      "message": "{option} is fixed before the first bar and holds an input() only as the whole of its value, so it cannot hold an expression over one.",
+      "placeholders": {
+        "option": "the option or field whose value reads a setting as part of something larger"
+      },
+      "cause": "A field fixed before bar 0 is written into the compiled program as one of two things: the value itself, which the compiler folds, or a reference to one input, which the engine resolves once at load (compiled-program.md 2.3). An expression over a setting is neither. The compiler cannot fold it, because the setting's value is not known until the host resolves the settings, and the program has no form for an expression evaluated at load, because that would be a second evaluator every engine has to agree on before the first bar. An input's own default, bounds and step are the same kind of field and are held tighter still: they are what the settings dialog shows before anybody has chosen, so none of them may read another setting at all.",
+      "fix": "Declare the setting as the value itself, with an input() written as the whole of {option}, or write the value out as a literal.",
+      "autofix": false,
+      "example": {
+        "before": "w = input(1, \"Width\")\nplot(close, \"Close\", aqua, width = w + 1)",
+        "after": "w = input(2, \"Width\")\nplot(close, \"Close\", aqua, width = w)"
+      },
+      "spec": "language.md 13.2",
+      "refines": null,
+      "test": "tests/unit/check-plot-options.test.ts"
+    },
+    {
+      "code": "OS3026",
+      "title": "This option cannot be a setting",
+      "severity": "error",
+      "stage": "check",
+      "since": 1,
+      "message": "{option} is written into the compiled program as a plain value, so a setting cannot choose it in this format version.",
+      "placeholders": {
+        "option": "the option that was written from an input()"
+      },
+      "cause": "An option fixed before bar 0 carries either its value or a reference to one input, resolved at load (compiled-program.md 2.3), and almost every option takes both. A plot's style takes only the value: its field in the compiled format is a plain string. So an input() written into it could only be folded to its default, the settings row it declares would move nothing, and a select offering values the option does not accept would pass, because the set check reads a value written out and a setting is not one. Widening the field changes the compiled format that every other engine is written against, so it is refused here rather than half carried.",
+      "fix": "Write the option out as a string literal and drop the input(): style = \"step\", for instance, is one of the values OS3008 names.",
+      "autofix": false,
+      "example": {
+        "before": "st = input(\"line\", \"Style\", options = [\"line\", \"step\", \"area\"])\nplot(close, \"Close\", aqua, style = st)",
+        "after": "plot(close, \"Close\", aqua, style = \"step\")"
+      },
+      "spec": "language.md 13.4",
+      "refines": null,
+      "test": "tests/unit/check-plot-options.test.ts"
+    },
     {
       "code": "OS4001",
       "title": "History index is not usable",
@@ -1709,7 +1759,7 @@
       },
       "spec": "language.md 14.1",
       "refines": null,
-      "test": null
+      "test": "tests/engine/machine.test.ts"
     },
     {
       "code": "OS4004",
@@ -1824,8 +1874,7 @@
       },
       "spec": "language.md 15.3",
       "refines": null,
-      "test": null,
-      "deferred": "Nothing raises this yet. A write outside the declared grid raises the broader OS4004, which names an index rather than the shape the declaration fixed. Raised when the table surface reports the cell against the table it was written to, language.md 15.3."
+      "test": "tests/engine/tables.test.ts"
     },
     {
       "code": "OS4009",
@@ -2428,17 +2477,18 @@
       "since": 1,
       "message": "The host did not supply {fact} for {symbol}.",
       "placeholders": {
-        "fact": "the missing fact: tick size, lot size, session or timezone",
+        "fact": "what the instrument record lacks for something that cannot default it: a timezone for the session it states, a timezone the calendar can read, a session spelled HH:MM, or session days numbered 1 to 7",
         "symbol": "the instrument it is missing for"
       },
-      "cause": "Tick size, lot size, the session and the timezone come from the instrument record (host-interface.md 4.1), not from the bars. A script that rounds to a tick or sizes in lots cannot invent them, and guessing would produce orders the exchange rejects.",
-      "fix": "Supply {fact} in the host's instrument record, or stop depending on it: round with a number the script chooses rather than chart.tickSize.",
+      "cause": "An instrument fact the host did not state is absent, and a bare read of one, chart.tickSize or chart.lotSize among them, returns the absent value a script can test with isNone (stdlib.md 3.4). This error is the other case: something that needs the fact and has no way to proceed without it. A session with no timezone is a window with no clock to read it in, so every session test on that host would answer absence on every bar and every session study would draw nothing with nothing said. The engine refuses the record at load instead, before any bar runs, because the fact comes from the instrument record (host-interface.md 4.1) and not from the bars, and a guessed zone is silently wrong for half the year anywhere a clock changes with the season.",
+      "fix": "Supply {fact} in the host's instrument record for {symbol}, or leave the session out of the record, which makes every session read absent rather than wrong.",
       "autofix": false,
       "example": {
-        "before": "qty = lots * chart.lotSize",
-        "after": "lotSize = input(1, \"Lot size\", min = 1)\nqty = lots * lotSize"
+        "kind": "transcript",
+        "before": "host instrument record:\n  session   09:15 to 15:30, days 1 to 5\n  timezone  not stated",
+        "after": "host instrument record:\n  session   09:15 to 15:30, days 1 to 5\n  timezone  UTC"
       },
-      "spec": "language.md 15.2",
+      "spec": "host-interface.md 4.5",
       "refines": null,
       "test": "tests/engine/requests-host.test.ts"
     },
@@ -2698,6 +2748,51 @@
       "refines": null,
       "test": "tests/backtest/settings.test.ts"
     },
+    {
+      "code": "OS6024",
+      "title": "The host cannot draw something this study declares",
+      "severity": "error",
+      "stage": "host",
+      "since": 1,
+      "message": "This host cannot draw {what}: {limit}.",
+      "placeholders": {
+        "what": "the declaration that will not be drawn, named by its title where it has one",
+        "limit": "the host's own sentence for why, which is the only part a host writes"
+      },
+      "cause": "A compiled program carries every output the language can express, and a host draws what its own surface has room for. The two are allowed to differ, and what is not allowed is the difference being invisible: a study whose second panel never appears looks like a study with a bug in its cells, and a band drawn in a colour the script did not choose looks like a script that chose it. So a host states its limit before any bar runs, rather than drawing part of the study and saying nothing. The compiled program carries no source position for a declaration, which is why the refusal names the declaration by its title rather than pointing at a line.",
+      "fix": "Declare what this host draws, or run the study on a host that draws {what}.",
+      "autofix": false,
+      "example": {
+        "kind": "transcript",
+        "before": "study declares:\n  table \"Summary\", 2 rows, 2 columns\n  table \"Detail\", 4 rows, 2 columns\nhost draws: one grid per pane",
+        "after": "study declares:\n  table \"Summary\", 6 rows, 2 columns\nhost draws: one grid per pane"
+      },
+      "spec": "compiled-program.md 11",
+      "refines": null,
+      "test": "tests/adapters/charts/undrawable.test.ts"
+    },
+    {
+      "code": "OS6025",
+      "title": "A bar has no time",
+      "severity": "error",
+      "stage": "host",
+      "since": 1,
+      "message": "Bar {index} was handed over with no time.",
+      "placeholders": {
+        "index": "the index of the bar that carries no time"
+      },
+      "cause": "Every bar states its open instant (host-interface.md 3.1), and the order rule, the history operator, warmup and every calendar fold are built on it. A bar dated nothing cannot be put in order against the bar before it, so it is not OS6011, which is about two stated instants in the wrong order: it is a bar of the wrong shape. Reading it as the absent value would step it over every calendar fold and make every session fact absent for a bar that is on the chart, which draws a gap where the host has data.",
+      "fix": "State the bar's open instant in whole milliseconds since the Unix epoch, UTC, and leave out a bar the host cannot date rather than handing it over without a time.",
+      "autofix": false,
+      "example": {
+        "kind": "transcript",
+        "before": "host input:\n  bar 41  09:10\n  bar 42  (no time)\n  bar 43  09:20",
+        "after": "host input:\n  bar 41  09:10\n  bar 42  09:15\n  bar 43  09:20"
+      },
+      "spec": "host-interface.md 3.5",
+      "refines": null,
+      "test": "tests/engine/series.test.ts"
+    },
     {
       "code": "OS7001",
       "title": "Only a strategy can do that",
@@ -3274,7 +3369,7 @@
       },
       "spec": "language.md 13.2, 15.3",
       "refines": null,
-      "test": null
+      "test": "tests/unit/check-plot-options.test.ts"
     },
     {
       "code": "OS8008",
@@ -3380,7 +3475,7 @@
       },
       "spec": "language.md 6.4, 6.5",
       "refines": null,
-      "test": null
+      "test": "tests/unit/check-dead-code.test.ts"
     },
     {
       "code": "OS8013",
@@ -3449,7 +3544,7 @@
       },
       "spec": "language.md 10.3",
       "refines": null,
-      "test": null
+      "test": "tests/unit/check-dead-code.test.ts"
     },
     {
       "code": "OS8016",
@@ -3470,7 +3565,7 @@
       },
       "spec": "language.md 11.3",
       "refines": null,
-      "test": null
+      "test": "tests/unit/check-dead-code.test.ts"
     },
     {
       "code": "OS8017",
@@ -3491,7 +3586,7 @@
       },
       "spec": "language.md 10.2",
       "refines": null,
-      "test": null
+      "test": "tests/unit/check-dead-code.test.ts"
     },
     {
       "code": "OS8018",
@@ -3536,8 +3631,273 @@
       },
       "spec": "language.md 5.4",
       "refines": null,
-      "test": null,
-      "deferred": "Nothing raises this yet. The checker does not follow a reference to a deleted object, so the held handle this warns about compiles silently. Raised when the checker follows a deletion to the names and elements still holding the object, language.md 5.4."
+      "test": "tests/unit/check-deleted.test.ts"
+    },
+    {
+      "code": "OS9001",
+      "title": "Version not read by the importer",
+      "severity": "error",
+      "stage": "import",
+      "since": 1,
+      "message": "The importer reads scripts written for version 5 or 6 of the source dialect, and this one {found}.",
+      "placeholders": {
+        "found": "what the version annotation says instead: that it declares another version, naming it, or that it declares none"
+      },
+      "cause": "A script in the source dialect opens with an annotation comment naming the version of the dialect it is written for. The importer's reader, its table of built-ins and every rule it applies about where the two languages differ are written for versions 5 and 6, whose built-ins live in namespaces and whose declaration is an indicator or strategy call. An earlier version names its built-ins differently and differs in rules the importer does not model, so reading one under these rules would produce a translation that compiles and means something else. Nothing is translated: the result's source is empty and this is its only finding.",
+      "fix": "Bring the script up to version 5 or 6 in the source dialect, or translate it by hand, and import it again.",
+      "autofix": false,
+      "example": {
+        "kind": "import",
+        "before": "//@version=4\nstudy(\"Range\")\nplot(high - low)",
+        "after": "version 1\n\nstudy(\"Range\")\nplot(high - low, \"Range\")"
+      },
+      "spec": "docs/writing/importing-a-script.md 2",
+      "refines": null,
+      "test": "tests/importer/refusals.test.ts"
+    },
+    {
+      "code": "OS9002",
+      "title": "Construct with no equivalent",
+      "severity": "error",
+      "stage": "import",
+      "since": 1,
+      "message": "The importer cannot translate {construct}, so the statement holding it was kept as a comment.",
+      "placeholders": {
+        "construct": "the form the importer met, named in a few words: a tuple assignment, an if used as a value, a comparison with na"
+      },
+      "cause": "Some forms of the source dialect have no OpenScript spelling that keeps their meaning: a value produced by an if or a switch, a tuple, a type, a method, an import, an array literal, a loop over a collection, and an equality test against na, which the source dialect answers false on every bar while OpenScript's own test for absence answers true where the value is absent. A few more are written in forms the importer's reader does not accept. The importer keeps the whole top level statement holding one as a comment line per source line, marked not translated, so the output still compiles and the original is there to translate from.",
+      "fix": "Translate that statement by hand from the comment that holds it: the rest of the script was translated around it.",
+      "autofix": false,
+      "example": {
+        "kind": "import",
+        "before": "//@version=5\nindicator(\"Side\")\nside = if close > open\n    1\nelse\n    -1\nplot(side)",
+        "after": "version 1\n\nstudy(\"Side\")\nside = close > open ? 1 : -1\nplot(side, \"Side\")"
+      },
+      "spec": "docs/writing/importing-a-script.md 4",
+      "refines": null,
+      "test": "tests/importer/refusals.test.ts"
+    },
+    {
+      "code": "OS9003",
+      "title": "Built-in with no mapping",
+      "severity": "error",
+      "stage": "import",
+      "since": 1,
+      "message": "{name} is not one of the built-ins the importer maps, so the statement holding it was kept as a comment.",
+      "placeholders": {
+        "name": "the built-in as the source writes it, namespace included"
+      },
+      "cause": "The importer translates a built-in only where it holds a row saying which OpenScript name computes the same thing and how the arguments line up. A built-in with no row, or a name the source never declares, is not guessed at: a function with a similar name can differ in its arguments, its warmup or its arithmetic, and a translation that compiled with the wrong one would draw a line that looks right and is not. The whole top level statement holding it is kept as a comment.",
+      "fix": "Find the OpenScript library call that does the same job, check how it treats its first bars and absent values, and write the statement by hand.",
+      "autofix": false,
+      "example": {
+        "kind": "import",
+        "before": "//@version=5\nindicator(\"Range position\")\nrank = ta.percentrank(close, 20)\nplot(rank)",
+        "after": "version 1\n\nstudy(\"Range position\")\nrank = percentRank(close, 20)\nplot(rank, \"Rank\")"
+      },
+      "spec": "docs/writing/importing-a-script.md 3",
+      "refines": null,
+      "test": "tests/importer/refusals.test.ts"
+    },
+    {
+      "code": "OS9004",
+      "title": "Declaration the importer cannot place",
+      "severity": "error",
+      "stage": "import",
+      "since": 1,
+      "message": "The importer writes the declaration from one indicator or strategy call at the top level, and this script {found}.",
+      "placeholders": {
+        "found": "what the importer found instead: that the script has none, that it declares a library, or that it makes a second declaration here"
+      },
+      "cause": "An OpenScript file carries exactly one declaration, and it is what makes the file a study or a strategy. The importer writes it from the source's indicator or strategy call and from nothing else, because a declaration it invented would decide whether the translation may place orders. A script with none, and a library, which has no declaration an OpenScript file can carry, are not translated at all: the result's source is empty and this is its only finding. A second declaration is kept as a comment and the first one is used.",
+      "fix": "Give the source script exactly one indicator or strategy declaration at the top level, and import it again.",
+      "autofix": false,
+      "example": {
+        "kind": "import",
+        "before": "//@version=5\nbasis = ta.sma(close, 20)\nplot(basis)",
+        "after": "version 1\n\nstudy(\"Basis\")\nbasis = sma(close, 20)\nplot(basis, \"Basis\")"
+      },
+      "spec": "docs/writing/importing-a-script.md 2",
+      "refines": null,
+      "test": "tests/importer/refusals.test.ts"
+    },
+    {
+      "code": "OS9005",
+      "title": "Reads a statement that was not translated",
+      "severity": "error",
+      "stage": "import",
+      "since": 1,
+      "message": "{name} is declared by the statement at line {line}, which was not translated, so this statement that reads it was kept as a comment too.",
+      "placeholders": {
+        "name": "the name, as the source writes it",
+        "line": "the line of the statement that declares it and was kept as a comment"
+      },
+      "cause": "A statement that was not translated declares nothing in the output, so a later statement reading one of its names would not compile. Rather than hand back a file that fails, the importer keeps every such statement as a comment as well, in source order, so that one refusal is reported once at its cause and once at each statement that follows from it.",
+      "fix": "Translate the statement at line {line} by hand first, then this one, which was kept as a comment only because it reads {name}.",
+      "autofix": false,
+      "example": {
+        "kind": "import",
+        "before": "//@version=5\nindicator(\"Rank\")\nrank = ta.percentrank(close, 20)\nsmooth = ta.sma(rank, 5)\nplot(smooth)",
+        "after": "version 1\n\nstudy(\"Rank\")\nrank = percentRank(close, 20)\nsmooth = sma(rank, 5)\nplot(smooth, \"Smooth\")"
+      },
+      "spec": "docs/writing/importing-a-script.md 4",
+      "refines": null,
+      "test": "tests/importer/refusals.test.ts"
+    },
+    {
+      "code": "OS9006",
+      "title": "Argument with no equivalent",
+      "severity": "error",
+      "stage": "import",
+      "since": 1,
+      "message": "{argument} changes what {call} computes or trades, and OpenScript has no equivalent the importer can write.",
+      "placeholders": {
+        "argument": "the argument, as the source names it or by its position",
+        "call": "the call it was given to, as the source writes it"
+      },
+      "cause": "Some arguments change the numbers a script produces or the orders it sends: a declaration's timeframe, a strategy's margin or its pyramiding above one, a limit price on an entry, a trailing exit, a quantity on a close, and a quantity on an entry in a strategy that sizes its orders in anything but units, which the source dialect counts in contracts and OpenScript in the declaration's own unit. Leaving one out would produce a translation that compiles and computes something else. An argument to the declaration or to an input is left out of that call, because the file needs its declaration and the rest of the script reads the input; every other call carrying one is kept as a comment.",
+      "fix": "Translate the call by hand, deciding what OpenScript should do in place of {argument}, or remove {argument} from the source script if the script does not depend on it.",
+      "autofix": false,
+      "example": {
+        "kind": "import",
+        "before": "//@version=5\nindicator(\"Daily basis\", timeframe = \"D\")\nplot(ta.sma(close, 20))",
+        "after": "version 1\n\nstudy(\"Daily basis\")\nplot(req.timeframe(\"1D\", sma(close, 20)), \"Basis\")"
+      },
+      "spec": "docs/writing/importing-a-script.md 4",
+      "refines": null,
+      "test": "tests/importer/arguments.test.ts"
+    },
+    {
+      "code": "OS9007",
+      "title": "Warmup and absent bars follow OpenScript",
+      "severity": "warning",
+      "stage": "import",
+      "since": 1,
+      "message": "{call} became {target} here and wherever else the script calls it, and {target} follows OpenScript's own warmup, arithmetic and handling of absent values, which the original is not guaranteed to share.",
+      "placeholders": {
+        "call": "the built-in as the source writes it",
+        "target": "the OpenScript call it was translated to"
+      },
+      "cause": "OpenScript fixes, for every function, the first bar a value appears on, how a seeded average is seeded, the order its arithmetic is done in and what an absent value inside the window does (stdlib.md sections 2.4 and 20). The source dialect does not fix the same things to the same precision, and where it says anything it can say something else: it skips absent values in windows where OpenScript propagates them. So a translated average can be absent on a first bar where the original drew a value, or differ in the last digits. Over a source with no absent values, and after the first bars, the two compute the same quantity. The finding is given once per built-in, at its first call.",
+      "fix": "Compare the first bars of the translation with the original, and where the script depends on them, write the value as an explicit recurrence held in var, seeded the way the original seeds it.",
+      "autofix": false,
+      "example": {
+        "kind": "import",
+        "before": "//@version=5\nindicator(\"Average\")\nplot(ta.ema(close, 20))",
+        "after": "version 1\n\nstudy(\"Average\")\nplot(ema(close, 20), \"Average\")"
+      },
+      "spec": "language.md 6.7, 7.3; stdlib.md 2.4, 20.2",
+      "refines": null,
+      "test": "tests/importer/differences.test.ts"
+    },
+    {
+      "code": "OS9008",
+      "title": "Whole-number division in version 5",
+      "severity": "warning",
+      "stage": "import",
+      "since": 1,
+      "message": "Both sides of this division are whole-number constants, which version 5 of the source dialect divides without a fractional part, and OpenScript keeps the fraction.",
+      "placeholders": {},
+      "cause": "Version 5 of the source dialect gives the quotient of two whole-number constants as a whole number, and version 6 and OpenScript both keep the fraction (language.md 9.2). A constant here is a whole-number literal, or a name the script binds once to one and never reassigns. The importer writes the division as OpenScript writes it and says so, rather than deciding which of the two results the script's author was relying on.",
+      "fix": "If the script relied on the whole-number result, wrap the translated division in trunc(); otherwise leave it as it is.",
+      "autofix": false,
+      "example": {
+        "kind": "import",
+        "before": "//@version=5\nindicator(\"Half\")\nhalf = 7 / 2\nplot(close * half)",
+        "after": "version 1\n\nstudy(\"Half\")\nhalf = trunc(7 / 2)\nplot(close * half, \"Half\")"
+      },
+      "spec": "language.md 9.2",
+      "refines": null,
+      "test": "tests/importer/differences.test.ts"
+    },
+    {
+      "code": "OS9009",
+      "title": "Presentation argument left out",
+      "severity": "warning",
+      "stage": "import",
+      "since": 1,
+      "message": "{argument} changes how {call} is displayed or what it may allocate, not what it computes, and OpenScript has no equivalent, so the translation leaves it out.",
+      "placeholders": {
+        "argument": "the argument, as the source names it",
+        "call": "the call it was given to, as the source writes it"
+      },
+      "cause": "Many arguments in the source dialect are about the picture rather than the numbers: a line that tracks the price, a label size, a legend entry, a count of drawings to keep, a style the OpenScript call does not offer. Leaving one out changes what the chart looks like and nothing the script computes or trades, so the call is translated and the argument is reported rather than silently dropped.",
+      "fix": "Nothing needs to change unless the display mattered; where it did, restyle the translated call with the arguments OpenScript does have, such as its colour, width and style.",
+      "autofix": false,
+      "example": {
+        "kind": "import",
+        "before": "//@version=5\nindicator(\"Close\")\nplot(close, \"Close\", trackprice = true)",
+        "after": "version 1\n\nstudy(\"Close\")\nplot(close, \"Close\")"
+      },
+      "spec": "docs/writing/importing-a-script.md 5",
+      "refines": null,
+      "test": "tests/importer/arguments.test.ts"
+    },
+    {
+      "code": "OS9010",
+      "title": "Order placed under OpenScript's order model",
+      "severity": "warning",
+      "stage": "import",
+      "since": 1,
+      "message": "{call} was translated into OpenScript's order calls here and wherever else the script uses it, and OpenScript decides when an order fills, how a reversal and a repeated entry are handled and when an exit level starts to apply by its own order model.",
+      "placeholders": {
+        "call": "the order call as the source writes it"
+      },
+      "cause": "The importer translates an entry into a close of any opposite position and an entry guarded so that it never adds to a position already held on its side, which is what the source dialect does with its default pyramiding, and an exit into a leg level guarded by the side of the entry it names, with profit and loss distances converted from ticks by the instrument's tick size. That is as close as the two order models come, and they are not the same model: an OpenScript exit sets the leg's level when it is called rather than when its entry fills, a repeated entry past the pyramiding limit is refused rather than ignored, and an order a script places while flat is sized and filled by the rules of stdlib.md section 17. The finding is given once per order call, at its first use.",
+      "fix": "Backtest the translation beside the original and compare the two trade lists before relying on it, and adjust the order calls by hand where they part.",
+      "autofix": false,
+      "example": {
+        "kind": "import",
+        "before": "//@version=5\nstrategy(\"Cross\")\nfast = ta.sma(close, 10)\nslow = ta.sma(close, 30)\nif ta.crossover(fast, slow)\n    strategy.entry(\"Long\", strategy.long)",
+        "after": "version 1\n\nstrategy(\"Cross\", capital = 1000000)\nfast = sma(close, 10)\nslow = sma(close, 30)\nif crossUp(fast, slow)\n    if pos.size < 0\n        close()\n    if pos.size <= 0\n        buy(tag = \"Long\")"
+      },
+      "spec": "stdlib.md 17.1, 17.2",
+      "refines": null,
+      "test": "tests/importer/orders.test.ts"
+    },
+    {
+      "code": "OS9011",
+      "title": "Equality over two absent values",
+      "severity": "warning",
+      "stage": "import",
+      "since": 1,
+      "message": "Both sides of {operator} can be absent on the same bar, and OpenScript counts two absent values as equal, which the original is not guaranteed to do.",
+      "placeholders": {
+        "operator": "the equality operator, == or !="
+      },
+      "cause": "OpenScript's equality is total: none == none is true and none != none is false, so that a test for absence can be written as a comparison (language.md 6.5). The source dialect does not count two absent values as equal. Where both sides of an equality can be absent together, which is every warmup bar of two averages, the translation and the original can take different branches on exactly those bars.",
+      "fix": "If the original relied on two absent values never comparing equal, guard the translated comparison with isNone() on either side.",
+      "autofix": false,
+      "example": {
+        "kind": "import",
+        "before": "//@version=5\nindicator(\"Touch\")\nfast = ta.sma(close, 5)\nslow = ta.sma(close, 20)\nplot(fast == slow ? 1 : 0)",
+        "after": "version 1\n\nstudy(\"Touch\")\nfast = sma(close, 5)\nslow = sma(close, 20)\nplot(not isNone(fast) and fast == slow ? 1 : 0, \"Touch\")"
+      },
+      "spec": "language.md 6.5",
+      "refines": null,
+      "test": "tests/importer/differences.test.ts"
+    },
+    {
+      "code": "OS9012",
+      "title": "The translation does not compile",
+      "severity": "error",
+      "stage": "import",
+      "since": 1,
+      "message": "The OpenScript compiler refused the translation of this statement with {code}, so the statement was kept as a comment.",
+      "placeholders": {
+        "code": "the catalogue code the compiler raised on the translated text"
+      },
+      "cause": "The importer compiles its own output before it returns it, so that what it hands back compiles. A statement can translate construct by construct and still be refused as a whole: version 5 of the source dialect lets a number stand where a condition is expected, and the source dialect lets a name inside a block keep a history and lets two values of different types meet where OpenScript refuses. The importer does not type the source script, so it learns of these from the compiler, keeps the statement as a comment and compiles again.",
+      "fix": "Look up {code} in this catalogue and translate the statement by hand in the form that code's fix describes.",
+      "autofix": false,
+      "example": {
+        "kind": "import",
+        "before": "//@version=5\nindicator(\"Traded\")\ntraded = volume ? 1 : 0\nplot(traded)",
+        "after": "version 1\n\nstudy(\"Traded\")\ntraded = volume > 0 ? 1 : 0\nplot(traded, \"Traded\")"
+      },
+      "spec": "docs/writing/importing-a-script.md 4",
+      "refines": null,
+      "test": "tests/importer/refusals.test.ts"
     }
   ]
 }

package/src/adapters/charts/run.ts

@@ -39,6 +39,7 @@ import type { SourceFile } from '../../core/index.js';
 import { hostBar, hostNow, stateFor } from './bars.js';
 import type { ChartBar, ChartCalcContext, ChartSettings, ChartStore } from './contract.js';
 import { refused, stopped } from './errors.js';
+import { undrawable } from './undrawable.js';
 import { stationIn, stationOf } from './requests.js';
 import { engineSettings, signatureOf } from './settings.js';
 import { answersFor, needsVenue, routeInto, venueFor } from './venue.js';
@@ -335,6 +336,11 @@ function start(
     ? { ...options, orders: routeInto(holder) }
     : options;
 
+  // What this chart has no room for is refused before the engine is asked,
+  // because a study drawn without it is a study that looks broken.
+  const narrower = undrawable(program);
+  if (narrower !== undefined) throw refused(narrower);
+
   const loaded = load(program, {
     settings: engineSettings(program, settings),
     host: hostFor(ctx, withRoute, requests),

package/src/adapters/charts/tables.ts

@@ -28,25 +28,12 @@
  * direction: a cell nothing was written into is blank, never a zero.
  *
  * **A chart pane holds one grid and the language declares as many as it likes.**
- * The descriptor has one `table` hook, so the first declared grid is the one
- * drawn and any after it are not. That is a gap in the chart's own contract
- * rather than a choice worth making here: there is no second hook to write to,
- * and merging two grids into one would put cells somewhere the script never
- * asked for.
- *
- * **What ought to happen is a refusal, and it cannot be written yet.** A study
- * whose second grid never appears is a study with no explanation, so the second
- * `table()` should be refused where it is written, naming the limit. Every
- * diagnostic in this project carries a catalogue code and the catalogue has
- * none for "the chart cannot draw something this study declares"; inventing one
- * here is the one thing that is not allowed, so the gap is reported instead, in
- * `issues/0011-a-second-declared-grid-is-dropped-with-nothing-said.md`, with the
- * sentence it should carry.
- *
- * Until it lands, the drop is at least no longer silent inside this repository:
- * it is recorded in `spec/chart-narrowings.json` with its reason, and
- * `scripts/check-chart-surface.mjs` fails the build if this adapter ever drops
- * anything else a compiled program declares without recording it there.
+ * The descriptor has one `table` hook, and merging two grids into it would put
+ * cells somewhere the script never asked for. So a program declaring a second
+ * grid never reaches this file: `undrawable.ts` refuses it before any bar runs,
+ * with OS6024, and this reads the one grid a program that runs can have.
+ * `spec/chart-narrowings.json` records the refusal and
+ * `scripts/check-chart-surface.mjs` proves it with a study that declares two.
  */
 import type { CompiledProgram, Grid as DeclaredGrid } from '../../core/emit/index.js';
 import type { Grid, GridCell } from '../../core/engine/index.js';

package/src/adapters/charts/undrawable.ts

@@ -0,0 +1,51 @@
+/**
+ * What this chart cannot draw of what a program declares, refused before a bar.
+ *
+ * `compiled-program.md` section 11: a host draws what its surface has room for,
+ * and refuses what it does not with OS6024 rather than drawing part of a study
+ * and saying nothing. Two things a version 1 program can declare have no place
+ * on this chart's surface, and both used to be dropped in silence.
+ *
+ * - **A second grid.** The descriptor has one `table` hook, so one grid reaches
+ *   a pane. Merging two into it would put cells somewhere the script never
+ *   asked for, and drawing the first alone is a study whose second panel never
+ *   appears and whose cells look broken.
+ * - **A band colour computed per bar.** The chart's band takes one colour for
+ *   the whole run and has no channel to point at, so a band whose colour the
+ *   script computes was drawn in the first plot's colour faded, which is a
+ *   colour the script did not choose.
+ *
+ * The compiled program carries no source position for a declaration, so the
+ * refusal names the declaration by its title, which is what a reader sees in
+ * the legend and the settings dialog, and its span is the load's own.
+ */
+import { diagnosticFor, makeSpan } from '../../core/index.js';
+import type { Diagnostic } from '../../core/index.js';
+import type { CompiledProgram, Field } from '../../core/emit/index.js';
+
+/** A load refusal has no line of its own: the program is what was refused. */
+const AT_LOAD = makeSpan(0, 0, 0, 0);
+
+export function undrawable(program: CompiledProgram): Diagnostic | undefined {
+  const second = program.outputs.tables[1];
+  if (second !== undefined) {
+    return diagnosticFor('OS6024', AT_LOAD, {
+      what: `the table ${titled(second.title, 'after the first')}, the second grid this study declares`,
+      limit: 'a chart pane draws one grid',
+    });
+  }
+  for (const band of program.outputs.fills) {
+    if (band.colorUpChannel !== null || band.colorDownChannel !== null) {
+      return diagnosticFor('OS6024', AT_LOAD, {
+        what: "a band's colour that is computed per bar",
+        limit: "a chart's band takes one colour for the whole run",
+      });
+    }
+  }
+  return undefined;
+}
+
+/** A title as a reader sees it, or a description where it is a setting's. */
+function titled(title: Field, otherwise: string): string {
+  return typeof title === 'string' ? `"${title}"` : otherwise;
+}